catalogmx 0.3.0__py3-none-any.whl

catalogmx/catalogs/sat/cfdi_4/clave_prod_serv.py

@@ -0,0 +1,383 @@
+"""
+SAT CFDI 4.0 - Clave de Producto o Servicio (c_ClaveProdServ)
+
+Catálogo de claves de productos y servicios para facturación CFDI.
+Contiene ~52,000 códigos oficiales basados en UNSPSC (United Nations
+Standard Products and Services Code).
+
+Este módulo usa SQLite con FTS5 para búsqueda eficiente de texto completo.
+"""
+
+import sqlite3
+from pathlib import Path
+from typing import TypedDict
+
+
+class ClaveProdServ(TypedDict):
+    """Estructura de una clave de producto/servicio"""
+
+    id: str
+    descripcion: str
+    incluirIVATrasladado: str
+    incluirIEPSTrasladado: str
+    complementoQueDebeIncluir: str
+    palabrasSimilares: str
+    fechaInicioVigencia: str
+    fechaFinVigencia: str
+    estimuloFranjaFronteriza: str
+
+
+class ClaveProdServCatalog:
+    """
+    Catálogo de claves de productos y servicios SAT CFDI 4.0.
+
+    Implementación basada en SQLite con búsqueda FTS5 para alto rendimiento.
+
+    Características:
+    - ~52,000 códigos de productos y servicios
+    - Basado en estándar UNSPSC (ONU)
+    - Búsqueda full-text con FTS5
+    - Estructura jerárquica (segmento → familia → clase → producto)
+    - Indicadores de IVA e IEPS
+
+    WARNING: Este es un catálogo grande. Use search() o get_by_prefix()
+    en lugar de get_all() para mejor rendimiento.
+
+    Ejemplo:
+        >>> from catalogmx.catalogs.sat.cfdi_4 import ClaveProdServCatalog
+        >>>
+        >>> # Buscar productos
+        >>> results = ClaveProdServCatalog.search("computadora", limit=10)
+        >>> for item in results:
+        ...     print(f"{item['id']}: {item['descripcion']}")
+        >>>
+        >>> # Obtener por clave exacta
+        >>> producto = ClaveProdServCatalog.get_clave("43211500")
+        >>> print(producto['descripcion'])
+        >>>
+        >>> # Buscar por prefijo (navegación jerárquica)
+        >>> familia = ClaveProdServCatalog.get_by_prefix("4321", limit=50)
+        >>> print(f"Productos en familia 4321: {len(familia)}")
+    """
+
+    _db_path: Path | None = None
+    _connection: sqlite3.Connection | None = None
+
+    @classmethod
+    def _get_db_path(cls) -> Path:
+        """Obtiene la ruta a la base de datos SQLite"""
+        if cls._db_path is None:
+            # Path: catalogmx/packages/python/catalogmx/catalogs/sat/cfdi_4/clave_prod_serv.py
+            # Target: catalogmx/packages/shared-data/sqlite/clave_prod_serv.db
+            cls._db_path = (
+                Path(__file__).parent.parent.parent.parent.parent.parent
+                / "shared-data"
+                / "sqlite"
+                / "clave_prod_serv.db"
+            )
+        return cls._db_path
+
+    @classmethod
+    def _get_connection(cls) -> sqlite3.Connection:
+        """Obtiene conexión a la base de datos (singleton)"""
+        if cls._connection is None:
+            db_path = cls._get_db_path()
+            if not db_path.exists():
+                raise FileNotFoundError(
+                    f"Database not found at {db_path}. "
+                    "Please ensure the clave_prod_serv.db file exists."
+                )
+            cls._connection = sqlite3.connect(str(db_path))
+            cls._connection.row_factory = sqlite3.Row
+        return cls._connection
+
+    @classmethod
+    def _row_to_clave(cls, row: sqlite3.Row) -> ClaveProdServ:
+        """Convierte una fila de SQLite a ClaveProdServ"""
+        return {
+            "id": row["clave"],
+            "descripcion": row["descripcion"],
+            "incluirIVATrasladado": "Sí" if row["incluye_iva"] == 1 else "No",
+            "incluirIEPSTrasladado": "Sí" if row["incluye_ieps"] == 1 else "No",
+            "complementoQueDebeIncluir": row["complemento"] or "",
+            "palabrasSimilares": row["palabras_similares"] or "",
+            "fechaInicioVigencia": row["fecha_inicio_vigencia"] or "",
+            "fechaFinVigencia": row["fecha_fin_vigencia"] or "",
+            "estimuloFranjaFronteriza": "",
+        }
+
+    @classmethod
+    def get_all(cls) -> list[ClaveProdServ]:
+        """
+        Obtiene todas las claves de productos/servicios.
+
+        WARNING: Retorna ~52,000 productos/servicios. Para mejor rendimiento,
+        use search() o get_by_prefix() en su lugar.
+
+        Returns:
+            Lista completa de productos/servicios
+
+        Ejemplo:
+            >>> all_claves = ClaveProdServCatalog.get_all()
+            >>> print(f"Total: {len(all_claves)}")  # ~52,000
+        """
+        conn = cls._get_connection()
+        cursor = conn.cursor()
+        cursor.execute("SELECT * FROM clave_prod_serv")
+        return [cls._row_to_clave(row) for row in cursor.fetchall()]
+
+    @classmethod
+    def get_clave(cls, id: str) -> ClaveProdServ | None:
+        """
+        Obtiene una clave por su ID.
+
+        Args:
+            id: Clave de 8 dígitos (ej: "10101500", "43211500")
+
+        Returns:
+            Producto/servicio o None si no existe
+
+        Ejemplo:
+            >>> producto = ClaveProdServCatalog.get_clave("43211500")
+            >>> if producto:
+            ...     print(producto['descripcion'])
+        """
+        conn = cls._get_connection()
+        cursor = conn.cursor()
+        cursor.execute("SELECT * FROM clave_prod_serv WHERE clave = ?", (id,))
+        row = cursor.fetchone()
+        return cls._row_to_clave(row) if row else None
+
+    @classmethod
+    def is_valid(cls, id: str) -> bool:
+        """
+        Verifica si una clave de producto/servicio existe.
+
+        Args:
+            id: Clave de 8 dígitos
+
+        Returns:
+            True si existe, False en caso contrario
+
+        Ejemplo:
+            >>> ClaveProdServCatalog.is_valid("43211500")  # True
+            >>> ClaveProdServCatalog.is_valid("99999999")  # False
+        """
+        return cls.get_clave(id) is not None
+
+    @classmethod
+    def search(cls, keyword: str, limit: int = 100) -> list[ClaveProdServ]:
+        """
+        Busca productos/servicios usando FTS5 full-text search.
+
+        Busca en: descripción, complemento y palabras similares.
+
+        Args:
+            keyword: Palabra clave a buscar
+            limit: Máximo número de resultados (default: 100)
+
+        Returns:
+            Lista de productos/servicios que coinciden
+
+        Ejemplo:
+            >>> resultados = ClaveProdServCatalog.search("computadora", limit=20)
+            >>> for item in resultados:
+            ...     print(f"{item['id']}: {item['descripcion']}")
+        """
+        conn = cls._get_connection()
+        cursor = conn.cursor()
+
+        # Use FTS5 for fast full-text search
+        query = """
+            SELECT cps.*
+            FROM clave_prod_serv_fts fts
+            JOIN clave_prod_serv cps ON fts.clave = cps.clave
+            WHERE clave_prod_serv_fts MATCH ?
+            LIMIT ?
+        """
+
+        cursor.execute(query, (keyword, limit))
+        return [cls._row_to_clave(row) for row in cursor.fetchall()]
+
+    @classmethod
+    def search_simple(cls, keyword: str, limit: int = 100) -> list[ClaveProdServ]:
+        """
+        Búsqueda simple sin FTS5 (fallback o búsqueda parcial).
+
+        Args:
+            keyword: Palabra clave a buscar en descripción y palabras similares
+            limit: Máximo número de resultados (default: 100)
+
+        Returns:
+            Lista de productos/servicios que coinciden
+
+        Ejemplo:
+            >>> resultados = ClaveProdServCatalog.search_simple("comput", limit=10)
+        """
+        conn = cls._get_connection()
+        cursor = conn.cursor()
+
+        keyword_pattern = f"%{keyword}%"
+        query = """
+            SELECT * FROM clave_prod_serv
+            WHERE descripcion LIKE ? OR palabras_similares LIKE ?
+            LIMIT ?
+        """
+
+        cursor.execute(query, (keyword_pattern, keyword_pattern, limit))
+        return [cls._row_to_clave(row) for row in cursor.fetchall()]
+
+    @classmethod
+    def get_by_prefix(cls, prefix: str, limit: int = 500) -> list[ClaveProdServ]:
+        """
+        Obtiene productos/servicios por prefijo de clave.
+
+        Útil para navegación jerárquica del catálogo UNSPSC:
+        - 2 dígitos: Segmento (ej: "43" = Tecnología de información)
+        - 4 dígitos: Familia (ej: "4321" = Computadoras)
+        - 6 dígitos: Clase (ej: "432115" = Computadoras personales)
+        - 8 dígitos: Producto específico
+
+        Args:
+            prefix: Prefijo de la clave (2, 4, 6 u 8 dígitos)
+            limit: Máximo número de resultados (default: 500)
+
+        Returns:
+            Lista de productos/servicios con ese prefijo
+
+        Ejemplo:
+            >>> # Todos los productos en segmento 43 (TI)
+            >>> ti = ClaveProdServCatalog.get_by_prefix("43", limit=100)
+            >>>
+            >>> # Familia 4321 (Computadoras)
+            >>> comps = ClaveProdServCatalog.get_by_prefix("4321", limit=50)
+        """
+        conn = cls._get_connection()
+        cursor = conn.cursor()
+
+        query = """
+            SELECT * FROM clave_prod_serv
+            WHERE clave LIKE ?
+            LIMIT ?
+        """
+
+        cursor.execute(query, (f"{prefix}%", limit))
+        return [cls._row_to_clave(row) for row in cursor.fetchall()]
+
+    @classmethod
+    def get_con_iva(cls, limit: int = 1000) -> list[ClaveProdServ]:
+        """
+        Obtiene productos/servicios que incluyen IVA trasladado.
+
+        Args:
+            limit: Máximo número de resultados (default: 1000)
+
+        Returns:
+            Lista de productos/servicios con IVA
+
+        Ejemplo:
+            >>> con_iva = ClaveProdServCatalog.get_con_iva(limit=100)
+            >>> print(f"Productos con IVA: {len(con_iva)}")
+        """
+        conn = cls._get_connection()
+        cursor = conn.cursor()
+        cursor.execute("SELECT * FROM clave_prod_serv WHERE incluye_iva = 1 LIMIT ?", (limit,))
+        return [cls._row_to_clave(row) for row in cursor.fetchall()]
+
+    @classmethod
+    def get_con_ieps(cls, limit: int = 1000) -> list[ClaveProdServ]:
+        """
+        Obtiene productos/servicios que incluyen IEPS trasladado.
+
+        Args:
+            limit: Máximo número de resultados (default: 1000)
+
+        Returns:
+            Lista de productos/servicios con IEPS
+
+        Ejemplo:
+            >>> con_ieps = ClaveProdServCatalog.get_con_ieps(limit=100)
+            >>> print(f"Productos con IEPS: {len(con_ieps)}")
+        """
+        conn = cls._get_connection()
+        cursor = conn.cursor()
+        cursor.execute("SELECT * FROM clave_prod_serv WHERE incluye_ieps = 1 LIMIT ?", (limit,))
+        return [cls._row_to_clave(row) for row in cursor.fetchall()]
+
+    @classmethod
+    def get_vigentes(cls, limit: int = 10000) -> list[ClaveProdServ]:
+        """
+        Obtiene productos/servicios vigentes (sin fecha de fin de vigencia).
+
+        Args:
+            limit: Máximo número de resultados (default: 10000)
+
+        Returns:
+            Lista de productos/servicios vigentes
+
+        Ejemplo:
+            >>> vigentes = ClaveProdServCatalog.get_vigentes(limit=100)
+        """
+        conn = cls._get_connection()
+        cursor = conn.cursor()
+        cursor.execute(
+            "SELECT * FROM clave_prod_serv WHERE fecha_fin_vigencia IS NULL OR fecha_fin_vigencia = '' LIMIT ?",
+            (limit,),
+        )
+        return [cls._row_to_clave(row) for row in cursor.fetchall()]
+
+    @classmethod
+    def get_total_count(cls) -> int:
+        """
+        Obtiene el total de productos/servicios en el catálogo.
+
+        Returns:
+            Número total de productos/servicios (~52,000)
+
+        Ejemplo:
+            >>> total = ClaveProdServCatalog.get_total_count()
+            >>> print(f"Total productos/servicios: {total:,}")
+        """
+        conn = cls._get_connection()
+        cursor = conn.cursor()
+        cursor.execute("SELECT COUNT(*) FROM clave_prod_serv")
+        return cursor.fetchone()[0]
+
+    @classmethod
+    def get_estadisticas(cls) -> dict[str, int]:
+        """
+        Obtiene estadísticas del catálogo.
+
+        Returns:
+            Diccionario con estadísticas
+
+        Ejemplo:
+            >>> stats = ClaveProdServCatalog.get_estadisticas()
+            >>> print(f"Total: {stats['total']:,}")
+            >>> print(f"Con IVA: {stats['con_iva']:,}")
+            >>> print(f"Con IEPS: {stats['con_ieps']:,}")
+        """
+        conn = cls._get_connection()
+        cursor = conn.cursor()
+
+        cursor.execute("SELECT COUNT(*) FROM clave_prod_serv")
+        total = cursor.fetchone()[0]
+
+        cursor.execute("SELECT COUNT(*) FROM clave_prod_serv WHERE incluye_iva = 1")
+        con_iva = cursor.fetchone()[0]
+
+        cursor.execute("SELECT COUNT(*) FROM clave_prod_serv WHERE incluye_ieps = 1")
+        con_ieps = cursor.fetchone()[0]
+
+        cursor.execute(
+            "SELECT COUNT(*) FROM clave_prod_serv WHERE fecha_fin_vigencia IS NULL OR fecha_fin_vigencia = ''"
+        )
+        vigentes = cursor.fetchone()[0]
+
+        return {
+            "total": total,
+            "con_iva": con_iva,
+            "con_ieps": con_ieps,
+            "vigentes": vigentes,
+            "obsoletos": total - vigentes,
+        }

catalogmx/catalogs/sat/cfdi_4/clave_unidad.py

@@ -0,0 +1,298 @@
+"""
+SAT CFDI 4.0 - Clave de Unidad (c_ClaveUnidad)
+
+Catálogo de unidades de medida para productos y servicios.
+Contiene ~2,400 unidades oficiales del SAT basadas en las
+recomendaciones 20 y 21 de UN/ECE.
+"""
+
+import json
+from pathlib import Path
+from typing import TypedDict
+
+
+class ClaveUnidad(TypedDict):
+    """Estructura de una unidad de medida"""
+
+    id: str
+    nombre: str
+    descripcion: str
+    nota: str
+    fechaDeInicioDeVigencia: str
+    fechaDeFinDeVigencia: str
+    simbolo: str
+
+
+class ClaveUnidadCatalog:
+    """
+    Catálogo de claves de unidad SAT CFDI 4.0.
+
+    Características:
+    - ~2,400 unidades de medida oficiales
+    - Basado en UN/ECE Recommendation 20 y 21
+    - Incluye peso, longitud, volumen, tiempo, piezas, etc.
+    - Distingue entre unidades vigentes y obsoletas
+    - Búsqueda por ID, nombre, símbolo y categoría
+
+    Ejemplo:
+        >>> from catalogmx.catalogs.sat.cfdi_4 import ClaveUnidadCatalog
+        >>>
+        >>> # Obtener unidad por ID
+        >>> metro = ClaveUnidadCatalog.get_unidad("MTR")
+        >>> print(metro['nombre'])  # "Metro"
+        >>>
+        >>> # Buscar por nombre
+        >>> kilos = ClaveUnidadCatalog.search_by_name("kilogramo")
+        >>> for unidad in kilos:
+        ...     print(f"{unidad['id']}: {unidad['nombre']}")
+        >>>
+        >>> # Validar unidad
+        >>> if ClaveUnidadCatalog.is_valid("KGM"):
+        ...     print("Unidad válida")
+    """
+
+    _data: list[ClaveUnidad] | None = None
+    _by_id: dict[str, ClaveUnidad] | 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/sat/cfdi_4/clave_unidad.py
+        # Target: catalogmx/packages/shared-data/sat/cfdi_4.0/clave_unidad.json
+        data_path = (
+            Path(__file__).parent.parent.parent.parent.parent.parent
+            / "shared-data"
+            / "sat"
+            / "cfdi_4.0"
+            / "clave_unidad.json"
+        )
+
+        with open(data_path, encoding="utf-8") as f:
+            cls._data = json.load(f)
+
+        # Crear índice por ID
+        cls._by_id = {item["id"]: item for item in cls._data}
+
+    @classmethod
+    def get_all(cls) -> list[ClaveUnidad]:
+        """
+        Obtiene todas las unidades.
+
+        WARNING: Retorna ~2,400 unidades. Considere usar búsqueda o paginación.
+
+        Returns:
+            Lista completa de unidades
+
+        Ejemplo:
+            >>> unidades = ClaveUnidadCatalog.get_all()
+            >>> print(f"Total unidades: {len(unidades)}")
+        """
+        cls._load_data()
+        return cls._data.copy()  # type: ignore
+
+    @classmethod
+    def get_unidad(cls, id: str) -> ClaveUnidad | None:
+        """
+        Obtiene una unidad por su ID/clave.
+
+        Args:
+            id: Clave de la unidad (ej: "MTR", "KGM", "H87")
+
+        Returns:
+            Unidad o None si no existe
+
+        Ejemplo:
+            >>> metro = ClaveUnidadCatalog.get_unidad("MTR")
+            >>> print(metro['nombre'])  # "Metro"
+            >>> print(metro['simbolo'])  # "m"
+        """
+        cls._load_data()
+        return cls._by_id.get(id)  # type: ignore
+
+    @classmethod
+    def is_valid(cls, id: str) -> bool:
+        """
+        Verifica si una clave de unidad existe.
+
+        Args:
+            id: Clave de la unidad
+
+        Returns:
+            True si existe, False en caso contrario
+
+        Ejemplo:
+            >>> ClaveUnidadCatalog.is_valid("KGM")  # True
+            >>> ClaveUnidadCatalog.is_valid("INVALID")  # False
+        """
+        return cls.get_unidad(id) is not None
+
+    @classmethod
+    def search_by_name(cls, keyword: str) -> list[ClaveUnidad]:
+        """
+        Busca unidades por nombre (búsqueda parcial, case-insensitive).
+
+        Args:
+            keyword: Palabra clave a buscar en el nombre
+
+        Returns:
+            Lista de unidades que coinciden
+
+        Ejemplo:
+            >>> unidades = ClaveUnidadCatalog.search_by_name("kilogramo")
+            >>> for u in unidades:
+            ...     print(f"{u['id']}: {u['nombre']}")
+        """
+        cls._load_data()
+        keyword_lower = keyword.lower()
+        return [u for u in cls._data if keyword_lower in u["nombre"].lower()]  # type: ignore
+
+    @classmethod
+    def search_by_symbol(cls, simbolo: str) -> list[ClaveUnidad]:
+        """
+        Busca unidades por símbolo (ej: "kg", "m", "l").
+
+        Args:
+            simbolo: Símbolo a buscar
+
+        Returns:
+            Lista de unidades con ese símbolo
+
+        Ejemplo:
+            >>> metros = ClaveUnidadCatalog.search_by_symbol("m")
+            >>> for u in metros:
+            ...     print(f"{u['id']}: {u['nombre']} ({u['simbolo']})")
+        """
+        cls._load_data()
+        simbolo_lower = simbolo.lower()
+        return [u for u in cls._data if u["simbolo"].lower() == simbolo_lower]  # type: ignore
+
+    @classmethod
+    def get_vigentes(cls) -> list[ClaveUnidad]:
+        """
+        Obtiene unidades vigentes (sin fecha de fin de vigencia).
+
+        Returns:
+            Lista de unidades vigentes
+
+        Ejemplo:
+            >>> vigentes = ClaveUnidadCatalog.get_vigentes()
+            >>> print(f"Unidades vigentes: {len(vigentes)}")
+        """
+        cls._load_data()
+        return [
+            u
+            for u in cls._data  # type: ignore
+            if not u["fechaDeFinDeVigencia"] or u["fechaDeFinDeVigencia"] == ""
+        ]
+
+    @classmethod
+    def get_obsoletas(cls) -> list[ClaveUnidad]:
+        """
+        Obtiene unidades obsoletas (con fecha de fin de vigencia).
+
+        Returns:
+            Lista de unidades obsoletas
+
+        Ejemplo:
+            >>> obsoletas = ClaveUnidadCatalog.get_obsoletas()
+            >>> print(f"Unidades obsoletas: {len(obsoletas)}")
+        """
+        cls._load_data()
+        return [
+            u
+            for u in cls._data  # type: ignore
+            if u["fechaDeFinDeVigencia"] and u["fechaDeFinDeVigencia"] != ""
+        ]
+
+    @classmethod
+    def search_by_category(cls, categoria: str) -> list[ClaveUnidad]:
+        """
+        Busca unidades por categoría (en el nombre).
+
+        Categorías soportadas: peso, longitud, volumen, tiempo, pieza
+
+        Args:
+            categoria: Categoría a buscar
+
+        Returns:
+            Lista de unidades en esa categoría
+
+        Ejemplo:
+            >>> pesos = ClaveUnidadCatalog.search_by_category("peso")
+            >>> for u in pesos:
+            ...     print(f"{u['id']}: {u['nombre']}")
+        """
+        cls._load_data()
+        cat_lower = categoria.lower()
+
+        keywords: dict[str, list[str]] = {
+            "peso": ["kilogramo", "gramo", "tonelada", "libra", "onza"],
+            "longitud": [
+                "metro",
+                "centímetro",
+                "milímetro",
+                "kilómetro",
+                "pulgada",
+                "pie",
+                "yarda",
+            ],
+            "volumen": ["litro", "mililitro", "metro cúbico", "galón", "barril"],
+            "tiempo": ["hora", "minuto", "segundo", "día", "semana", "mes", "año"],
+            "pieza": ["pieza", "unidad", "paquete", "caja", "docena"],
+        }
+
+        search_words = keywords.get(cat_lower, [cat_lower])
+
+        results = []
+        for u in cls._data:  # type: ignore
+            nombre_lower = u["nombre"].lower()
+            if any(word in nombre_lower for word in search_words):
+                results.append(u)
+
+        return results
+
+    @classmethod
+    def get_total_count(cls) -> int:
+        """
+        Obtiene el total de unidades en el catálogo.
+
+        Returns:
+            Número total de unidades
+
+        Ejemplo:
+            >>> total = ClaveUnidadCatalog.get_total_count()
+            >>> print(f"Total: {total} unidades")
+        """
+        cls._load_data()
+        return len(cls._data)  # type: ignore
+
+    @classmethod
+    def get_statistics(cls) -> dict[str, int]:
+        """
+        Obtiene estadísticas del catálogo.
+
+        Returns:
+            Diccionario con estadísticas de unidades
+
+        Ejemplo:
+            >>> stats = ClaveUnidadCatalog.get_statistics()
+            >>> print(f"Total: {stats['total']}")
+            >>> print(f"Vigentes: {stats['vigentes']}")
+            >>> print(f"Obsoletas: {stats['obsoletas']}")
+        """
+        cls._load_data()
+
+        con_simbolo = sum(
+            1 for u in cls._data if u["simbolo"] and u["simbolo"] != ""  # type: ignore
+        )
+
+        return {
+            "total": len(cls._data),  # type: ignore
+            "vigentes": len(cls.get_vigentes()),
+            "obsoletas": len(cls.get_obsoletas()),
+            "con_simbolo": con_simbolo,
+            "sin_simbolo": len(cls._data) - con_simbolo,  # type: ignore
+        }