catalogmx 0.3.0__py3-none-any.whl

catalogmx/catalogs/inegi/municipios_completo.py

@@ -0,0 +1,236 @@
+"""
+INEGI - Catálogo Completo de Municipios Mexicanos
+
+Catálogo completo de todos los 2,469 municipios de México
+(2,462 municipios + 7 alcaldías CDMX)
+"""
+
+import json
+from pathlib import Path
+
+
+class MunicipiosCompletoCatalog:
+    """
+    Catálogo completo de municipios mexicanos.
+
+    Incluye todos los 2,469 municipios (2,462 municipios + 7 alcaldías CDMX)
+    con información demográfica completa.
+
+    WARNING: Este catálogo carga todos los municipios en memoria (~940KB).
+    Para consultas simples, considere usar MunicipiosCatalog en su lugar.
+
+    Características:
+    - 2,469 municipios totales
+    - Población total, masculina, femenina
+    - Viviendas habitadas
+    - Nombre de cabecera municipal
+    - Códigos INEGI completos
+
+    Ejemplo:
+        >>> from catalogmx.catalogs.inegi import MunicipiosCompletoCatalog
+        >>>
+        >>> # Obtener todos los municipios
+        >>> municipios = MunicipiosCompletoCatalog.get_all()
+        >>> print(f"Total municipios: {len(municipios)}")
+        >>>
+        >>> # Buscar municipio por código
+        >>> guadalajara = MunicipiosCompletoCatalog.get_municipio("14039")
+        >>> print(f"{guadalajara['nom_municipio']}: {guadalajara['poblacion_total']:,} habitantes")
+        >>>
+        >>> # Obtener municipios por estado
+        >>> jalisco = MunicipiosCompletoCatalog.get_by_entidad("14")
+        >>> print(f"Jalisco tiene {len(jalisco)} municipios")
+    """
+
+    _data: list[dict] | 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/inegi/municipios_completo.py
+        # Target: catalogmx/packages/shared-data/inegi/municipios_completo.json
+        data_path = (
+            Path(__file__).parent.parent.parent.parent.parent
+            / "shared-data"
+            / "inegi"
+            / "municipios_completo.json"
+        )
+
+        with open(data_path, encoding="utf-8") as f:
+            cls._data = json.load(f)
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """
+        Obtiene todos los municipios (2,469 total).
+
+        WARNING: Retorna todos los municipios en memoria.
+
+        Returns:
+            Lista completa de municipios
+
+        Ejemplo:
+            >>> municipios = MunicipiosCompletoCatalog.get_all()
+            >>> print(f"Total: {len(municipios)}")  # 2469
+        """
+        cls._load_data()
+        return cls._data.copy()  # type: ignore
+
+    @classmethod
+    def get_municipio(cls, cve_completa: str) -> dict | None:
+        """
+        Obtiene municipio por código completo (cve_completa).
+
+        Args:
+            cve_completa: Código completo de 5 dígitos (ej: "14039" para Guadalajara)
+
+        Returns:
+            Información del municipio o None si no existe
+
+        Ejemplo:
+            >>> mun = MunicipiosCompletoCatalog.get_municipio("14039")
+            >>> print(mun['nom_municipio'])  # "Guadalajara"
+        """
+        cls._load_data()
+        for mun in cls._data:  # type: ignore
+            if mun["cve_completa"] == cve_completa:
+                return mun
+        return None
+
+    @classmethod
+    def get_by_entidad(cls, cve_entidad: str) -> list[dict]:
+        """
+        Obtiene municipios por estado (cve_entidad).
+
+        Args:
+            cve_entidad: Código de entidad de 2 dígitos (ej: "14" para Jalisco)
+
+        Returns:
+            Lista de municipios del estado
+
+        Ejemplo:
+            >>> jalisco = MunicipiosCompletoCatalog.get_by_entidad("14")
+            >>> print(f"Jalisco: {len(jalisco)} municipios")
+        """
+        cls._load_data()
+        return [mun for mun in cls._data if mun["cve_entidad"] == cve_entidad]  # type: ignore
+
+    @classmethod
+    def search_by_name(cls, name: str) -> list[dict]:
+        """
+        Busca municipios por nombre (case-insensitive).
+
+        Args:
+            name: Nombre o parte del nombre a buscar
+
+        Returns:
+            Lista de municipios que coinciden
+
+        Ejemplo:
+            >>> san = MunicipiosCompletoCatalog.search_by_name("San")
+            >>> for mun in san[:5]:
+            ...     print(f"{mun['nom_municipio']}, {mun['nom_entidad']}")
+        """
+        cls._load_data()
+        search_term = name.upper()
+        return [
+            mun for mun in cls._data if search_term in mun["nom_municipio"].upper()  # type: ignore
+        ]
+
+    @classmethod
+    def get_by_state_name(cls, state_name: str) -> list[dict]:
+        """
+        Obtiene municipios por nombre de estado.
+
+        Args:
+            state_name: Nombre del estado (ej: "Jalisco", "CDMX")
+
+        Returns:
+            Lista de municipios del estado
+
+        Ejemplo:
+            >>> jalisco = MunicipiosCompletoCatalog.get_by_state_name("Jalisco")
+            >>> for mun in jalisco[:5]:
+            ...     print(mun['nom_municipio'])
+        """
+        cls._load_data()
+        search_term = state_name.upper()
+        return [
+            mun for mun in cls._data if mun["nom_entidad"].upper() == search_term  # type: ignore
+        ]
+
+    @classmethod
+    def get_count_by_entidad(cls, cve_entidad: str) -> int:
+        """
+        Obtiene el número de municipios en un estado.
+
+        Args:
+            cve_entidad: Código de entidad de 2 dígitos
+
+        Returns:
+            Número de municipios en el estado
+
+        Ejemplo:
+            >>> count = MunicipiosCompletoCatalog.get_count_by_entidad("14")
+            >>> print(f"Jalisco tiene {count} municipios")
+        """
+        return len(cls.get_by_entidad(cve_entidad))
+
+    @classmethod
+    def is_valid(cls, cve_completa: str) -> bool:
+        """
+        Valida código de municipio.
+
+        Args:
+            cve_completa: Código completo de 5 dígitos
+
+        Returns:
+            True si el código existe, False en caso contrario
+
+        Ejemplo:
+            >>> MunicipiosCompletoCatalog.is_valid("14039")  # True
+            >>> MunicipiosCompletoCatalog.is_valid("99999")  # False
+        """
+        return cls.get_municipio(cve_completa) is not None
+
+    @classmethod
+    def get_total_count(cls) -> int:
+        """
+        Obtiene el total de municipios.
+
+        Returns:
+            Número total de municipios (2,469)
+
+        Ejemplo:
+            >>> total = MunicipiosCompletoCatalog.get_total_count()
+            >>> print(f"Total municipios: {total}")  # 2469
+        """
+        cls._load_data()
+        return len(cls._data)  # type: ignore
+
+    @classmethod
+    def get_estadisticas(cls) -> dict[str, int]:
+        """
+        Obtiene estadísticas del catálogo.
+
+        Returns:
+            Diccionario con estadísticas de municipios
+
+        Ejemplo:
+            >>> stats = MunicipiosCompletoCatalog.get_estadisticas()
+            >>> print(f"Total municipios: {stats['total_municipios']}")
+            >>> print(f"Total estados: {stats['total_estados']}")
+        """
+        cls._load_data()
+
+        estados = {mun["cve_entidad"] for mun in cls._data}  # type: ignore
+        poblacion_total = sum(mun["poblacion_total"] for mun in cls._data)  # type: ignore
+
+        return {
+            "total_municipios": len(cls._data),  # type: ignore
+            "total_estados": len(estados),
+            "poblacion_total": poblacion_total,
+        }

catalogmx/catalogs/inegi/states.py

@@ -0,0 +1,148 @@
+"""
+Mexican States Catalog from INEGI
+
+This module provides access to the official catalog of Mexican states
+(entidades federativas) with their CURP codes, INEGI codes, and abbreviations.
+"""
+
+import json
+from pathlib import Path
+
+from catalogmx.utils.text import normalize_text
+
+
+class StateCatalog:
+    """
+    Catalog of Mexican states
+    """
+
+    _data: list[dict] | None = None
+    _state_by_code: dict[str, dict] | None = None
+    _state_by_name: dict[str, dict] | None = None
+    _state_by_name_normalized: dict[str, dict] | None = None
+    _state_by_inegi: dict[str, dict] | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        """Load state data from JSON file"""
+        if cls._data is None:
+            # Get path to shared data
+            current_file = Path(__file__)
+            shared_data_path = (
+                current_file.parent.parent.parent.parent.parent
+                / "shared-data"
+                / "inegi"
+                / "states.json"
+            )
+
+            with open(shared_data_path, encoding="utf-8") as f:
+                cls._data = json.load(f)
+
+            # Create lookup dictionaries
+            cls._state_by_code = {state["code"]: state for state in cls._data}
+            cls._state_by_name = {state["name"].upper(): state for state in cls._data}
+            cls._state_by_name_normalized = {
+                normalize_text(state["name"]): state for state in cls._data
+            }
+            cls._state_by_inegi = {state["clave_inegi"]: state for state in cls._data}
+
+            # Add aliases to name lookup
+            for state in cls._data:
+                if "aliases" in state:
+                    for alias in state["aliases"]:
+                        cls._state_by_name[alias.upper()] = state
+                        cls._state_by_name_normalized[normalize_text(alias)] = state
+
+    @classmethod
+    def get_all_states(cls) -> list[dict]:
+        """
+        Get all states in the catalog
+
+        :return: List of state dictionaries
+        """
+        cls._load_data()
+        return cls._data.copy()
+
+    @classmethod
+    def get_state_by_code(cls, code: str) -> dict | None:
+        """
+        Get state information by CURP code
+
+        :param code: 2-letter CURP state code (e.g., 'AS' for Aguascalientes)
+        :return: State dictionary or None if not found
+        """
+        cls._load_data()
+        return cls._state_by_code.get(code.upper())
+
+    @classmethod
+    def get_state_by_name(cls, name: str) -> dict | None:
+        """
+        Get state information by name (case and accent insensitive)
+
+        :param name: State name (case and accent insensitive)
+        :return: State dictionary or None if not found
+        """
+        cls._load_data()
+        return cls._state_by_name_normalized.get(normalize_text(name))
+
+    @classmethod
+    def get_state_by_inegi_code(cls, code: str) -> dict | None:
+        """
+        Get state information by INEGI code
+
+        :param code: 2-digit INEGI code (e.g., '01' for Aguascalientes)
+        :return: State dictionary or None if not found
+        """
+        cls._load_data()
+        code = str(code).zfill(2)
+        return cls._state_by_inegi.get(code)
+
+    @classmethod
+    def validate_state_code(cls, code: str) -> bool:
+        """
+        Validate if a state CURP code exists
+
+        :param code: 2-letter CURP state code
+        :return: True if exists, False otherwise
+        """
+        return cls.get_state_by_code(code) is not None
+
+    @classmethod
+    def get_state_codes(cls) -> dict[str, str]:
+        """
+        Get dictionary of state names to CURP codes
+
+        :return: Dictionary mapping state names to codes
+        """
+        cls._load_data()
+        return {state["name"]: state["code"] for state in cls._data}
+
+    @classmethod
+    def get_inegi_codes(cls) -> dict[str, str]:
+        """
+        Get dictionary of state names to INEGI codes
+
+        :return: Dictionary mapping state names to INEGI codes
+        """
+        cls._load_data()
+        return {state["name"]: state["clave_inegi"] for state in cls._data}
+
+
+# Convenience functions
+def get_states_dict() -> dict[str, dict]:
+    """Get dictionary of all states indexed by CURP code"""
+    StateCatalog._load_data()
+    return StateCatalog._state_by_code.copy()
+
+
+def get_state_names() -> list[str]:
+    """Get list of all state names"""
+    return [state["name"] for state in StateCatalog.get_all_states()]
+
+
+# Export commonly used functions
+__all__ = [
+    "StateCatalog",
+    "get_states_dict",
+    "get_state_names",
+]

catalogmx/catalogs/mexico/__init__.py

@@ -0,0 +1,17 @@
+"""
+Mexican National Catalogs
+
+This module provides access to various Mexican national catalogs.
+"""
+
+from .hoy_no_circula import HoyNoCirculaCatalog
+from .placas_formatos import PlacasFormatosCatalog
+from .salarios_minimos import SalariosMinimos
+from .uma import UMACatalog
+
+__all__ = [
+    "PlacasFormatosCatalog",
+    "SalariosMinimos",
+    "UMACatalog",
+    "HoyNoCirculaCatalog",
+]

catalogmx/catalogs/mexico/hoy_no_circula.py

@@ -0,0 +1,215 @@
+"""
+Hoy No Circula CDMX Catalog
+
+This module provides access to the Hoy No Circula traffic restriction program
+for Mexico City (CDMX) and Estado de México.
+"""
+
+import json
+from pathlib import Path
+
+
+class HoyNoCirculaCatalog:
+    """
+    Catalog for Hoy No Circula traffic restriction program
+
+    The Hoy No Circula program restricts vehicle circulation in Mexico City
+    and Estado de México based on the last digit of the license plate number
+    and the vehicle's verification hologram.
+    """
+
+    _data: dict | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        """Load Hoy No Circula data from JSON file"""
+        if cls._data is None:
+            # Path: catalogmx/packages/python/catalogmx/catalogs/mexico/hoy_no_circula.py
+            # Target: catalogmx/packages/shared-data/mexico/hoy_no_circula_cdmx.json
+            current_file = Path(__file__)
+            shared_data_path = (
+                current_file.parent.parent.parent.parent.parent
+                / "shared-data"
+                / "mexico"
+                / "hoy_no_circula_cdmx.json"
+            )
+
+            with open(shared_data_path, encoding="utf-8") as f:
+                cls._data = json.load(f)
+
+    @classmethod
+    def get_data(cls) -> dict:
+        """
+        Get all Hoy No Circula data
+
+        :return: Complete Hoy No Circula data dictionary
+        """
+        cls._load_data()
+        return cls._data.copy()
+
+    @classmethod
+    def get_restricciones(cls) -> list[dict]:
+        """
+        Get all restrictions by day of week
+
+        :return: List of restriction dictionaries
+        """
+        cls._load_data()
+        return cls._data.get("restricciones_por_dia", []).copy()
+
+    @classmethod
+    def get_restriccion_por_dia(cls, dia: str) -> dict | None:
+        """
+        Get restriction for a specific day of week
+
+        :param dia: Day of week (e.g., 'lunes', 'martes')
+        :return: Restriction dictionary or None if not found
+        """
+        cls._load_data()
+        restricciones = cls._data.get("restricciones_por_dia", [])
+
+        for restriccion in restricciones:
+            if restriccion.get("dia", "").lower() == dia.lower():
+                return restriccion.copy()
+
+        return None
+
+    @classmethod
+    def get_exenciones(cls) -> list[dict]:
+        """
+        Get all exemptions by hologram type
+
+        :return: List of exemption dictionaries
+        """
+        cls._load_data()
+        return cls._data.get("exenciones_por_holograma", []).copy()
+
+    @classmethod
+    def get_exencion_por_holograma(cls, holograma: str) -> dict | None:
+        """
+        Get exemption information for a specific hologram
+
+        :param holograma: Hologram type (e.g., '00', '0', '1', '2')
+        :return: Exemption dictionary or None if not found
+        """
+        cls._load_data()
+        exenciones = cls._data.get("exenciones_por_holograma", [])
+
+        for exencion in exenciones:
+            if exencion.get("holograma") == holograma:
+                return exencion.copy()
+
+        return None
+
+    @classmethod
+    def puede_circular(cls, terminacion: str, dia: str, holograma: str = "2") -> bool:
+        """
+        Check if a vehicle can circulate on a given day
+
+        :param terminacion: Last digit of license plate (0-9)
+        :param dia: Day of week ('lunes', 'martes', 'miércoles', 'jueves', 'viernes', 'sábado')
+        :param holograma: Verification hologram ('00', '0', '1', '2')
+        :return: True if can circulate, False otherwise
+        """
+        cls._load_data()
+
+        # Check exemption by hologram first
+        exencion = cls.get_exencion_por_holograma(holograma)
+        if exencion:
+            # Hologram 00 and 0 can circulate all days (except Saturdays for 0)
+            if holograma == "00":
+                return True
+            elif holograma == "0":
+                return dia.lower() != "sábado"
+
+        # Check restriction for the day
+        restriccion = cls.get_restriccion_por_dia(dia)
+        if not restriccion:
+            # No restriction for this day (e.g., Sunday)
+            return True
+
+        # Check if the termination is restricted
+        terminaciones_restringidas = restriccion.get("terminacion_placa", [])
+        return str(terminacion) not in [str(t) for t in terminaciones_restringidas]
+
+    @classmethod
+    def get_dia_restriccion(cls, terminacion: str) -> str | None:
+        """
+        Get the day of week when a vehicle is restricted (for hologram 2)
+
+        :param terminacion: Last digit of license plate (0-9)
+        :return: Day of week when restricted or None if not restricted
+        """
+        cls._load_data()
+
+        restricciones = cls._data.get("restricciones_por_dia", [])
+        for restriccion in restricciones:
+            terminaciones = restriccion.get("terminacion_placa", [])
+            if str(terminacion) in [str(t) for t in terminaciones]:
+                return restriccion.get("dia")
+
+        return None
+
+    @classmethod
+    def get_engomado(cls, terminacion: str) -> str | None:
+        """
+        Get the engomado (sticker color) for a license plate termination
+
+        :param terminacion: Last digit of license plate (0-9)
+        :return: Engomado color or None if not found
+        """
+        cls._load_data()
+
+        restricciones = cls._data.get("restricciones_por_dia", [])
+        for restriccion in restricciones:
+            terminaciones = restriccion.get("terminacion_placa", [])
+            if str(terminacion) in [str(t) for t in terminaciones]:
+                engomados = restriccion.get("engomado", [])
+                return engomados[0] if engomados else None
+
+        return None
+
+    @classmethod
+    def get_contingencias(cls) -> dict:
+        """
+        Get contingency program information
+
+        :return: Dictionary with environmental contingency rules
+        """
+        cls._load_data()
+        return cls._data.get("contingencias_ambientales", {}).copy()
+
+    @classmethod
+    def get_sabatinos(cls) -> dict:
+        """
+        Get Saturday restriction information
+
+        :return: Dictionary with Saturday restriction rules
+        """
+        cls._load_data()
+        return cls._data.get("sabatinos", {}).copy()
+
+
+# Convenience functions
+def puede_circular(terminacion: str, dia: str, holograma: str = "2") -> bool:
+    """Check if a vehicle can circulate on a given day"""
+    return HoyNoCirculaCatalog.puede_circular(terminacion, dia, holograma)
+
+
+def get_dia_restriccion(terminacion: str) -> str | None:
+    """Get the day when a vehicle is restricted"""
+    return HoyNoCirculaCatalog.get_dia_restriccion(terminacion)
+
+
+def get_engomado(terminacion: str) -> str | None:
+    """Get the engomado color for a license plate termination"""
+    return HoyNoCirculaCatalog.get_engomado(terminacion)
+
+
+# Export commonly used functions and classes
+__all__ = [
+    "HoyNoCirculaCatalog",
+    "puede_circular",
+    "get_dia_restriccion",
+    "get_engomado",
+]