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

catalogmx/calculators/resico.py

@@ -0,0 +1,154 @@
+"""
+RESICO (Régimen Simplificado de Confianza) Calculator for Mexico
+Supports years: 2024, 2025, 2026
+
+RESICO uses a DIRECT TAX RATE system (simpler than ISR):
+- No deductions allowed
+- No fixed fee (cuota fija)
+- Tax = Total Income × Bracket Rate
+
+Official source: Artículo 113-E LISR (Ley del Impuesto Sobre la Renta)
+"""
+
+import json
+from pathlib import Path
+from typing import Literal, TypedDict
+
+RESICOYear = Literal[2024, 2025, 2026]
+RESICOPeriod = Literal["mensual", "anual"]
+
+
+class RESICOBracket(TypedDict):
+    """RESICO tax bracket structure (simplified - no cuota fija)"""
+
+    limiteInferior: float
+    limiteSuperior: float
+    tasa: float
+
+
+class RESICOCalculationResult(TypedDict):
+    """Complete RESICO calculation result"""
+
+    ingreso: float
+    periodo: str
+    year: int
+    limiteMaximo: float
+    dentroDeLimite: bool
+    bracket: dict
+    resicoCalculado: float
+    tasaEfectiva: float
+
+
+# Load RESICO tables from centralized JSON
+_RESICO_TABLES: dict | None = None
+
+
+def _load_resico_tables() -> dict:
+    """Load RESICO tables from shared JSON file"""
+    global _RESICO_TABLES
+    if _RESICO_TABLES is None:
+        json_path = (
+            Path(__file__).parent.parent.parent.parent.parent
+            / "packages"
+            / "shared-data"
+            / "resico-tables.json"
+        )
+        with open(json_path, encoding="utf-8") as f:
+            _RESICO_TABLES = json.load(f)
+    return _RESICO_TABLES
+
+
+def get_resico_brackets(year: RESICOYear, periodo: RESICOPeriod) -> list[RESICOBracket]:
+    """
+    Get RESICO tax brackets for a specific year and period
+
+    Args:
+        year: Tax year (2024, 2025, or 2026)
+        periodo: Period (mensual or anual)
+
+    Returns:
+        List of RESICO tax brackets
+    """
+    tables = _load_resico_tables()
+    year_str = str(year)
+
+    brackets_data = tables["brackets"][year_str][periodo]
+
+    brackets = []
+    for b in brackets_data:
+        bracket = RESICOBracket(
+            limiteInferior=b["limiteInferior"], limiteSuperior=b["limiteSuperior"], tasa=b["tasa"]
+        )
+        brackets.append(bracket)
+
+    return brackets
+
+
+def calculate_resico(
+    ingreso: float, periodo: RESICOPeriod = "mensual", year: RESICOYear = 2026
+) -> RESICOCalculationResult:
+    """
+    Calculate RESICO (Régimen Simplificado de Confianza) tax
+
+    RESICO uses a DIRECT TAX RATE system (not marginal like regular ISR):
+    - No deductions allowed
+    - No fixed fee (cuota fija)
+    - Tax = Total Income × Bracket Rate
+
+    Args:
+        ingreso: Taxable income for the period
+        periodo: Period (mensual or anual, default: mensual)
+        year: Tax year (default: 2026)
+
+    Returns:
+        Complete RESICO calculation result
+
+    Examples:
+        >>> # Monthly income $50,000 → bracket 1.5% → ISR = $50,000 × 1.5% = $750
+        >>> result = calculate_resico(50000, "mensual", 2026)
+        >>> print(f"RESICO: ${result['resicoCalculado']:.2f}")
+        RESICO: $750.00
+
+        >>> # Annual income $500,000 → bracket 1.1% → ISR = $500,000 × 1.1% = $5,500
+        >>> result = calculate_resico(500000, "anual", 2026)
+        >>> print(f"RESICO anual: ${result['resicoCalculado']:.2f}")
+        RESICO anual: $5500.00
+    """
+    tables = _load_resico_tables()
+
+    # Get income limits
+    limits = tables["limits"]["personaFisica"]
+    limite_maximo = (
+        limits["ingresoMensualMaximo"] if periodo == "mensual" else limits["ingresoAnualMaximo"]
+    )
+    dentro_de_limite = ingreso <= limite_maximo
+
+    # Get brackets for year and period
+    brackets = get_resico_brackets(year, periodo)
+
+    # Find applicable bracket
+    bracket = None
+    for b in brackets:
+        if b["limiteInferior"] <= ingreso <= b["limiteSuperior"]:
+            bracket = b
+            break
+
+    if bracket is None:
+        bracket = brackets[-1]  # Last bracket if not found
+
+    # RESICO calculation: Direct rate on total income (NO cuota fija, NO excedente)
+    resico_calculado = ingreso * (bracket["tasa"] / 100)
+
+    # Effective rate (should equal bracket rate for RESICO)
+    tasa_efectiva = (resico_calculado / ingreso * 100) if ingreso > 0 else 0
+
+    return RESICOCalculationResult(
+        ingreso=ingreso,
+        periodo=periodo,
+        year=year,
+        limiteMaximo=limite_maximo,
+        dentroDeLimite=dentro_de_limite,
+        bracket=dict(bracket),
+        resicoCalculado=resico_calculado,
+        tasaEfectiva=tasa_efectiva,
+    )

catalogmx/catalogs/banxico/__init__.py

@@ -4,21 +4,47 @@ catalogmx.catalogs.banxico - Catálogos de Banxico
 Catálogos incluidos:
 - BankCatalog: Bancos autorizados por Banxico
 - UDICatalog: UDIs (Unidades de Inversión)
+- TipoCambioUSDCatalog: Tipo de cambio USD/MXN FIX
+- TIIE28Catalog: TIIE 28 días
+- CETES28Catalog: CETES 28 días
+- InflacionAnualCatalog: Inflación anual (INPC)
+- SalariosMinimosCatalog: Salarios mínimos por zona
 - InstitucionesFinancieras: Tipos de instituciones del sistema financiero
 - MonedasDivisas: Monedas y divisas internacionales
 - CodigosPlazaCatalog: Códigos de plaza para CLABE
 """
 
+# Static catalogs (JSON-based, don't change frequently)
 from .banks import BankCatalog
+from .cetes_sqlite import CETESCatalog as CETES28Catalog
 from .codigos_plaza import CodigosPlazaCatalog
+from .inflacion_sqlite import InflacionCatalog as InflacionAnualCatalog
 from .instituciones_financieras import InstitucionesFinancieras
 from .monedas_divisas import MonedasDivisas
-from .udis import UDICatalog
+from .salarios_minimos_sqlite import SalariosMinimosCatalog
+from .tiie_sqlite import TIIECatalog as TIIE28Catalog
+from .tipo_cambio_usd_sqlite import TipoCambioUSDCatalog
+
+# Dynamic catalogs (SQLite-based, auto-updating)
+from .udis_sqlite import UDICatalog
+
+# Aliases for convenience
+Banks = BankCatalog
+Bancos = BankCatalog
 
 __all__ = [
+    # Main classes
     "BankCatalog",
-    "UDICatalog",
+    "CETES28Catalog",
+    "CodigosPlazaCatalog",
+    "InflacionAnualCatalog",
     "InstitucionesFinancieras",
     "MonedasDivisas",
-    "CodigosPlazaCatalog",
+    "SalariosMinimosCatalog",
+    "TIIE28Catalog",
+    "TipoCambioUSDCatalog",
+    "UDICatalog",
+    # Aliases
+    "Banks",
+    "Bancos",
 ]

catalogmx/catalogs/banxico/cetes_sqlite.py

@@ -0,0 +1,279 @@
+"""
+CETES (Certificados de la Tesorería) Catalog - SQLite Backend
+
+This module provides access to CETES rates from Banco de México using a SQLite
+database that can be automatically updated without requiring library releases.
+"""
+
+import sqlite3
+from pathlib import Path
+
+from catalogmx.data.updater import get_database_path
+
+
+class CETESCatalog:
+    """
+    Catalog of CETES (Certificados de la Tesorería) rates
+
+    CETES are short-term Mexican treasury bills and serve as the
+    risk-free rate benchmark for the Mexican market.
+
+    This catalog uses an auto-updating SQLite database backend.
+    """
+
+    _db_path: Path | None = None
+
+    @classmethod
+    def _get_db_path(cls) -> Path:
+        """Get path to database with auto-update"""
+        if cls._db_path is None:
+            cls._db_path = get_database_path(auto_update=True, max_age_hours=24)
+        return cls._db_path
+
+    @classmethod
+    def _row_to_dict(cls, row: sqlite3.Row) -> dict:
+        """Convert SQLite row to dictionary"""
+        return {
+            "fecha": row["fecha"],
+            "plazo": row["plazo"],
+            "tasa": row["tasa"],
+            "año": row["anio"],
+            "mes": row["mes"],
+            "instrumento": "CETES",  # Add instrumento field for compatibility
+        }
+
+    @classmethod
+    def get_data(cls, plazo: int = 28) -> list[dict]:
+        """
+        Get all CETES data for a specific term
+
+        :param plazo: Term in days (28, 91, 182, or 364)
+        :return: List of all CETES records
+        """
+        db = sqlite3.connect(cls._get_db_path())
+        db.row_factory = sqlite3.Row
+        cursor = db.execute(
+            """
+            SELECT fecha, plazo, tasa, anio, mes
+            FROM cetes
+            WHERE plazo = ?
+            ORDER BY fecha
+            """,
+            (plazo,),
+        )
+        results = [cls._row_to_dict(row) for row in cursor.fetchall()]
+        db.close()
+        return results
+
+    @classmethod
+    def get_por_fecha(cls, fecha: str, plazo: int = 28) -> dict | None:
+        """
+        Get CETES rate for a specific date and term
+
+        :param fecha: Date string in YYYY-MM-DD format
+        :param plazo: Term in days (28, 91, 182, or 364)
+        :return: CETES record or None if not found
+        """
+        db = sqlite3.connect(cls._get_db_path())
+        db.row_factory = sqlite3.Row
+
+        cursor = db.execute(
+            """
+            SELECT fecha, plazo, tasa, anio, mes
+            FROM cetes
+            WHERE fecha = ? AND plazo = ?
+            LIMIT 1
+            """,
+            (fecha, plazo),
+        )
+        row = cursor.fetchone()
+        db.close()
+
+        if row:
+            return cls._row_to_dict(row)
+        return None
+
+    @classmethod
+    def get_actual(cls, plazo: int = 28) -> dict | None:
+        """
+        Get most recent CETES rate
+
+        :param plazo: Term in days (28, 91, 182, or 364)
+        :return: Latest CETES record
+        """
+        db = sqlite3.connect(cls._get_db_path())
+        db.row_factory = sqlite3.Row
+
+        cursor = db.execute(
+            """
+            SELECT fecha, plazo, tasa, anio, mes
+            FROM cetes
+            WHERE plazo = ?
+            ORDER BY fecha DESC
+            LIMIT 1
+            """,
+            (plazo,),
+        )
+        row = cursor.fetchone()
+        db.close()
+
+        if row:
+            return cls._row_to_dict(row)
+        return None
+
+    @classmethod
+    def get_valor_actual(cls, plazo: int = 28) -> float | None:
+        """
+        Get current CETES rate value
+
+        :param plazo: Term in days (28, 91, 182, or 364)
+        :return: Current CETES rate or None
+        """
+        record = cls.get_actual(plazo)
+        return record.get("tasa") if record else None
+
+    @classmethod
+    def get_por_anio(cls, anio: int, plazo: int = 28) -> list[dict]:
+        """
+        Get all CETES rates for a specific year and term
+
+        :param anio: Year (e.g., 2024)
+        :param plazo: Term in days (28, 91, 182, or 364)
+        :return: List of CETES records for the year
+        """
+        db = sqlite3.connect(cls._get_db_path())
+        db.row_factory = sqlite3.Row
+
+        cursor = db.execute(
+            """
+            SELECT fecha, plazo, tasa, anio, mes
+            FROM cetes
+            WHERE anio = ? AND plazo = ?
+            ORDER BY fecha
+            """,
+            (anio, plazo),
+        )
+        results = [cls._row_to_dict(row) for row in cursor.fetchall()]
+        db.close()
+        return results
+
+    @classmethod
+    def calcular_variacion(cls, fecha_inicio: str, fecha_fin: str, plazo: int = 28) -> float | None:
+        """
+        Calculate variation between two dates
+
+        :param fecha_inicio: Start date (YYYY-MM-DD)
+        :param fecha_fin: End date (YYYY-MM-DD)
+        :param plazo: Term in days (28, 91, 182, or 364)
+        :return: Variation in percentage points or None
+        """
+        record_inicio = cls.get_por_fecha(fecha_inicio, plazo)
+        record_fin = cls.get_por_fecha(fecha_fin, plazo)
+
+        if not record_inicio or not record_fin:
+            return None
+
+        tasa_inicio = record_inicio.get("tasa")
+        tasa_fin = record_fin.get("tasa")
+
+        if tasa_inicio is None or tasa_fin is None:
+            return None
+
+        # Return difference in percentage points (not percentage change)
+        return tasa_fin - tasa_inicio
+
+    @classmethod
+    def get_promedio_anual(cls, anio: int, plazo: int = 28) -> float | None:
+        """
+        Calculate annual average CETES rate
+
+        :param anio: Year (e.g., 2024)
+        :param plazo: Term in days (28, 91, 182, or 364)
+        :return: Annual average rate or None if no data
+        """
+        records = cls.get_por_anio(anio, plazo)
+        if not records:
+            return None
+
+        tasas = [r.get("tasa") for r in records if r.get("tasa") is not None]
+        return sum(tasas) / len(tasas) if tasas else None
+
+    @classmethod
+    def get_tasa_actual(cls, plazo: int = 28) -> float | None:
+        """
+        Get current CETES rate value (alias for get_valor_actual)
+
+        :param plazo: Term in days (28, 91, 182, or 364)
+        :return: Current CETES rate or None
+        """
+        return cls.get_valor_actual(plazo)
+
+    @classmethod
+    def calcular_rendimiento(
+        cls, monto: float, fecha_inicio: str, fecha_fin: str, plazo: int = 28
+    ) -> float | None:
+        """
+        Calculate CETES return (principal + interest)
+
+        :param monto: Initial investment amount
+        :param fecha_inicio: Start date (YYYY-MM-DD)
+        :param fecha_fin: End date (YYYY-MM-DD)
+        :param plazo: Term in days (28, 91, 182, or 364)
+        :return: Total return (principal + interest) or None if data not available
+        """
+        from datetime import datetime
+
+        record_inicio = cls.get_por_fecha(fecha_inicio, plazo)
+        record_fin = cls.get_por_fecha(fecha_fin, plazo)
+
+        if not record_inicio and not record_fin:
+            return None
+
+        # Use available rate (start or end, or average if both)
+        tasa = None
+        if record_inicio and record_fin:
+            tasa = (record_inicio.get("tasa", 0) + record_fin.get("tasa", 0)) / 2
+        elif record_inicio:
+            tasa = record_inicio.get("tasa")
+        elif record_fin:
+            tasa = record_fin.get("tasa")
+
+        if tasa is None:
+            return None
+
+        # Calculate days between dates
+        date_inicio = datetime.strptime(fecha_inicio, "%Y-%m-%d")
+        date_fin = datetime.strptime(fecha_fin, "%Y-%m-%d")
+        dias = (date_fin - date_inicio).days
+
+        if dias <= 0:
+            return monto
+
+        # Calculate simple interest return
+        interes = monto * (tasa / 100) * (dias / 365)
+        return round(monto + interes, 2)
+
+
+# Convenience functions for CETES 28 (most commonly used)
+def get_cetes_actual(plazo: int = 28) -> dict | None:
+    """Get most recent CETES rate"""
+    return CETESCatalog.get_actual(plazo)
+
+
+def get_cetes_por_fecha(fecha: str, plazo: int = 28) -> dict | None:
+    """Get CETES rate for a specific date"""
+    return CETESCatalog.get_por_fecha(fecha, plazo)
+
+
+def get_cetes_valor_actual(plazo: int = 28) -> float | None:
+    """Get current CETES rate value"""
+    return CETESCatalog.get_valor_actual(plazo)
+
+
+# Export commonly used functions and classes
+__all__ = [
+    "CETESCatalog",
+    "get_cetes_actual",
+    "get_cetes_por_fecha",
+    "get_cetes_valor_actual",
+]