catalogmx 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

catalogmx/catalogs/sepomex/codigos_postales_completo.py

@@ -0,0 +1,261 @@
+"""Catálogo de Códigos Postales SEPOMEX - Versión Completa
+
+Provides access to all ~150,000 Mexican postal codes with enhanced data.
+Includes settlement type (tipo_asentamiento), zone (zona), and state/municipality codes.
+
+WARNING: This catalog is very large (~42MB). Use with caution and consider
+using pagination or filters when displaying results.
+"""
+
+import json
+from pathlib import Path
+
+from catalogmx.utils.text import normalize_text
+
+
+class CodigosPostalesCompleto:
+    """Catálogo completo de códigos postales con datos extendidos"""
+
+    _data: list[dict] | None = None
+    _by_cp: dict[str, list[dict]] | None = None
+    _by_estado: dict[str, list[dict]] | None = None
+    _by_estado_normalized: dict[str, list[dict]] | None = None
+    _by_municipio_normalized: dict[str, list[dict]] | None = None
+    _by_zona: dict[str, list[dict]] | None = None
+
+    @classmethod
+    def _load_data(cls) -> None:
+        if cls._data is None:
+            path = (
+                Path(__file__).parent.parent.parent.parent.parent
+                / "shared-data"
+                / "sepomex"
+                / "codigos_postales_completo.json"
+            )
+            with open(path, encoding="utf-8") as f:
+                cls._data = json.load(f)
+
+            # Index by CP (can have multiple settlements)
+            cls._by_cp = {}
+            for item in cls._data:
+                cp = item.get("cp") or item.get("codigo_postal")
+                if cp:
+                    if cp not in cls._by_cp:
+                        cls._by_cp[cp] = []
+                    cls._by_cp[cp].append(item)
+
+            # Index by estado
+            cls._by_estado = {}
+            for item in cls._data:
+                estado = item.get("estado")
+                if estado:
+                    if estado not in cls._by_estado:
+                        cls._by_estado[estado] = []
+                    cls._by_estado[estado].append(item)
+
+            # Index by estado normalized (accent-insensitive)
+            cls._by_estado_normalized = {}
+            for item in cls._data:
+                estado = item.get("estado")
+                if estado:
+                    estado_norm = normalize_text(estado)
+                    if estado_norm not in cls._by_estado_normalized:
+                        cls._by_estado_normalized[estado_norm] = []
+                    cls._by_estado_normalized[estado_norm].append(item)
+
+            # Index by municipio normalized (accent-insensitive)
+            cls._by_municipio_normalized = {}
+            for item in cls._data:
+                municipio = item.get("municipio")
+                if municipio:
+                    municipio_norm = normalize_text(municipio)
+                    if municipio_norm not in cls._by_municipio_normalized:
+                        cls._by_municipio_normalized[municipio_norm] = []
+                    cls._by_municipio_normalized[municipio_norm].append(item)
+
+            # Index by zona (Urbano/Rural)
+            cls._by_zona = {}
+            for item in cls._data:
+                zona = item.get("zona")
+                if zona:
+                    if zona not in cls._by_zona:
+                        cls._by_zona[zona] = []
+                    cls._by_zona[zona].append(item)
+
+    @classmethod
+    def get_by_cp(cls, cp: str) -> list[dict]:
+        """Obtiene todos los asentamientos de un código postal"""
+        cls._load_data()
+        return cls._by_cp.get(cp, [])
+
+    @classmethod
+    def is_valid(cls, cp: str) -> bool:
+        """Verifica si un código postal existe"""
+        cls._load_data()
+        return cp in cls._by_cp
+
+    @classmethod
+    def get_by_estado(cls, estado: str) -> list[dict]:
+        """Obtiene todos los códigos postales de un estado (insensible a acentos)"""
+        cls._load_data()
+        estado_normalized = normalize_text(estado)
+        return cls._by_estado_normalized.get(estado_normalized, [])
+
+    @classmethod
+    def get_by_municipio(cls, municipio: str) -> list[dict]:
+        """Obtiene todos los códigos postales de un municipio (insensible a acentos)"""
+        cls._load_data()
+        municipio_normalized = normalize_text(municipio)
+        return cls._by_municipio_normalized.get(municipio_normalized, [])
+
+    @classmethod
+    def get_by_zona(cls, zona: str) -> list[dict]:
+        """Obtiene códigos postales por zona (Urbano o Rural)"""
+        cls._load_data()
+        return cls._by_zona.get(zona, [])
+
+    @classmethod
+    def search_by_asentamiento(
+        cls, query: str, *, codigo_postal: str | None = None, estado: str | None = None
+    ) -> list[dict]:
+        """Busca códigos postales por nombre de asentamiento (insensible a acentos)"""
+        cls._load_data()
+        query_normalized = normalize_text(query)
+
+        search_list = cls._data
+        if codigo_postal:
+            search_list = cls.get_by_cp(codigo_postal)
+        elif estado:
+            search_list = cls.get_by_estado(estado)
+
+        return [
+            item
+            for item in search_list
+            if query_normalized in normalize_text(item.get("asentamiento", ""))
+        ]
+
+    @classmethod
+    def search_by_colonia(cls, colonia: str) -> list[dict]:
+        """Alias for search_by_asentamiento for backwards compatibility"""
+        return cls.search_by_asentamiento(colonia)
+
+    @classmethod
+    def get_by_tipo_asentamiento(cls, tipo: str) -> list[dict]:
+        """Obtiene códigos postales por tipo de asentamiento (Colonia, Fraccionamiento, etc.)"""
+        cls._load_data()
+        tipo_normalized = normalize_text(tipo)
+        return [
+            item
+            for item in cls._data
+            if tipo_normalized in normalize_text(item.get("tipo_asentamiento", ""))
+        ]
+
+    @classmethod
+    def get_all(cls) -> list[dict]:
+        """Obtiene todos los códigos postales (WARNING: dataset muy grande)"""
+        cls._load_data()
+        return cls._data.copy()
+
+    @classmethod
+    def get_municipio(cls, cp: str) -> str | None:
+        """Obtiene el municipio de un código postal"""
+        settlements = cls.get_by_cp(cp)
+        return settlements[0]["municipio"] if settlements else None
+
+    @classmethod
+    def get_estado(cls, cp: str) -> str | None:
+        """Obtiene el estado de un código postal"""
+        settlements = cls.get_by_cp(cp)
+        return settlements[0]["estado"] if settlements else None
+
+    @classmethod
+    def get_total_count(cls) -> int:
+        """Obtiene el conteo total de códigos postales"""
+        cls._load_data()
+        return len(cls._data)
+
+    @classmethod
+    def get_unique_cps(cls) -> list[str]:
+        """Obtiene todos los códigos postales únicos"""
+        cls._load_data()
+        return sorted(set(cls._by_cp.keys()))
+
+    @classmethod
+    def get_count_by_estado(cls, estado: str) -> int:
+        """Obtiene el conteo de códigos postales por estado"""
+        return len(cls.get_by_estado(estado))
+
+    @classmethod
+    def get_asentamientos(cls, cp: str) -> list[str]:
+        """Obtiene todos los asentamientos de un código postal"""
+        settlements = cls.get_by_cp(cp)
+        return [s.get("asentamiento", "") for s in settlements]
+
+    @classmethod
+    def search(
+        cls,
+        *,
+        cp: str | None = None,
+        estado: str | None = None,
+        municipio: str | None = None,
+        asentamiento: str | None = None,
+        limit: int = 100,
+    ) -> list[dict]:
+        """Busca con múltiples criterios (con paginación)"""
+        cls._load_data()
+        results = cls._data
+
+        if cp:
+            results = [r for r in results if r.get("cp") == cp or r.get("codigo_postal") == cp]
+        if estado:
+            estado_norm = normalize_text(estado)
+            results = [r for r in results if normalize_text(r.get("estado", "")) == estado_norm]
+        if municipio:
+            municipio_norm = normalize_text(municipio)
+            results = [
+                r for r in results if municipio_norm in normalize_text(r.get("municipio", ""))
+            ]
+        if asentamiento:
+            asentamiento_norm = normalize_text(asentamiento)
+            results = [
+                r for r in results if asentamiento_norm in normalize_text(r.get("asentamiento", ""))
+            ]
+
+        return results[:limit]
+
+    @classmethod
+    def get_statistics(cls) -> dict:
+        """Obtiene estadísticas del catálogo"""
+        cls._load_data()
+        unique_cps = set()
+        unique_states = set()
+        unique_municipalities = set()
+
+        for item in cls._data:
+            cp = item.get("cp") or item.get("codigo_postal")
+            if cp:
+                unique_cps.add(cp)
+            estado = item.get("estado")
+            if estado:
+                unique_states.add(estado)
+            municipio = item.get("municipio")
+            estado = item.get("estado")
+            if municipio and estado:
+                unique_municipalities.add(f"{estado}:{municipio}")
+
+        return {
+            "total_postal_codes": len(cls._data),
+            "unique_postal_codes": len(unique_cps),
+            "states": len(unique_states),
+            "municipalities": len(unique_municipalities),
+        }
+
+    @classmethod
+    def clear_cache(cls) -> None:
+        """Limpia los datos en caché para liberar memoria"""
+        cls._data = None
+        cls._by_cp = None
+        cls._by_estado = None
+        cls._by_estado_normalized = None
+        cls._by_municipio_normalized = None
+        cls._by_zona = None

catalogmx/cli.py

@@ -1,17 +1,20 @@
 """
 Module that contains the command line app.
 
-Why does this file exist, and why not put this in __main__?
-
-  You might be tempted to import things from __main__ later, but that will cause
-  problems: the code will get executed twice:
+Coverage Exclusion Justification:
+---------------------------------
+This file is excluded from coverage because:
+1. CLI code requires actual terminal invocation to test properly
+2. Click commands handle formatted output (colors, emojis) that's hard to assert
+3. User interaction paths (error messages, confirmations) are presentation-only
+4. The underlying validators (RFCValidator, CURPValidator) ARE tested directly
 
-  - When you run `python -mrfcmx` python will execute
-    ``__main__.py`` as a script. That means there won't be any
-    ``rfcmx.__main__`` in ``sys.modules``.
-  - When you import __main__ it will get executed again (as a module) because
-    there's no ``rfcmx.__main__`` in ``sys.modules``.
+The business logic (validation, generation) is tested in their respective modules.
+This file is pure presentation/interface code.
 
+Why does this file exist, and why not put this in __main__?
+  You might be tempted to import things from __main__ later, but that will cause
+  problems: the code will get executed twice.
   Also see (1) from http://click.pocoo.org/5/setuptools/#setuptools-integration
 """
 

catalogmx/data/__init__.py

@@ -0,0 +1,10 @@
+"""
+Data updater module for catalogmx
+
+This module handles automatic updates of dynamic data (UDI, tipo cambio, etc.)
+from GitHub Releases, allowing data updates without requiring library releases.
+"""
+
+from catalogmx.data.updater import DataUpdater
+
+__all__ = ["DataUpdater"]

catalogmx/data/updater.py

@@ -0,0 +1,362 @@
+"""
+Data Updater - Automatic download of dynamic data from GitHub Releases
+
+This module allows catalogmx to update dynamic data (UDI, exchange rates, TIIE, etc.)
+without requiring a new library release. Data is downloaded from GitHub Releases
+and cached locally.
+
+Coverage Exclusion Justification:
+---------------------------------
+This file is excluded from coverage because:
+1. Network I/O: Downloads from GitHub Releases require mocking entire urllib
+2. File system operations: Cache management, directory creation, file moves
+3. Error recovery paths: Network failures, corrupted downloads, disk full scenarios
+4. Environment variables: CATALOGMX_DATA_URL, CATALOGMX_CACHE_DIR, CATALOGMX_AUTO_UPDATE
+
+Testing this properly would require:
+- Mocking urllib.request.urlretrieve
+- Mocking Path operations (exists, mkdir, unlink, open)
+- Mocking sqlite3 connections
+- Creating temporary directories
+
+The overhead doesn't justify the benefit since:
+- The SQLite catalog loaders (which USE this updater) are tested
+- Manual integration testing verifies the download flow works
+
+Usage:
+    from catalogmx.data import DataUpdater
+
+    # Automatic update (recommended)
+    updater = DataUpdater()
+    db_path = updater.auto_update(max_age_hours=24)
+
+    # Manual update
+    updater.download_latest()
+
+    # Check version
+    version = updater.get_local_version()
+"""
+
+import json
+import os
+import shutil
+import sqlite3
+import urllib.request
+from datetime import datetime
+from pathlib import Path
+
+# Configuration
+GITHUB_RELEASE_URL = os.getenv(
+    "CATALOGMX_DATA_URL",
+    "https://github.com/openbancor/catalogmx/releases/download/latest/mexico_dynamic.sqlite3",
+)
+
+CACHE_DIR = Path(os.getenv("CATALOGMX_CACHE_DIR", str(Path.home() / ".catalogmx")))
+CACHE_DB = CACHE_DIR / "mexico_dynamic.sqlite3"
+VERSION_FILE = CACHE_DIR / "version.json"
+
+# Embedded fallback database (included in package)
+EMBEDDED_DB = Path(__file__).parent / "mexico_dynamic.sqlite3"
+
+# Auto-update enabled by default
+AUTO_UPDATE_ENABLED = os.getenv("CATALOGMX_AUTO_UPDATE", "true").lower() in (
+    "true",
+    "1",
+    "yes",
+)
+
+
+class DataUpdater:
+    """
+    Manages automatic updates of dynamic data from GitHub Releases
+
+    This class handles downloading, caching, and version management of the
+    dynamic data SQLite database, allowing data updates without library releases.
+    """
+
+    def __init__(self, cache_dir: Path | None = None):
+        """
+        Initialize DataUpdater
+
+        :param cache_dir: Custom cache directory (default: ~/.catalogmx)
+        """
+        self.cache_dir = cache_dir or CACHE_DIR
+        self.cache_db = self.cache_dir / "mexico_dynamic.sqlite3"
+        self.version_file = self.cache_dir / "version.json"
+
+        # Create cache directory if it doesn't exist
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def get_local_version(self) -> str | None:
+        """
+        Get version of local cached data
+
+        :return: Version string (e.g., "2025-12-04") or None if no cache
+        """
+        if not self.version_file.exists():
+            return None
+
+        try:
+            with open(self.version_file, encoding="utf-8") as f:
+                return json.load(f).get("version")
+        except (json.JSONDecodeError, OSError):
+            return None
+
+    def get_local_age_hours(self) -> float | None:
+        """
+        Get age of local cached data in hours
+
+        :return: Age in hours or None if no cache
+        """
+        if not self.version_file.exists():
+            return None
+
+        try:
+            with open(self.version_file, encoding="utf-8") as f:
+                data = json.load(f)
+                updated_str = data.get("updated_at")
+                if not updated_str:
+                    return None
+
+                updated = datetime.fromisoformat(updated_str)
+                return (datetime.now() - updated).total_seconds() / 3600
+        except (json.JSONDecodeError, OSError, ValueError):
+            return None
+
+    def _verify_database(self, db_path: Path) -> str | None:
+        """
+        Verify database integrity and get version
+
+        :param db_path: Path to database file
+        :return: Version string or None if invalid
+        """
+        try:
+            db = sqlite3.connect(db_path)
+            cursor = db.execute("SELECT value FROM _metadata WHERE key = 'version'")
+            row = cursor.fetchone()
+            db.close()
+
+            if row:
+                return row[0]
+            return None
+        except (sqlite3.Error, OSError):
+            return None
+
+    def download_latest(self, force: bool = False, verbose: bool = True) -> bool:
+        """
+        Download latest version of data from GitHub Releases
+
+        :param force: Force download even if cache is recent
+        :param verbose: Print progress messages
+        :return: True if download successful, False otherwise
+        """
+        if verbose:
+            print(f"📥 Downloading data from {GITHUB_RELEASE_URL}...")
+
+        try:
+            # Download to temporary file
+            temp_db = self.cache_dir / "mexico_dynamic.sqlite3.tmp"
+            urllib.request.urlretrieve(GITHUB_RELEASE_URL, temp_db)
+
+            # Verify integrity
+            version = self._verify_database(temp_db)
+            if not version:
+                if verbose:
+                    print("❌ Downloaded database is invalid or corrupted")
+                temp_db.unlink(missing_ok=True)
+                return False
+
+            # Move to cache
+            shutil.move(str(temp_db), str(self.cache_db))
+
+            # Save metadata
+            with open(self.version_file, "w", encoding="utf-8") as f:
+                json.dump(
+                    {
+                        "version": version,
+                        "updated_at": datetime.now().isoformat(),
+                        "source": "github_releases",
+                        "url": GITHUB_RELEASE_URL,
+                    },
+                    f,
+                    indent=2,
+                )
+
+            if verbose:
+                print(f"✅ Data updated to version {version}")
+            return True
+
+        except Exception as e:
+            if verbose:
+                print(f"❌ Error downloading data: {e}")
+            return False
+
+    def auto_update(self, max_age_hours: int = 24, verbose: bool = False) -> Path:
+        """
+        Auto-update with intelligent fallback
+
+        This method:
+        1. Checks if local cache exists and is recent
+        2. Downloads update if cache is old or missing
+        3. Falls back to cache if download fails
+        4. Falls back to embedded data if no cache exists
+
+        :param max_age_hours: Maximum age before updating (default 24 hours)
+        :param verbose: Print progress messages
+        :return: Path to database to use
+        """
+        if not AUTO_UPDATE_ENABLED:
+            # Auto-update disabled, use cache or embedded
+            if self.cache_db.exists():
+                return self.cache_db
+            if EMBEDDED_DB.exists():
+                return EMBEDDED_DB
+            raise FileNotFoundError("No database available and auto-update is disabled")
+
+        age = self.get_local_age_hours()
+
+        # If no cache or cache is old, try to update
+        if age is None or age > max_age_hours:
+            if self.download_latest(verbose=verbose):
+                return self.cache_db
+
+        # If cache exists (even if update failed), use it
+        if self.cache_db.exists():
+            if verbose and age is not None:
+                print(f"ℹ️  Using cached data (age: {age:.1f} hours)")
+            return self.cache_db
+
+        # Fallback: embedded data
+        if EMBEDDED_DB.exists():
+            if verbose:
+                print("⚠️  Using embedded data (may be outdated)")
+            return EMBEDDED_DB
+
+        raise FileNotFoundError(
+            "No database available. Please check your internet connection or manually download the database."
+        )
+
+    def get_database_path(self, auto_update: bool = True, max_age_hours: int = 24) -> Path:
+        """
+        Get path to database (with or without auto-update)
+
+        :param auto_update: Enable auto-update (default True)
+        :param max_age_hours: Maximum age before updating (default 24 hours)
+        :return: Path to database file
+        """
+        if auto_update:
+            return self.auto_update(max_age_hours=max_age_hours)
+
+        # No auto-update, use cache or embedded
+        if self.cache_db.exists():
+            return self.cache_db
+
+        if EMBEDDED_DB.exists():
+            return EMBEDDED_DB
+
+        raise FileNotFoundError("No database available")
+
+    def get_version_info(self) -> dict[str, str]:
+        """
+        Get detailed version information
+
+        :return: Dictionary with version, age, source, etc.
+        """
+        if not self.version_file.exists():
+            return {
+                "version": "unknown",
+                "source": "embedded" if EMBEDDED_DB.exists() else "none",
+                "age_hours": "N/A",
+                "updated_at": "N/A",
+            }
+
+        try:
+            with open(self.version_file, encoding="utf-8") as f:
+                data = json.load(f)
+
+            age = self.get_local_age_hours()
+            data["age_hours"] = f"{age:.1f}" if age is not None else "N/A"
+
+            return data
+        except (json.JSONDecodeError, OSError):
+            return {
+                "version": "error",
+                "source": "error",
+                "age_hours": "N/A",
+                "updated_at": "N/A",
+            }
+
+    def clear_cache(self) -> bool:
+        """
+        Clear local cache
+
+        :return: True if cache cleared successfully
+        """
+        try:
+            if self.cache_db.exists():
+                self.cache_db.unlink()
+            if self.version_file.exists():
+                self.version_file.unlink()
+            return True
+        except OSError:
+            return False
+
+    def clearCache(self) -> bool:
+        """
+        Clear local cache (camelCase alias for clear_cache)
+
+        :return: True if cache cleared successfully
+        """
+        return self.clear_cache()
+
+
+# Singleton instance for convenience
+_default_updater = DataUpdater()
+
+
+def get_database_path(auto_update: bool = True, max_age_hours: int = 24) -> Path:
+    """
+    Get path to dynamic data database
+
+    Convenience function using default updater instance.
+
+    :param auto_update: Enable auto-update (default True)
+    :param max_age_hours: Maximum age before updating (default 24 hours)
+    :return: Path to database file
+    """
+    return _default_updater.get_database_path(auto_update, max_age_hours)
+
+
+def get_version() -> str | None:
+    """
+    Get version of local cached data
+
+    Convenience function using default updater instance.
+
+    :return: Version string or None
+    """
+    return _default_updater.get_local_version()
+
+
+def update_now(force: bool = False, verbose: bool = True) -> bool:
+    """
+    Force update data now
+
+    Convenience function using default updater instance.
+
+    :param force: Force download even if cache is recent
+    :param verbose: Print progress messages
+    :return: True if successful
+    """
+    return _default_updater.download_latest(force=force, verbose=verbose)
+
+
+# Export public API
+__all__ = [
+    "DataUpdater",
+    "get_database_path",
+    "get_version",
+    "update_now",
+    "CACHE_DIR",
+    "AUTO_UPDATE_ENABLED",
+]

catalogmx/generators/__init__.py

@@ -0,0 +1,20 @@
+"""
+Identity generators for Mexican test data.
+
+This module provides functions to generate complete Mexican identities
+with realistic data for testing and development purposes.
+"""
+
+from catalogmx.generators.identity import (
+    IdentityGenerator,
+    generate_identity,
+    generate_persona_fisica,
+    generate_persona_moral,
+)
+
+__all__ = [
+    "IdentityGenerator",
+    "generate_identity",
+    "generate_persona_fisica",
+    "generate_persona_moral",
+]