catalogmx 0.3.0__py3-none-any.whl

catalogmx/__init__.py

@@ -0,0 +1,56 @@
+__version__ = "0.3.0"
+
+# RFC imports
+# Modern helper functions (recommended API)
+from .helpers import (
+    detect_rfc_type,
+    # CURP helpers
+    generate_curp,
+    # RFC helpers
+    generate_rfc_persona_fisica,
+    generate_rfc_persona_moral,
+    get_curp_info,
+    is_valid_curp,
+    is_valid_rfc,
+    validate_curp,
+    validate_rfc,
+)
+
+# CURP imports
+from .validators.curp import (
+    CURPException,
+    CURPGenerator,
+    CURPLengthError,
+    CURPStructureError,
+    CURPValidator,
+)
+from .validators.rfc import (
+    RFCGenerator,
+    RFCGeneratorFisicas,
+    RFCGeneratorMorales,
+    RFCValidator,
+)
+
+__all__ = [
+    # RFC Classes (legacy/advanced usage)
+    "RFCValidator",
+    "RFCGenerator",
+    "RFCGeneratorFisicas",
+    "RFCGeneratorMorales",
+    # CURP Classes (legacy/advanced usage)
+    "CURPValidator",
+    "CURPGenerator",
+    "CURPException",
+    "CURPLengthError",
+    "CURPStructureError",
+    # Modern helper functions (recommended)
+    "generate_rfc_persona_fisica",
+    "generate_rfc_persona_moral",
+    "validate_rfc",
+    "detect_rfc_type",
+    "is_valid_rfc",
+    "generate_curp",
+    "validate_curp",
+    "get_curp_info",
+    "is_valid_curp",
+]

catalogmx/catalogs/__init__.py

@@ -0,0 +1,5 @@
+"""
+catalogmx.catalogs - Catálogos oficiales mexicanos
+"""
+
+__all__ = ["sat", "banxico", "inegi", "sepomex", "ift"]

catalogmx/catalogs/banxico/__init__.py

@@ -0,0 +1,24 @@
+"""
+catalogmx.catalogs.banxico - Catálogos de Banxico
+
+Catálogos incluidos:
+- BankCatalog: Bancos autorizados por Banxico
+- UDICatalog: UDIs (Unidades de Inversión)
+- InstitucionesFinancieras: Tipos de instituciones del sistema financiero
+- MonedasDivisas: Monedas y divisas internacionales
+- CodigosPlazaCatalog: Códigos de plaza para CLABE
+"""
+
+from .banks import BankCatalog
+from .codigos_plaza import CodigosPlazaCatalog
+from .instituciones_financieras import InstitucionesFinancieras
+from .monedas_divisas import MonedasDivisas
+from .udis import UDICatalog
+
+__all__ = [
+    "BankCatalog",
+    "UDICatalog",
+    "InstitucionesFinancieras",
+    "MonedasDivisas",
+    "CodigosPlazaCatalog",
+]

catalogmx/catalogs/banxico/banks.py

@@ -0,0 +1,136 @@
+"""
+Bank Catalog from Banxico
+
+This module provides access to the official catalog of Mexican banks
+participating in the SPEI (Sistema de Pagos Electrónicos Interbancarios).
+"""
+
+import json
+from pathlib import Path
+
+from catalogmx.utils.text import normalize_text
+
+
+class BankCatalog:
+    """
+    Catalog of Mexican banks
+    """
+
+    _data: list[dict] | None = None
+    _bank_by_code: dict[str, dict] | None = None
+    _bank_by_name: dict[str, dict] | None = None
+    _bank_by_name_normalized: dict[str, dict] | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        """Load bank data from JSON file"""
+        if cls._data is None:
+            # Path: catalogmx/packages/python/catalogmx/catalogs/banxico/banks.py
+            # Target: catalogmx/packages/shared-data/banxico/banks.json
+            current_file = Path(__file__)
+            shared_data_path = (
+                current_file.parent.parent.parent.parent.parent
+                / "shared-data"
+                / "banxico"
+                / "banks.json"
+            )
+
+            with open(shared_data_path, encoding="utf-8") as f:
+                cls._data = json.load(f)
+
+            # Create lookup dictionaries
+            cls._bank_by_code = {bank["code"]: bank for bank in cls._data}
+            cls._bank_by_name = {bank["name"].upper(): bank for bank in cls._data}
+            # Accent-insensitive lookup
+            cls._bank_by_name_normalized = {
+                normalize_text(bank["name"]): bank for bank in cls._data
+            }
+
+    @classmethod
+    def get_all_banks(cls) -> list[dict]:
+        """
+        Get all banks in the catalog
+
+        :return: List of bank dictionaries
+        """
+        cls._load_data()
+        return cls._data.copy()
+
+    @classmethod
+    def get_bank_by_code(cls, code: str) -> dict | None:
+        """
+        Get bank information by code
+
+        :param code: 3-digit bank code (e.g., '002' for Banamex)
+        :return: Bank dictionary or None if not found
+        """
+        cls._load_data()
+        code = str(code).zfill(3)
+        return cls._bank_by_code.get(code)
+
+    @classmethod
+    def get_bank_by_name(cls, name: str) -> dict | None:
+        """
+        Get bank information by name (accent-insensitive)
+
+        :param name: Bank name (case and accent insensitive, e.g., 'BANAMEX' or 'Banamex')
+        :return: Bank dictionary or None if not found
+
+        Examples:
+            >>> # Both searches work the same
+            >>> bank = BankCatalog.get_bank_by_name("Banamex")
+            >>> bank = BankCatalog.get_bank_by_name("Banámex")  # same result
+        """
+        cls._load_data()
+        return cls._bank_by_name_normalized.get(normalize_text(name))
+
+    @classmethod
+    def is_spei_participant(cls, code: str) -> bool:
+        """
+        Check if a bank participates in SPEI
+
+        :param code: 3-digit bank code
+        :return: True if bank participates in SPEI, False otherwise
+        """
+        bank = cls.get_bank_by_code(code)
+        return bank.get("spei", False) if bank else False
+
+    @classmethod
+    def get_spei_banks(cls) -> list[dict]:
+        """
+        Get all banks that participate in SPEI
+
+        :return: List of SPEI participant banks
+        """
+        cls._load_data()
+        return [bank for bank in cls._data if bank.get("spei", False)]
+
+    @classmethod
+    def validate_bank_code(cls, code: str) -> bool:
+        """
+        Validate if a bank code exists
+
+        :param code: 3-digit bank code
+        :return: True if exists, False otherwise
+        """
+        return cls.get_bank_by_code(code) is not None
+
+
+# Convenience dictionaries for direct access
+def get_banks_dict() -> dict[str, dict]:
+    """Get dictionary of all banks indexed by code"""
+    BankCatalog._load_data()
+    return BankCatalog._bank_by_code.copy()
+
+
+def get_spei_banks() -> list[dict]:
+    """Get list of all SPEI participant banks"""
+    return BankCatalog.get_spei_banks()
+
+
+# Export commonly used functions
+__all__ = [
+    "BankCatalog",
+    "get_banks_dict",
+    "get_spei_banks",
+]

catalogmx/catalogs/banxico/codigos_plaza.py

@@ -0,0 +1,287 @@
+"""
+Catálogo de Códigos de Plaza CLABE
+=====================================
+
+Códigos de plaza para el sistema CLABE (Clave Bancaria Estandarizada).
+Los códigos de plaza son identificadores de 3 dígitos que indican la ubicación
+geográfica de las sucursales bancarias en México.
+
+Fuente: Banco de México (BANXICO) / Sistema de Pagos Electrónicos Interbancarios (SPEI)
+"""
+
+import json
+import os
+from typing import TypedDict
+
+try:
+    from unidecode import unidecode
+except ImportError:
+    # Fallback if unidecode not available
+    def unidecode(text):
+        return text
+
+
+class CodigoPlaza(TypedDict):
+    """Estructura de un código de plaza CLABE."""
+
+    codigo: str  # Código de 3 dígitos
+    plaza: str  # Nombre de la plaza/ciudad
+    estado: str  # Estado
+    cve_entidad: str  # Código INEGI del estado
+
+
+class CodigosPlazaCatalog:
+    """Catálogo de códigos de plaza para CLABE."""
+
+    _data: list[CodigoPlaza] | None = None
+    _by_codigo: dict[str, list[CodigoPlaza]] | None = None
+    _by_estado: dict[str, list[CodigoPlaza]] | None = None
+    _by_plaza: dict[str, list[CodigoPlaza]] | None = None
+    _by_plaza_normalized: dict[str, list[CodigoPlaza]] | None = None
+
+    @classmethod
+    def _normalize(cls, text: str) -> str:
+        """Normaliza texto removiendo acentos y convirtiendo a mayúsculas."""
+        return unidecode(text).upper()
+
+    @classmethod
+    def _load(cls) -> None:
+        """Carga los datos del catálogo."""
+        if cls._data is not None:
+            return
+
+        data_path = os.path.join(
+            os.path.dirname(__file__), "../../../../shared-data/banxico/codigos_plaza.json"
+        )
+
+        with open(data_path, encoding="utf-8") as f:
+            catalog = json.load(f)
+            cls._data = catalog["plazas"]
+
+        # Build indices
+        cls._by_codigo = {}
+        cls._by_estado = {}
+        cls._by_plaza = {}
+        cls._by_plaza_normalized = {}
+
+        for plaza in cls._data:
+            # By codigo (puede haber múltiples plazas con el mismo código)
+            if plaza["codigo"] not in cls._by_codigo:
+                cls._by_codigo[plaza["codigo"]] = []
+            cls._by_codigo[plaza["codigo"]].append(plaza)
+
+            # By estado
+            if plaza["estado"] not in cls._by_estado:
+                cls._by_estado[plaza["estado"]] = []
+            cls._by_estado[plaza["estado"]].append(plaza)
+
+            # By plaza name (exact match)
+            plaza_key = plaza["plaza"].upper()
+            if plaza_key not in cls._by_plaza:
+                cls._by_plaza[plaza_key] = []
+            cls._by_plaza[plaza_key].append(plaza)
+
+            # By plaza name (normalized, accent-insensitive)
+            plaza_normalized = cls._normalize(plaza["plaza"])
+            if plaza_normalized not in cls._by_plaza_normalized:
+                cls._by_plaza_normalized[plaza_normalized] = []
+            cls._by_plaza_normalized[plaza_normalized].append(plaza)
+
+    @classmethod
+    def get_all(cls) -> list[CodigoPlaza]:
+        """
+        Obtiene todos los códigos de plaza.
+
+        Returns:
+            Lista con todos los códigos de plaza
+        """
+        cls._load()
+        return cls._data.copy()
+
+    @classmethod
+    def buscar_por_codigo(cls, codigo: str) -> list[CodigoPlaza]:
+        """
+        Busca plazas por código.
+
+        Args:
+            codigo: Código de plaza (3 dígitos)
+
+        Returns:
+            Lista de plazas con ese código (puede haber múltiples)
+
+        Examples:
+            >>> plazas = CodigosPlazaCatalog.buscar_por_codigo("320")
+            >>> for p in plazas:
+            ...     print(f"{p['plaza']}, {p['estado']}")
+            Guadalajara, Jalisco
+            Tonala, Jalisco
+            ...
+        """
+        cls._load()
+        codigo_padded = codigo.zfill(3)
+        return cls._by_codigo.get(codigo_padded, [])
+
+    @classmethod
+    def buscar_por_plaza(cls, nombre_plaza: str) -> list[CodigoPlaza]:
+        """
+        Busca códigos por nombre de plaza (insensible a acentos).
+
+        Args:
+            nombre_plaza: Nombre de la plaza/ciudad
+
+        Returns:
+            Lista de códigos para esa plaza
+
+        Examples:
+            >>> # Tonalá aparece en dos estados diferentes
+            >>> plazas = CodigosPlazaCatalog.buscar_por_plaza("Tonala")
+            >>> for p in plazas:
+            ...     print(f"Código {p['codigo']}: {p['plaza']}, {p['estado']}")
+            Código 135: Tonala, Chiapas
+            Código 320: Tonala, Jalisco
+
+            >>> # Búsqueda insensible a acentos
+            >>> tuxpam = CodigosPlazaCatalog.buscar_por_plaza("Tuxpam")  # sin acento
+            >>> print(len(tuxpam))  # Encuentra "Túxpam" con acento
+            2
+        """
+        cls._load()
+        plaza_normalized = cls._normalize(nombre_plaza)
+        return cls._by_plaza_normalized.get(plaza_normalized, [])
+
+    @classmethod
+    def get_por_estado(cls, estado: str) -> list[CodigoPlaza]:
+        """
+        Obtiene todas las plazas de un estado.
+
+        Args:
+            estado: Nombre del estado
+
+        Returns:
+            Lista de plazas en ese estado
+
+        Examples:
+            >>> plazas = CodigosPlazaCatalog.get_por_estado("Jalisco")
+            >>> print(f"Jalisco tiene {len(plazas)} plazas")
+        """
+        cls._load()
+        return cls._by_estado.get(estado, [])
+
+    @classmethod
+    def get_por_cve_entidad(cls, cve_entidad: str) -> list[CodigoPlaza]:
+        """
+        Obtiene todas las plazas por código INEGI de entidad.
+
+        Args:
+            cve_entidad: Código INEGI del estado (2 dígitos)
+
+        Returns:
+            Lista de plazas en esa entidad
+
+        Examples:
+            >>> # Jalisco tiene cve_entidad '14'
+            >>> plazas = CodigosPlazaCatalog.get_por_cve_entidad("14")
+            >>> print(f"Entidad 14 tiene {len(plazas)} plazas")
+        """
+        cls._load()
+        return [p for p in cls._data if p["cve_entidad"] == cve_entidad]
+
+    @classmethod
+    def validar_codigo_clabe(cls, codigo_plaza: str) -> dict:
+        """
+        Valida un código de plaza dentro de una CLABE.
+
+        Args:
+            codigo_plaza: Código de plaza (3 dígitos)
+
+        Returns:
+            Diccionario con información de validación
+
+        Examples:
+            >>> result = CodigosPlazaCatalog.validar_codigo_clabe("180")
+            >>> print(result['valido'])
+            True
+            >>> print(result['plazas'][0]['plaza'])
+            Ciudad de México
+        """
+        cls._load()
+        codigo_padded = codigo_plaza.zfill(3)
+        plazas = cls.buscar_por_codigo(codigo_padded)
+
+        return {
+            "valido": len(plazas) > 0,
+            "codigo": codigo_padded,
+            "plazas": plazas,
+            "num_plazas": len(plazas),
+        }
+
+    @classmethod
+    def get_plazas_duplicadas(cls) -> dict[str, list[CodigoPlaza]]:
+        """
+        Obtiene plazas con nombres duplicados en diferentes estados.
+
+        Returns:
+            Diccionario con nombres de plaza y sus instancias
+
+        Examples:
+            >>> duplicadas = CodigosPlazaCatalog.get_plazas_duplicadas()
+            >>> for nombre, plazas in duplicadas.items():
+            ...     print(f"{nombre}: {len(plazas)} ubicaciones")
+            Tonala: 2 ubicaciones (Chiapas, Jalisco)
+            Túxpam: 2 ubicaciones (Jalisco, Nayarit)
+        """
+        cls._load()
+        duplicadas = {}
+        for nombre, plazas in cls._by_plaza.items():
+            if len(plazas) > 1:
+                duplicadas[nombre] = plazas
+        return duplicadas
+
+    @classmethod
+    def search(cls, query: str) -> list[CodigoPlaza]:
+        """
+        Busca plazas por nombre parcial (insensible a acentos y mayúsculas).
+
+        Args:
+            query: Texto a buscar
+
+        Returns:
+            Lista de plazas que coinciden
+
+        Examples:
+            >>> # Buscar todas las plazas con "San" en el nombre
+            >>> plazas = CodigosPlazaCatalog.search("San")
+            >>> for p in plazas[:5]:
+            ...     print(f"{p['codigo']}: {p['plaza']}, {p['estado']}")
+
+            >>> # Búsqueda insensible a acentos
+            >>> plazas = CodigosPlazaCatalog.search("Tuxpam")  # sin acento
+            >>> print(len(plazas))  # Encuentra "Túxpam" con acento
+            3
+        """
+        cls._load()
+        query_normalized = cls._normalize(query)
+        return [p for p in cls._data if query_normalized in cls._normalize(p["plaza"])]
+
+    @classmethod
+    def get_estadisticas(cls) -> dict:
+        """
+        Obtiene estadísticas del catálogo.
+
+        Returns:
+            Diccionario con estadísticas
+        """
+        cls._load()
+
+        estados = {p["estado"] for p in cls._data}
+        codigos_unicos = len(cls._by_codigo)
+
+        return {
+            "total_plazas": len(cls._data),
+            "codigos_unicos": codigos_unicos,
+            "estados_cubiertos": len(estados),
+            "plazas_duplicadas": len(cls.get_plazas_duplicadas()),
+        }
+
+
+__all__ = ["CodigosPlazaCatalog", "CodigoPlaza"]