catalogmx 0.3.0__py3-none-any.whl

catalogmx/catalogs/mexico/placas_formatos.py

@@ -0,0 +1,184 @@
+"""
+Mexican License Plates Formats Catalog
+
+This module provides validation patterns and formats for Mexican vehicle license plates
+according to NOM-001-SCT-2-2016.
+"""
+
+import json
+import re
+from pathlib import Path
+
+
+class PlacasFormatosCatalog:
+    """
+    Catalog of Mexican license plate formats
+
+    Provides validation and detection for 35 official vehicle plate formats
+    defined by NOM-001-SCT-2-2016.
+    """
+
+    _data: list[dict] | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        """Load license plate formats from JSON file"""
+        if cls._data is None:
+            # Path: catalogmx/packages/python/catalogmx/catalogs/mexico/placas_formatos.py
+            # Target: catalogmx/packages/shared-data/mexico/placas_formatos.json
+            current_file = Path(__file__)
+            shared_data_path = (
+                current_file.parent.parent.parent.parent.parent
+                / "shared-data"
+                / "mexico"
+                / "placas_formatos.json"
+            )
+
+            with open(shared_data_path, encoding="utf-8") as f:
+                cls._data = json.load(f)
+
+    @classmethod
+    def get_data(cls) -> list[dict]:
+        """
+        Get all license plate formats
+
+        :return: List of all plate format dictionaries
+        """
+        cls._load_data()
+        return cls._data.copy()
+
+    @classmethod
+    def validate_placa(cls, placa: str) -> bool:
+        """
+        Validate a license plate against all known active formats
+
+        :param placa: License plate string to validate
+        :return: True if valid, False otherwise
+        """
+        cls._load_data()
+        normalized_placa = placa.upper().strip()
+
+        for formato in cls._data:
+            if formato.get("activo", True):
+                pattern = formato["pattern"]
+                if re.match(pattern, normalized_placa):
+                    return True
+
+        return False
+
+    @classmethod
+    def get_formatos_por_estado(cls, estado: str) -> list[dict]:
+        """
+        Get all formats for a specific state
+
+        :param estado: State name (e.g., 'Jalisco', 'Nacional')
+        :return: List of formats for the state
+        """
+        cls._load_data()
+        estado_lower = estado.lower()
+
+        return [
+            f
+            for f in cls._data
+            if estado_lower in f["estado"].lower() or estado_lower == "nacional"
+        ]
+
+    @classmethod
+    def get_formatos_por_tipo(cls, tipo: str) -> list[dict]:
+        """
+        Get all active formats by type
+
+        :param tipo: Plate type (e.g., 'particular', 'diplomatico', 'militar_ejercito')
+        :return: List of formats of the specified type
+        """
+        cls._load_data()
+
+        return [f for f in cls._data if f.get("tipo") == tipo and f.get("activo", True)]
+
+    @classmethod
+    def detect_formato(cls, placa: str) -> dict | None:
+        """
+        Detect the format of a given license plate
+
+        :param placa: License plate string
+        :return: Format dictionary if detected, None otherwise
+        """
+        cls._load_data()
+        normalized_placa = placa.upper().strip()
+
+        for formato in cls._data:
+            pattern = formato["pattern"]
+            if re.match(pattern, normalized_placa):
+                return formato.copy()
+
+        return None
+
+    @classmethod
+    def get_formatos_activos(cls) -> list[dict]:
+        """
+        Get all active formats
+
+        :return: List of active plate formats
+        """
+        cls._load_data()
+
+        return [f for f in cls._data if f.get("activo", True)]
+
+    @classmethod
+    def is_diplomatica(cls, placa: str) -> bool:
+        """
+        Check if a plate is diplomatic
+
+        :param placa: License plate string
+        :return: True if diplomatic, False otherwise
+        """
+        formato = cls.detect_formato(placa)
+        return formato.get("tipo") == "diplomatico" if formato else False
+
+    @classmethod
+    def is_federal(cls, placa: str) -> bool:
+        """
+        Check if a plate is federal (government, military, or federal service)
+
+        :param placa: License plate string
+        :return: True if federal, False otherwise
+        """
+        formato = cls.detect_formato(placa)
+        if not formato:
+            return False
+
+        tipo = formato.get("tipo")
+        federal_types = [
+            "gobierno_federal",
+            "servicio_publico_federal",
+            "carga_federal",
+            "policia_federal",
+            "remolque_federal",
+        ]
+
+        return tipo in federal_types
+
+
+# Convenience functions for direct access
+def validate_placa(placa: str) -> bool:
+    """Validate a license plate"""
+    return PlacasFormatosCatalog.validate_placa(placa)
+
+
+def detect_formato(placa: str) -> dict | None:
+    """Detect the format of a license plate"""
+    return PlacasFormatosCatalog.detect_formato(placa)
+
+
+def get_formatos_activos() -> list[dict]:
+    """Get all active plate formats"""
+    return PlacasFormatosCatalog.get_formatos_activos()
+
+
+# Export commonly used functions and classes
+__all__ = [
+    "PlacasFormatosCatalog",
+    "validate_placa",
+    "detect_formato",
+    "get_formatos_activos",
+]

catalogmx/catalogs/mexico/salarios_minimos.py

@@ -0,0 +1,156 @@
+"""
+Mexican Minimum Wage Catalog
+
+This module provides access to historical minimum wage data for Mexico.
+"""
+
+import json
+from pathlib import Path
+
+
+class SalariosMinimos:
+    """
+    Catalog of Mexican minimum wages
+
+    Provides historical minimum wage data from 2010 to present,
+    with separate values for border zone and rest of country.
+    """
+
+    _data: list[dict] | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        """Load minimum wage data from JSON file"""
+        if cls._data is None:
+            # Path: catalogmx/packages/python/catalogmx/catalogs/mexico/salarios_minimos.py
+            # Target: catalogmx/packages/shared-data/mexico/salarios_minimos.json
+            current_file = Path(__file__)
+            shared_data_path = (
+                current_file.parent.parent.parent.parent.parent
+                / "shared-data"
+                / "mexico"
+                / "salarios_minimos.json"
+            )
+
+            with open(shared_data_path, encoding="utf-8") as f:
+                cls._data = json.load(f)
+
+    @classmethod
+    def get_data(cls) -> list[dict]:
+        """
+        Get all minimum wage data
+
+        :return: List of all minimum wage records
+        """
+        cls._load_data()
+        return cls._data.copy()
+
+    @classmethod
+    def get_por_anio(cls, anio: int) -> dict | None:
+        """
+        Get minimum wage for a specific year
+
+        :param anio: Year (e.g., 2024)
+        :return: Minimum wage record or None if not found
+        """
+        cls._load_data()
+
+        for record in cls._data:
+            if record["año"] == anio:
+                return record.copy()
+
+        return None
+
+    @classmethod
+    def get_actual(cls) -> dict | None:
+        """
+        Get current minimum wage (latest year in data)
+
+        :return: Latest minimum wage record
+        """
+        cls._load_data()
+
+        if not cls._data:
+            return None
+
+        # Data is sorted by year descending, so first element is most recent
+        return cls._data[0].copy()
+
+    @classmethod
+    def calcular_mensual(cls, diario: float, dias: int = 30) -> float:
+        """
+        Calculate monthly wage from daily wage
+
+        :param diario: Daily wage amount
+        :param dias: Number of days (default 30)
+        :return: Monthly wage
+        """
+        return diario * dias
+
+    @classmethod
+    def calcular_anual(cls, diario: float, dias: int = 365) -> float:
+        """
+        Calculate annual wage from daily wage
+
+        :param diario: Daily wage amount
+        :param dias: Number of days (default 365)
+        :return: Annual wage
+        """
+        return diario * dias
+
+    @classmethod
+    def get_por_zona(cls, anio: int, zona_frontera: bool = False) -> float | None:
+        """
+        Get minimum wage for specific zone and year
+
+        :param anio: Year
+        :param zona_frontera: True for border zone, False for rest of country
+        :return: Daily wage amount or None if not found
+        """
+        record = cls.get_por_anio(anio)
+        if not record:
+            return None
+
+        if zona_frontera:
+            return record.get("zona_frontera_norte")
+        else:
+            return record.get("resto_pais")
+
+    @classmethod
+    def get_incremento(cls, anio: int) -> float | None:
+        """
+        Get percentage increment for a specific year
+
+        :param anio: Year
+        :return: Percentage increment or None if not found
+        """
+        record = cls.get_por_anio(anio)
+        if not record:
+            return None
+
+        return record.get("incremento_porcentual")
+
+
+# Convenience functions
+def get_salario_actual() -> dict | None:
+    """Get current minimum wage"""
+    return SalariosMinimos.get_actual()
+
+
+def get_salario_por_anio(anio: int) -> dict | None:
+    """Get minimum wage for a specific year"""
+    return SalariosMinimos.get_por_anio(anio)
+
+
+def calcular_mensual(diario: float, dias: int = 30) -> float:
+    """Calculate monthly wage from daily wage"""
+    return SalariosMinimos.calcular_mensual(diario, dias)
+
+
+# Export commonly used functions and classes
+__all__ = [
+    "SalariosMinimos",
+    "get_salario_actual",
+    "get_salario_por_anio",
+    "calcular_mensual",
+]

catalogmx/catalogs/mexico/uma.py

@@ -0,0 +1,207 @@
+"""
+UMA (Unidad de Medida y Actualización) Catalog
+
+This module provides access to UMA values, which are used as reference
+units for fines, taxes, and other obligations in Mexico.
+"""
+
+import json
+from pathlib import Path
+
+from .salarios_minimos import SalariosMinimos
+
+
+class UMACatalog:
+    """
+    Catalog of UMA (Unidad de Medida y Actualización) values
+
+    UMA is a reference economic unit used in Mexico for calculating
+    fines, taxes, social security contributions, and other obligations.
+    It was introduced in 2016 to replace the minimum wage as a reference unit.
+    """
+
+    _data: list[dict] | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        """Load UMA data from JSON file"""
+        if cls._data is None:
+            # Path: catalogmx/packages/python/catalogmx/catalogs/mexico/uma.py
+            # Target: catalogmx/packages/shared-data/mexico/uma.json
+            current_file = Path(__file__)
+            shared_data_path = (
+                current_file.parent.parent.parent.parent.parent
+                / "shared-data"
+                / "mexico"
+                / "uma.json"
+            )
+
+            with open(shared_data_path, encoding="utf-8") as f:
+                cls._data = json.load(f)
+
+    @classmethod
+    def get_data(cls) -> list[dict]:
+        """
+        Get all UMA data
+
+        :return: List of all UMA records
+        """
+        cls._load_data()
+        return cls._data.copy()
+
+    @classmethod
+    def get_por_anio(cls, anio: int) -> dict | None:
+        """
+        Get UMA values for a specific year
+
+        :param anio: Year (e.g., 2024)
+        :return: UMA record or None if not found
+        """
+        cls._load_data()
+
+        for record in cls._data:
+            if record["año"] == anio:
+                return record.copy()
+
+        # Fallback to salary minimum equivalence for pre-2017 years
+        salario = SalariosMinimos.get_por_anio(anio)
+        if not salario:
+            return None
+
+        diario = salario.get("uma_equivalente_diario") or salario.get("resto_pais")
+        if diario is None:
+            return None
+
+        mensual = salario.get("uma_equivalente_mensual")
+        if mensual is None:
+            mensual = round(diario * 30.4, 2)
+
+        anual = salario.get("uma_equivalente_anual")
+        if anual is None:
+            anual = round(diario * 365, 2)
+
+        return {
+            "año": anio,
+            "vigencia_inicio": salario.get("vigencia_inicio", f"{anio}-01-01"),
+            "vigencia_fin": f"{anio}-12-31",
+            "valor_diario": round(diario, 2),
+            "valor_mensual": mensual,
+            "valor_anual": anual,
+            "moneda": salario.get("moneda", "MXN"),
+            "publicacion_dof": salario.get("vigencia_inicio", f"{anio}-01-01"),
+            "incremento_porcentual": None,
+            "notas": "Equivalencia de UMA derivada del salario mínimo vigente antes de 2017",
+        }
+
+    @classmethod
+    def get_actual(cls) -> dict | None:
+        """
+        Get current UMA values (latest year in data)
+
+        :return: Latest UMA record
+        """
+        cls._load_data()
+
+        if not cls._data:
+            return None
+
+        # Data is sorted by year descending, so first element is most recent
+        return cls._data[0].copy()
+
+    @classmethod
+    def get_valor(cls, anio: int, tipo: str = "diario") -> float | None:
+        """
+        Get UMA value for specific year and type
+
+        :param anio: Year
+        :param tipo: Type of value ('diario', 'mensual', 'anual')
+        :return: UMA value or None if not found
+        """
+        record = cls.get_por_anio(anio)
+        if not record:
+            return None
+
+        tipo_map = {"diario": "valor_diario", "mensual": "valor_mensual", "anual": "valor_anual"}
+
+        field = tipo_map.get(tipo.lower())
+        if not field:
+            return None
+
+        return record.get(field)
+
+    @classmethod
+    def calcular_umas(cls, monto: float, anio: int, tipo: str = "diario") -> float | None:
+        """
+        Calculate how many UMAs a given amount represents
+
+        :param monto: Amount in Mexican pesos
+        :param anio: Year for UMA value
+        :param tipo: Type of UMA ('diario', 'mensual', 'anual')
+        :return: Number of UMAs or None if UMA value not found
+        """
+        valor_uma = cls.get_valor(anio, tipo)
+        if not valor_uma:
+            return None
+
+        return monto / valor_uma
+
+    @classmethod
+    def calcular_monto(cls, umas: float, anio: int, tipo: str = "diario") -> float | None:
+        """
+        Calculate the peso amount for a given number of UMAs
+
+        :param umas: Number of UMAs
+        :param anio: Year for UMA value
+        :param tipo: Type of UMA ('diario', 'mensual', 'anual')
+        :return: Amount in Mexican pesos or None if UMA value not found
+        """
+        valor_uma = cls.get_valor(anio, tipo)
+        if not valor_uma:
+            return None
+
+        return umas * valor_uma
+
+    @classmethod
+    def get_incremento(cls, anio: int) -> float | None:
+        """
+        Get percentage increment for a specific year
+
+        :param anio: Year
+        :return: Percentage increment or None if not found
+        """
+        record = cls.get_por_anio(anio)
+        if not record:
+            return None
+
+        return record.get("incremento_porcentual")
+
+
+# Convenience functions
+def get_uma_actual() -> dict | None:
+    """Get current UMA values"""
+    return UMACatalog.get_actual()
+
+
+def get_uma_por_anio(anio: int) -> dict | None:
+    """Get UMA values for a specific year"""
+    return UMACatalog.get_por_anio(anio)
+
+
+def calcular_umas(monto: float, anio: int, tipo: str = "diario") -> float | None:
+    """Calculate how many UMAs a given amount represents"""
+    return UMACatalog.calcular_umas(monto, anio, tipo)
+
+
+def calcular_monto(umas: float, anio: int, tipo: str = "diario") -> float | None:
+    """Calculate peso amount for a given number of UMAs"""
+    return UMACatalog.calcular_monto(umas, anio, tipo)
+
+
+# Export commonly used functions and classes
+__all__ = [
+    "UMACatalog",
+    "get_uma_actual",
+    "get_uma_por_anio",
+    "calcular_umas",
+    "calcular_monto",
+]

catalogmx/catalogs/sat/__init__.py

@@ -0,0 +1,13 @@
+"""
+catalogmx.catalogs.sat - Catálogos del SAT
+
+Módulos disponibles:
+- cfdi_4: Catálogos para CFDI 4.0 (Anexo 20)
+- comercio_exterior: Catálogos para Complemento de Comercio Exterior 2.0
+- carta_porte: Catálogos para Complemento de Carta Porte 3.0
+- nomina: Catálogos para Complemento de Nómina 1.2
+"""
+
+from . import carta_porte, cfdi_4, comercio_exterior, nomina
+
+__all__ = ["cfdi_4", "comercio_exterior", "carta_porte", "nomina"]

catalogmx/catalogs/sat/carta_porte/__init__.py

@@ -0,0 +1,19 @@
+"""Catálogos SAT Carta Porte 3.0"""
+
+from .aeropuertos import AeropuertosCatalog
+from .carreteras import CarreterasCatalog
+from .config_autotransporte import ConfigAutotransporteCatalog
+from .material_peligroso import MaterialPeligrosoCatalog
+from .puertos_maritimos import PuertosMaritimos
+from .tipo_embalaje import TipoEmbalajeCatalog
+from .tipo_permiso import TipoPermisoCatalog
+
+__all__ = [
+    "AeropuertosCatalog",
+    "PuertosMaritimos",
+    "TipoPermisoCatalog",
+    "ConfigAutotransporteCatalog",
+    "TipoEmbalajeCatalog",
+    "CarreterasCatalog",
+    "MaterialPeligrosoCatalog",
+]

catalogmx/catalogs/sat/carta_porte/aeropuertos.py

@@ -0,0 +1,76 @@
+"""Catálogo c_CodigoTransporteAereo - Aeropuertos"""
+
+import json
+from pathlib import Path
+
+from catalogmx.utils.text import normalize_text
+
+
+class AeropuertosCatalog:
+    _data: list[dict] | None = None
+    _by_code: dict[str, dict] | None = None
+    _by_iata: dict[str, dict] | None = None
+    _by_icao: dict[str, dict] | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        if cls._data is None:
+            path = (
+                Path(__file__).parent.parent.parent.parent.parent.parent
+                / "shared-data"
+                / "sat"
+                / "carta_porte_3"
+                / "aeropuertos.json"
+            )
+            with open(path, encoding="utf-8") as f:
+                cls._data = json.load(f)
+            cls._by_code = {item["code"]: item for item in cls._data}
+            cls._by_iata = {item["iata"]: item for item in cls._data}
+            cls._by_icao = {item["icao"]: item for item in cls._data}
+
+    @classmethod
+    def get_aeropuerto(cls, code: str) -> dict | None:
+        """Obtiene aeropuerto por código SAT"""
+        cls._load_data()
+        return cls._by_code.get(code)
+
+    @classmethod
+    def get_by_iata(cls, iata: str) -> dict | None:
+        """Obtiene aeropuerto por código IATA"""
+        cls._load_data()
+        return cls._by_iata.get(iata)
+
+    @classmethod
+    def get_by_icao(cls, icao: str) -> dict | None:
+        """Obtiene aeropuerto por código ICAO"""
+        cls._load_data()
+        return cls._by_icao.get(icao)
+
+    @classmethod
+    def is_valid(cls, code: str) -> bool:
+        """Verifica si un código de aeropuerto es válido"""
+        return cls.get_aeropuerto(code) is not None
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """Obtiene todos los aeropuertos"""
+        cls._load_data()
+        return cls._data.copy()
+
+    @classmethod
+    def get_by_state(cls, state: str) -> list[dict]:
+        """Obtiene aeropuertos por estado (insensible a acentos)"""
+        cls._load_data()
+        state_normalized = normalize_text(state)
+        return [
+            a
+            for a in cls._data
+            if normalize_text(a.get("estado", a.get("state", ""))) == state_normalized
+        ]
+
+    @classmethod
+    def search_by_name(cls, name: str) -> list[dict]:
+        """Busca aeropuertos por nombre (insensible a acentos)"""
+        cls._load_data()
+        name_normalized = normalize_text(name)
+        return [a for a in cls._data if name_normalized in normalize_text(a["name"])]