catalogmx 0.3.0__py3-none-any.whl

catalogmx/catalogs/ift/operadores_moviles.py

@@ -0,0 +1,315 @@
+"""
+Catálogo de operadores de telefonía móvil en México (IFT)
+
+Este módulo proporciona acceso al catálogo de operadores móviles
+registrados ante el Instituto Federal de Telecomunicaciones (IFT).
+"""
+
+import json
+from pathlib import Path
+from typing import TypedDict
+
+
+class OperadorMovil(TypedDict):
+    """Estructura de un operador móvil"""
+
+    nombre_comercial: str
+    razon_social: str
+    tipo: str  # OMR (Operador Móvil con Red) | OMV (Operador Móvil Virtual)
+    grupo_empresarial: str
+    tecnologias: list[str]  # 2G, 3G, 4G, 5G
+    cobertura: str  # nacional | regional
+    servicios: list[str]  # prepago, postpago, datos
+    market_share_aprox: float
+    fecha_inicio_operaciones: str
+    activo: bool
+
+
+class OperadoresMovilesCatalog:
+    """
+    Catálogo de operadores de telefonía móvil en México.
+
+    Incluye operadores móviles con red propia (OMR) y operadores móviles
+    virtuales (OMV).
+
+    Características:
+    - Operadores activos e históricos
+    - Información de tecnologías (2G, 3G, 4G, 5G)
+    - Market share aproximado
+    - Clasificación por tipo (OMR/OMV)
+    - Cobertura (nacional/regional)
+
+    Ejemplo:
+        >>> from catalogmx.catalogs.ift import OperadoresMovilesCatalog
+        >>>
+        >>> # Obtener operadores activos
+        >>> activos = OperadoresMovilesCatalog.get_activos()
+        >>> for op in activos:
+        ...     print(f"{op['nombre_comercial']}: {op['market_share_aprox']}%")
+        >>>
+        >>> # Buscar por nombre
+        >>> telcel = OperadoresMovilesCatalog.buscar_por_nombre("Telcel")
+        >>> print(telcel['razon_social'])
+    """
+
+    _data: list[OperadorMovil] | None = None
+    _by_nombre: dict[str, OperadorMovil] | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        """Carga lazy de datos desde JSON"""
+        if cls._data is not None:
+            return
+
+        # Path: catalogmx/packages/python/catalogmx/catalogs/ift/operadores_moviles.py
+        # Target: catalogmx/packages/shared-data/ift/operadores_moviles.json
+        data_path = (
+            Path(__file__).parent.parent.parent.parent.parent
+            / "shared-data"
+            / "ift"
+            / "operadores_moviles.json"
+        )
+
+        with open(data_path, encoding="utf-8") as f:
+            json_data = json.load(f)
+            cls._data = json_data["operadores"]
+
+        # Índice por nombre comercial
+        cls._by_nombre = {item["nombre_comercial"].lower(): item for item in cls._data}
+
+    @classmethod
+    def get_all(cls) -> list[OperadorMovil]:
+        """
+        Obtiene todos los operadores móviles.
+
+        Returns:
+            Lista completa de operadores
+
+        Ejemplo:
+            >>> operadores = OperadoresMovilesCatalog.get_all()
+            >>> print(f"Total operadores: {len(operadores)}")
+        """
+        cls._load_data()
+        return cls._data.copy()  # type: ignore
+
+    @classmethod
+    def get_activos(cls) -> list[OperadorMovil]:
+        """
+        Obtiene solo operadores activos.
+
+        Returns:
+            Lista de operadores actualmente operando
+
+        Ejemplo:
+            >>> activos = OperadoresMovilesCatalog.get_activos()
+            >>> for op in activos:
+            ...     print(f"{op['nombre_comercial']} ({op['tipo']})")
+        """
+        cls._load_data()
+        return [op for op in cls._data if op["activo"]]  # type: ignore
+
+    @classmethod
+    def get_inactivos(cls) -> list[OperadorMovil]:
+        """
+        Obtiene operadores que dejaron de operar.
+
+        Returns:
+            Lista de operadores inactivos
+
+        Ejemplo:
+            >>> inactivos = OperadoresMovilesCatalog.get_inactivos()
+            >>> print(f"Operadores históricos: {len(inactivos)}")
+        """
+        cls._load_data()
+        return [op for op in cls._data if not op["activo"]]  # type: ignore
+
+    @classmethod
+    def buscar_por_nombre(cls, nombre: str) -> OperadorMovil | None:
+        """
+        Busca un operador por nombre comercial.
+
+        Args:
+            nombre: Nombre comercial del operador (ej: "Telcel", "AT&T")
+
+        Returns:
+            Información del operador o None si no existe
+
+        Ejemplo:
+            >>> telcel = OperadoresMovilesCatalog.buscar_por_nombre("Telcel")
+            >>> if telcel:
+            ...     print(f"Razón social: {telcel['razon_social']}")
+            ...     print(f"Market share: {telcel['market_share_aprox']}%")
+        """
+        cls._load_data()
+        nombre_lower = nombre.lower()
+
+        # Búsqueda exacta
+        exact = cls._by_nombre.get(nombre_lower)  # type: ignore
+        if exact:
+            return exact
+
+        # Búsqueda parcial
+        for op in cls._data:  # type: ignore
+            if nombre_lower in op["nombre_comercial"].lower():
+                return op
+
+        return None
+
+    @classmethod
+    def get_por_tipo(cls, tipo: str) -> list[OperadorMovil]:
+        """
+        Obtiene operadores por tipo.
+
+        Args:
+            tipo: "OMR" (con red propia) o "OMV" (virtual)
+
+        Returns:
+            Lista de operadores del tipo especificado
+
+        Ejemplo:
+            >>> omr = OperadoresMovilesCatalog.get_por_tipo("OMR")
+            >>> print(f"Operadores con red propia: {len(omr)}")
+            >>>
+            >>> omv = OperadoresMovilesCatalog.get_por_tipo("OMV")
+            >>> print(f"Operadores virtuales: {len(omv)}")
+        """
+        cls._load_data()
+        tipo_upper = tipo.upper()
+        return [op for op in cls._data if op["tipo"] == tipo_upper]  # type: ignore
+
+    @classmethod
+    def get_con_tecnologia(cls, tecnologia: str) -> list[OperadorMovil]:
+        """
+        Obtiene operadores que soportan una tecnología específica.
+
+        Args:
+            tecnologia: "2G", "3G", "4G", "5G"
+
+        Returns:
+            Lista de operadores con la tecnología
+
+        Ejemplo:
+            >>> con_5g = OperadoresMovilesCatalog.get_con_tecnologia("5G")
+            >>> for op in con_5g:
+            ...     print(f"{op['nombre_comercial']} tiene 5G")
+        """
+        cls._load_data()
+        tecnologia_upper = tecnologia.upper()
+        return [op for op in cls._data if tecnologia_upper in op["tecnologias"]]  # type: ignore
+
+    @classmethod
+    def get_por_cobertura(cls, cobertura: str) -> list[OperadorMovil]:
+        """
+        Obtiene operadores por tipo de cobertura.
+
+        Args:
+            cobertura: "nacional" o "regional"
+
+        Returns:
+            Lista de operadores con ese tipo de cobertura
+
+        Ejemplo:
+            >>> nacionales = OperadoresMovilesCatalog.get_por_cobertura("nacional")
+            >>> print(f"Operadores con cobertura nacional: {len(nacionales)}")
+        """
+        cls._load_data()
+        cobertura_lower = cobertura.lower()
+        return [op for op in cls._data if op["cobertura"] == cobertura_lower]  # type: ignore
+
+    @classmethod
+    def get_por_grupo(cls, grupo: str) -> list[OperadorMovil]:
+        """
+        Obtiene operadores de un grupo empresarial.
+
+        Args:
+            grupo: Nombre del grupo empresarial
+
+        Returns:
+            Lista de operadores del grupo
+
+        Ejemplo:
+            >>> america_movil = OperadoresMovilesCatalog.get_por_grupo("América Móvil")
+            >>> for op in america_movil:
+            ...     print(op['nombre_comercial'])
+        """
+        cls._load_data()
+        grupo_lower = grupo.lower()
+        return [
+            op
+            for op in cls._data  # type: ignore
+            if "grupo_empresarial" in op and grupo_lower in op["grupo_empresarial"].lower()
+        ]
+
+    @classmethod
+    def get_con_servicio(cls, servicio: str) -> list[OperadorMovil]:
+        """
+        Obtiene operadores que ofrecen un servicio específico.
+
+        Args:
+            servicio: "prepago", "postpago", "datos"
+
+        Returns:
+            Lista de operadores con el servicio
+
+        Ejemplo:
+            >>> prepago = OperadoresMovilesCatalog.get_con_servicio("prepago")
+            >>> print(f"Operadores con prepago: {len(prepago)}")
+        """
+        cls._load_data()
+        servicio_lower = servicio.lower()
+        return [op for op in cls._data if servicio_lower in op["servicios"]]  # type: ignore
+
+    @classmethod
+    def get_top_por_market_share(cls, limit: int = 5) -> list[OperadorMovil]:
+        """
+        Obtiene los operadores con mayor market share.
+
+        Args:
+            limit: Número de operadores a retornar (default: 5)
+
+        Returns:
+            Lista de top operadores ordenados por market share
+
+        Ejemplo:
+            >>> top3 = OperadoresMovilesCatalog.get_top_por_market_share(3)
+            >>> for i, op in enumerate(top3, 1):
+            ...     print(f"{i}. {op['nombre_comercial']}: {op['market_share_aprox']}%")
+        """
+        cls._load_data()
+        sorted_ops = sorted(
+            [op for op in cls._data if op["activo"]],  # type: ignore
+            key=lambda x: x["market_share_aprox"],
+            reverse=True,
+        )
+        return sorted_ops[:limit]
+
+    @classmethod
+    def get_estadisticas(cls) -> dict[str, int | float | list]:
+        """
+        Obtiene estadísticas del catálogo.
+
+        Returns:
+            Diccionario con estadísticas
+
+        Ejemplo:
+            >>> stats = OperadoresMovilesCatalog.get_estadisticas()
+            >>> print(f"Total operadores: {stats['total_operadores']}")
+            >>> print(f"Activos: {stats['operadores_activos']}")
+            >>> print(f"Con 5G: {stats['operadores_con_5g']}")
+        """
+        cls._load_data()
+
+        activos = cls.get_activos()
+        con_5g = cls.get_con_tecnologia("5G")
+
+        return {
+            "total_operadores": len(cls._data),  # type: ignore
+            "operadores_activos": len(activos),
+            "operadores_inactivos": len(cls.get_inactivos()),
+            "omr_count": len(cls.get_por_tipo("OMR")),
+            "omv_count": len(cls.get_por_tipo("OMV")),
+            "operadores_con_5g": len(con_5g),
+            "cobertura_nacional": len(cls.get_por_cobertura("nacional")),
+            "market_share_total": sum(op["market_share_aprox"] for op in activos),
+            "tecnologias_disponibles": ["2G", "3G", "4G", "5G"],
+        }

catalogmx/catalogs/inegi/__init__.py

@@ -0,0 +1,21 @@
+"""
+Catálogos INEGI
+
+Catálogos incluidos:
+- MunicipiosCatalog: Municipios de México
+- MunicipiosCompletoCatalog: Catálogo completo de 2,469 municipios
+- LocalidadesCatalog: Localidades con 1,000+ habitantes
+- StateCatalog: Estados de México
+"""
+
+from .localidades import LocalidadesCatalog
+from .municipios import MunicipiosCatalog
+from .municipios_completo import MunicipiosCompletoCatalog
+from .states import StateCatalog
+
+__all__ = [
+    "MunicipiosCatalog",
+    "MunicipiosCompletoCatalog",
+    "LocalidadesCatalog",
+    "StateCatalog",
+]

catalogmx/catalogs/inegi/localidades.py

@@ -0,0 +1,207 @@
+"""Catálogo de Localidades INEGI (filtrado por población)"""
+
+import json
+from pathlib import Path
+
+from catalogmx.utils.text import normalize_text
+
+
+class LocalidadesCatalog:
+    """
+    Catálogo de localidades de México con 1,000+ habitantes.
+
+    Incluye:
+    - 10,635 localidades con población >= 1,000 habitantes
+    - Coordenadas GPS (latitud, longitud)
+    - Población y viviendas habitadas
+    - Clasificación urbano/rural
+    """
+
+    _data: list[dict] | None = None
+    _by_cvegeo: dict[str, dict] | None = None
+    _by_municipio: dict[str, list[dict]] | None = None
+    _by_entidad: dict[str, list[dict]] | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        if cls._data is None:
+            # Path: catalogmx/packages/python/catalogmx/catalogs/inegi/localidades.py
+            # Target: catalogmx/packages/shared-data/inegi/localidades.json
+            path = (
+                Path(__file__).parent.parent.parent.parent.parent
+                / "shared-data"
+                / "inegi"
+                / "localidades.json"
+            )
+            with open(path, encoding="utf-8") as f:
+                cls._data = json.load(f)
+
+            # Crear índices
+            cls._by_cvegeo = {item["cvegeo"]: item for item in cls._data}
+
+            # Índice por municipio
+            cls._by_municipio = {}
+            for item in cls._data:
+                cve_mun = item["cve_municipio"]
+                if cve_mun not in cls._by_municipio:
+                    cls._by_municipio[cve_mun] = []
+                cls._by_municipio[cve_mun].append(item)
+
+            # Índice por entidad
+            cls._by_entidad = {}
+            for item in cls._data:
+                cve_ent = item["cve_entidad"]
+                if cve_ent not in cls._by_entidad:
+                    cls._by_entidad[cve_ent] = []
+                cls._by_entidad[cve_ent].append(item)
+
+    @classmethod
+    def get_localidad(cls, cvegeo: str) -> dict | None:
+        """
+        Obtiene una localidad por su clave geoestadística (CVEGEO).
+
+        Args:
+            cvegeo: Clave geoestadística (ej: "010010001")
+
+        Returns:
+            Diccionario con datos de la localidad o None si no existe
+        """
+        cls._load_data()
+        return cls._by_cvegeo.get(cvegeo)
+
+    @classmethod
+    def is_valid(cls, cvegeo: str) -> bool:
+        """Verifica si una clave geoestadística existe"""
+        return cls.get_localidad(cvegeo) is not None
+
+    @classmethod
+    def get_by_municipio(cls, cve_municipio: str) -> list[dict]:
+        """
+        Obtiene todas las localidades de un municipio.
+
+        Args:
+            cve_municipio: Código del municipio (ej: "001")
+
+        Returns:
+            Lista de localidades del municipio
+        """
+        cls._load_data()
+        return cls._by_municipio.get(cve_municipio, []).copy()
+
+    @classmethod
+    def get_by_entidad(cls, cve_entidad: str) -> list[dict]:
+        """
+        Obtiene todas las localidades de un estado.
+
+        Args:
+            cve_entidad: Código del estado (ej: "01")
+
+        Returns:
+            Lista de localidades del estado
+        """
+        cls._load_data()
+        cve_ent = cve_entidad.zfill(2)
+        return cls._by_entidad.get(cve_ent, []).copy()
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """Obtiene todas las localidades"""
+        cls._load_data()
+        return cls._data.copy()
+
+    @classmethod
+    def get_urbanas(cls) -> list[dict]:
+        """Obtiene solo localidades urbanas"""
+        cls._load_data()
+        return [loc for loc in cls._data if loc["ambito"] == "U"]
+
+    @classmethod
+    def get_rurales(cls) -> list[dict]:
+        """Obtiene solo localidades rurales"""
+        cls._load_data()
+        return [loc for loc in cls._data if loc["ambito"] == "R"]
+
+    @classmethod
+    def search_by_name(cls, nombre: str) -> list[dict]:
+        """
+        Busca localidades por nombre (búsqueda parcial, insensible a acentos).
+
+        Args:
+            nombre: Nombre o parte del nombre a buscar
+
+        Returns:
+            Lista de localidades que coinciden
+
+        Ejemplo:
+            >>> # Búsqueda con o sin acentos funciona igual
+            >>> locs = LocalidadesCatalog.search_by_name("san jose")
+            >>> locs = LocalidadesCatalog.search_by_name("san josé")  # mismo resultado
+        """
+        cls._load_data()
+        nombre_normalized = normalize_text(nombre)
+        return [
+            loc for loc in cls._data if nombre_normalized in normalize_text(loc["nom_localidad"])
+        ]
+
+    @classmethod
+    def get_by_coordinates(cls, lat: float, lon: float, radio_km: float = 10) -> list[dict]:
+        """
+        Busca localidades cercanas a unas coordenadas.
+
+        Args:
+            lat: Latitud
+            lon: Longitud
+            radio_km: Radio de búsqueda en kilómetros (default: 10)
+
+        Returns:
+            Lista de localidades dentro del radio, ordenadas por distancia
+        """
+        from math import atan2, cos, radians, sin, sqrt
+
+        cls._load_data()
+
+        def distancia_haversine(lat1, lon1, lat2, lon2):
+            """Calcula distancia en km entre dos puntos GPS"""
+            R = 6371  # Radio de la Tierra en km
+
+            dlat = radians(lat2 - lat1)
+            dlon = radians(lon2 - lon1)
+
+            a = sin(dlat / 2) ** 2 + cos(radians(lat1)) * cos(radians(lat2)) * sin(dlon / 2) ** 2
+            c = 2 * atan2(sqrt(a), sqrt(1 - a))
+
+            return R * c
+
+        resultados = []
+        for loc in cls._data:
+            if loc["latitud"] is None or loc["longitud"] is None:
+                continue
+
+            distancia = distancia_haversine(lat, lon, loc["latitud"], loc["longitud"])
+            if distancia <= radio_km:
+                loc_con_distancia = loc.copy()
+                loc_con_distancia["distancia_km"] = round(distancia, 2)
+                resultados.append(loc_con_distancia)
+
+        # Ordenar por distancia
+        resultados.sort(key=lambda x: x["distancia_km"])
+        return resultados
+
+    @classmethod
+    def get_by_population_range(cls, min_pob: int, max_pob: int | None = None) -> list[dict]:
+        """
+        Obtiene localidades en un rango de población.
+
+        Args:
+            min_pob: Población mínima
+            max_pob: Población máxima (None para sin límite)
+
+        Returns:
+            Lista de localidades en el rango
+        """
+        cls._load_data()
+
+        if max_pob is None:
+            return [loc for loc in cls._data if loc["poblacion_total"] >= min_pob]
+        else:
+            return [loc for loc in cls._data if min_pob <= loc["poblacion_total"] <= max_pob]

catalogmx/catalogs/inegi/municipios.py

@@ -0,0 +1,73 @@
+"""Catálogo de Municipios INEGI"""
+
+import json
+from pathlib import Path
+
+from catalogmx.utils.text import normalize_text
+
+
+class MunicipiosCatalog:
+    _data: list[dict] | None = None
+    _by_cve_completa: dict[str, dict] | None = None
+    _by_entidad: dict[str, list[dict]] | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        if cls._data is None:
+            # Path: catalogmx/packages/python/catalogmx/catalogs/inegi/municipios.py
+            # Target: catalogmx/packages/shared-data/inegi/municipios_completo.json
+            path = (
+                Path(__file__).parent.parent.parent.parent.parent
+                / "shared-data"
+                / "inegi"
+                / "municipios_completo.json"
+            )
+            with open(path, encoding="utf-8") as f:
+                cls._data = json.load(f)
+
+            cls._by_cve_completa = {item["cve_completa"]: item for item in cls._data}
+
+            # Index by entidad
+            cls._by_entidad = {}
+            for item in cls._data:
+                entidad = item["cve_entidad"]
+                if entidad not in cls._by_entidad:
+                    cls._by_entidad[entidad] = []
+                cls._by_entidad[entidad].append(item)
+
+    @classmethod
+    def get_municipio(cls, cve_completa: str) -> dict | None:
+        """Obtiene municipio por clave completa (5 dígitos)"""
+        cls._load_data()
+        return cls._by_cve_completa.get(cve_completa)
+
+    @classmethod
+    def get_by_entidad(cls, cve_entidad: str) -> list[dict]:
+        """Obtiene todos los municipios de una entidad"""
+        cls._load_data()
+        return cls._by_entidad.get(cve_entidad, [])
+
+    @classmethod
+    def is_valid(cls, cve_completa: str) -> bool:
+        """Verifica si una clave de municipio es válida"""
+        return cls.get_municipio(cve_completa) is not None
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """Obtiene todos los municipios"""
+        cls._load_data()
+        return cls._data.copy()
+
+    @classmethod
+    def search_by_name(cls, nombre: str) -> list[dict]:
+        """
+        Busca municipios por nombre (búsqueda parcial, insensible a acentos).
+
+        Ejemplo:
+            >>> # Ambas búsquedas funcionan igual
+            >>> munis = MunicipiosCatalog.search_by_name("leon")
+            >>> munis = MunicipiosCatalog.search_by_name("león")  # mismo resultado
+        """
+        cls._load_data()
+        nombre_normalized = normalize_text(nombre)
+        return [m for m in cls._data if nombre_normalized in normalize_text(m["nom_municipio"])]