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

catalogmx/__init__.py

@@ -1,56 +1,170 @@
+"""
+catalogmx - Mexican Data Validation and Catalog Library
+
+A comprehensive library for validating Mexican identifiers (RFC, CURP, CLABE, NSS),
+accessing official catalogs (SAT, Banxico, INEGI, SEPOMEX, IFT, CNBV), and
+calculating taxes and payroll (ISR, RESICO, IMSS, IVA, Costo del Trabajador).
+
+Usage:
+    # Validators - Simple helper functions
+    from catalogmx import is_valid_rfc, is_valid_curp, is_valid_clabe, is_valid_nss
+
+    is_valid_rfc('PEGJ900515KL8')  # True
+    is_valid_curp('PEGJ900515HJCRRN05')  # True
+    is_valid_clabe('002010077777777771')  # True
+    is_valid_nss('12345678903')  # True
+
+    # Generators
+    from catalogmx import generate_rfc_persona_fisica, generate_curp, generate_clabe
+
+    rfc = generate_rfc_persona_fisica(
+        nombre='Juan',
+        apellido_paterno='Pérez',
+        apellido_materno='García',
+        fecha_nacimiento='1990-05-15'
+    )
+
+    clabe = generate_clabe(
+        bank_code='002',      # Banamex
+        branch_code='010',    # Branch
+        account_number='07777777777'
+    )  # Returns: '002010077777777771'
+
+    # Calculators
+    from catalogmx.calculators import calculate_isr, calculate_resico
+    from catalogmx.calculators import calcular_cuotas_obrero_patronales
+    from catalogmx.calculators import IVACalculator, calcular_costo_total
+
+    # Catalogs
+    from catalogmx.catalogs.sat.cfdi_4 import FormaPago, MetodoPago, UsoCFDI
+    from catalogmx.catalogs.banxico import Banks
+    from catalogmx.catalogs.inegi import States, Municipios
+    from catalogmx.catalogs.sepomex import CodigosPostales
+"""
+
 __version__ = "0.3.0"
 
-# RFC imports
-# Modern helper functions (recommended API)
-from .helpers import (
+# =============================================================================
+# Modern Helper Functions (recommended API)
+# =============================================================================
+from catalogmx.helpers import (
+    # RFC helpers
     detect_rfc_type,
+    # CLABE helpers
+    generate_clabe,
+    generate_clabe_random,
     # CURP helpers
     generate_curp,
-    # RFC helpers
     generate_rfc_persona_fisica,
     generate_rfc_persona_moral,
+    get_clabe_info,
     get_curp_info,
+    # NSS helpers
+    get_nss_info,
+    # Utility
+    get_project_root,
+    is_valid_clabe,
     is_valid_curp,
+    is_valid_nss,
     is_valid_rfc,
+    validate_clabe,
     validate_curp,
+    validate_nss,
     validate_rfc,
 )
 
-# CURP imports
-from .validators.curp import (
+# =============================================================================
+# Validator Classes (for advanced usage)
+# =============================================================================
+from catalogmx.validators.clabe import (
+    CLABECheckDigitError,
+    CLABEException,
+    CLABELengthError,
+    CLABEStructureError,
+    CLABEValidator,
+)
+from catalogmx.validators.curp import (
     CURPException,
     CURPGenerator,
     CURPLengthError,
     CURPStructureError,
     CURPValidator,
 )
-from .validators.rfc import (
+from catalogmx.validators.nss import (
+    NSSCheckDigitError,
+    NSSException,
+    NSSLengthError,
+    NSSStructureError,
+    NSSValidator,
+)
+from catalogmx.validators.rfc import (
     RFCGenerator,
     RFCGeneratorFisicas,
     RFCGeneratorMorales,
     RFCValidator,
 )
 
+# =============================================================================
+# Generators (identity generation with Faker - optional dependency)
+# =============================================================================
+# Note: Requires faker package - install with: pip install catalogmx[generators]
+# from catalogmx.generators import generate_identity, generate_persona_fisica, generate_persona_moral
+
+# =============================================================================
+# Submodules (import as needed)
+# =============================================================================
+# Catalogs: from catalogmx import catalogs
+# Calculators: from catalogmx import calculators
+# Validators: from catalogmx import validators
+# Generators: from catalogmx.generators import generate_identity
+
 __all__ = [
-    # RFC Classes (legacy/advanced usage)
-    "RFCValidator",
-    "RFCGenerator",
-    "RFCGeneratorFisicas",
-    "RFCGeneratorMorales",
-    # CURP Classes (legacy/advanced usage)
-    "CURPValidator",
-    "CURPGenerator",
-    "CURPException",
-    "CURPLengthError",
-    "CURPStructureError",
-    # Modern helper functions (recommended)
+    # Version
+    "__version__",
+    # RFC Helper Functions
     "generate_rfc_persona_fisica",
     "generate_rfc_persona_moral",
     "validate_rfc",
     "detect_rfc_type",
     "is_valid_rfc",
+    # RFC Classes
+    "RFCValidator",
+    "RFCGenerator",
+    "RFCGeneratorFisicas",
+    "RFCGeneratorMorales",
+    # CURP Helper Functions
     "generate_curp",
     "validate_curp",
     "get_curp_info",
     "is_valid_curp",
+    # CURP Classes
+    "CURPValidator",
+    "CURPGenerator",
+    "CURPException",
+    "CURPLengthError",
+    "CURPStructureError",
+    # CLABE Helper Functions
+    "generate_clabe",
+    "generate_clabe_random",
+    "validate_clabe",
+    "get_clabe_info",
+    "is_valid_clabe",
+    # CLABE Classes
+    "CLABEValidator",
+    "CLABEException",
+    "CLABELengthError",
+    "CLABEStructureError",
+    "CLABECheckDigitError",
+    # NSS Helper Functions
+    "validate_nss",
+    "get_nss_info",
+    "is_valid_nss",
+    # NSS Classes
+    "NSSValidator",
+    "NSSException",
+    "NSSLengthError",
+    "NSSStructureError",
+    "NSSCheckDigitError",
+    # Utility
+    "get_project_root",
 ]

catalogmx/calculators/__init__.py

@@ -0,0 +1,113 @@
+"""
+Calculators for Mexican taxes and payroll
+
+Available calculators:
+- ISR (Impuesto Sobre la Renta) - Income Tax
+- RESICO (Régimen Simplificado de Confianza) - Simplified Trust Regime
+- IMSS (Instituto Mexicano del Seguro Social) - Social Security Contributions
+- IVA (Impuesto al Valor Agregado) - Value Added Tax
+- IEPS (Impuesto Especial sobre Producción y Servicios) - Special Production and Services Tax
+- Retenciones (Withholdings) - ISR and IVA withholdings
+- Impuestos Locales (Local Taxes) - State and municipal taxes
+- Costo Trabajador (Worker Cost) - Total cost of employing a worker
+"""
+
+from catalogmx.calculators.costo_trabajador import (
+    CostoTotalResult,
+    calcular_costo_total,
+    obtener_dias_vacaciones,
+)
+from catalogmx.calculators.impuestos import (
+    IEPSCalculationResult,
+    IEPSCalculator,
+    IEPSCategoria,
+    IEPSTasa,
+    ImpuestoEstatal,
+    ImpuestosLocalesCalculator,
+    IVACalculationResult,
+    IVACalculator,
+    IVATasa,
+    RetencionCalculationResult,
+    RetencionCalculator,
+    RetencionISR,
+    RetencionIVA,
+)
+from catalogmx.calculators.imss import (
+    ClaseRiesgo,
+    CuotasIMSSResult,
+    IMSSYear,
+    Modalidad10Result,
+    Modalidad40Result,
+    UMAInfo,
+    ZonaSalario,
+    calcular_cuotas_obrero_patronales,
+    calcular_modalidad_10,
+    calcular_modalidad_40,
+    get_salario_minimo,
+    get_uma,
+)
+from catalogmx.calculators.isr import (
+    ISRCalculationResult,
+    ISRPeriod,
+    ISRYear,
+    calculate_isr,
+    calculate_subsidy,
+    get_isr_brackets,
+)
+from catalogmx.calculators.resico import (
+    RESICOCalculationResult,
+    RESICOPeriod,
+    RESICOYear,
+    calculate_resico,
+    get_resico_brackets,
+)
+
+__all__ = [
+    # ISR
+    "calculate_isr",
+    "get_isr_brackets",
+    "calculate_subsidy",
+    "ISRYear",
+    "ISRPeriod",
+    "ISRCalculationResult",
+    # RESICO
+    "calculate_resico",
+    "get_resico_brackets",
+    "RESICOYear",
+    "RESICOPeriod",
+    "RESICOCalculationResult",
+    # IMSS
+    "calcular_cuotas_obrero_patronales",
+    "calcular_modalidad_40",
+    "calcular_modalidad_10",
+    "get_uma",
+    "get_salario_minimo",
+    "IMSSYear",
+    "ZonaSalario",
+    "ClaseRiesgo",
+    "CuotasIMSSResult",
+    "Modalidad40Result",
+    "Modalidad10Result",
+    "UMAInfo",
+    # IVA
+    "IVACalculator",
+    "IVACalculationResult",
+    "IVATasa",
+    # IEPS
+    "IEPSCalculator",
+    "IEPSCalculationResult",
+    "IEPSCategoria",
+    "IEPSTasa",
+    # Retenciones
+    "RetencionCalculator",
+    "RetencionCalculationResult",
+    "RetencionISR",
+    "RetencionIVA",
+    # Impuestos Locales
+    "ImpuestosLocalesCalculator",
+    "ImpuestoEstatal",
+    # Costo Trabajador
+    "calcular_costo_total",
+    "obtener_dias_vacaciones",
+    "CostoTotalResult",
+]

catalogmx/calculators/costo_trabajador.py

@@ -0,0 +1,213 @@
+"""
+Costo Total del Trabajador Calculator for Mexico
+Calculates the true cost of hiring an employee in Mexico including all contributions and reserves
+
+Official sources:
+- Ley Federal del Trabajo (LFT)
+- IMSS contribution tables
+- Infonavit contributions
+- State payroll tax laws
+"""
+
+from typing import TypedDict
+
+from catalogmx.calculators.impuestos import ImpuestosLocalesCalculator
+from catalogmx.calculators.imss import IMSSYear, calcular_cuotas_obrero_patronales
+
+
+class CostoTotalResult(TypedDict):
+    """Total worker cost calculation result"""
+
+    salario_bruto_mensual: float
+    cuotas_imss_patronales: float
+    infonavit: float
+    impuesto_nomina: float
+    reserva_aguinaldo: float
+    reserva_prima_vacacional: float
+    reserva_vacaciones: float
+    ptu_estimado: float
+    costo_total_mensual: float
+    costo_total_anual: float
+    factor_costo: float
+
+
+# Vacation days according to LFT 2023 (Article 76)
+DIAS_VACACIONES_POR_ANTIGUEDAD = {
+    1: 12,
+    2: 14,
+    3: 16,
+    4: 18,
+    5: 20,
+    6: 22,
+    7: 22,
+    8: 22,
+    9: 22,
+    10: 22,
+    11: 24,
+    12: 24,
+    13: 24,
+    14: 24,
+    15: 24,
+    16: 26,
+    17: 26,
+    18: 26,
+    19: 26,
+    20: 26,
+    21: 28,
+    22: 28,
+    23: 28,
+    24: 28,
+    25: 28,
+    26: 30,
+    27: 30,
+    28: 30,
+    29: 30,
+    30: 30,
+    31: 32,
+    32: 32,
+    33: 32,
+    34: 32,
+    35: 32,
+}
+
+
+def obtener_dias_vacaciones(antiguedad_anos: int) -> int:
+    """
+    Get vacation days based on seniority according to LFT 2023
+
+    Args:
+        antiguedad_anos: Years of seniority (1-35+)
+
+    Returns:
+        Number of vacation days
+
+    Examples:
+        >>> obtener_dias_vacaciones(1)
+        12
+        >>> obtener_dias_vacaciones(5)
+        20
+        >>> obtener_dias_vacaciones(40)
+        32
+    """
+    if antiguedad_anos <= 0:
+        return 12
+    elif antiguedad_anos <= 35:
+        return DIAS_VACACIONES_POR_ANTIGUEDAD.get(antiguedad_anos, 32)
+    else:
+        return 32
+
+
+def calcular_costo_total(
+    salario_mensual_bruto: float,
+    cve_estado: str = "09",
+    antiguedad_anos: int = 1,
+    dias_aguinaldo: int = 15,
+    incluir_ptu: bool = False,
+    porcentaje_ptu: float = 10.0,
+    year: IMSSYear = 2026,
+) -> CostoTotalResult:
+    """
+    Calculate the total cost of employing a worker in Mexico
+
+    This calculator helps employers understand the true cost of hiring someone
+    by including all mandatory contributions, taxes, and labor law reserves.
+
+    Args:
+        salario_mensual_bruto: Monthly gross salary (base pay)
+        cve_estado: State code for payroll tax calculation (default: "09" CDMX)
+        antiguedad_anos: Years of seniority (affects vacation days, default: 1)
+        dias_aguinaldo: Aguinaldo days (minimum 15, default: 15)
+        incluir_ptu: Include PTU (profit sharing) reserve (default: False)
+        porcentaje_ptu: PTU percentage if included (default: 10.0%)
+        year: Year for IMSS calculations (default: 2026)
+
+    Returns:
+        Complete breakdown of employer costs including:
+        - IMSS employer contributions
+        - Infonavit (5% of SBC)
+        - Payroll tax (varies by state)
+        - Aguinaldo reserve
+        - Vacation bonus reserve
+        - Vacation pay reserve
+        - Optional PTU reserve
+
+    Examples:
+        >>> # Calculate cost for $15,000/month employee in CDMX
+        >>> result = calcular_costo_total(15000, "09", 1)
+        >>> print(f"Total monthly cost: ${result['costo_total_mensual']:.2f}")
+        Total monthly cost: $18750.00
+
+        >>> # Calculate with PTU included
+        >>> result = calcular_costo_total(20000, "09", 3, incluir_ptu=True)
+        >>> print(f"Factor: {result['factor_costo']:.2f}x")
+        Factor: 1.35x
+    """
+    # 1. Calculate daily wage (assuming 30-day month for calculation purposes)
+    salario_diario = salario_mensual_bruto / 30.0
+
+    # 2. Calculate IMSS employer contributions
+    cuotas_imss = calcular_cuotas_obrero_patronales(
+        salario_diario=salario_diario, dias=30, year=year
+    )
+    cuotas_imss_patronales = cuotas_imss["total_patron"]
+
+    # 3. Calculate Infonavit (5% of SBC)
+    salario_base_cotizacion = cuotas_imss["salario_base_cotizacion"]
+    infonavit = salario_base_cotizacion * 0.05
+
+    # 4. Calculate payroll tax (varies by state, typically 2-3%)
+    impuesto_nomina = ImpuestosLocalesCalculator.calcular_impuesto_nomina(
+        total_percepciones=salario_mensual_bruto, cve_estado=cve_estado
+    )
+
+    # 5. Calculate monthly reserves
+
+    # Aguinaldo: dias_aguinaldo / 12 months
+    reserva_aguinaldo = (salario_diario * dias_aguinaldo) / 12.0
+
+    # Vacation days based on seniority (LFT 2023)
+    dias_vacaciones = obtener_dias_vacaciones(antiguedad_anos)
+
+    # Vacation reserve: vacation days / 12 months
+    reserva_vacaciones = (salario_diario * dias_vacaciones) / 12.0
+
+    # Vacation bonus (prima vacacional): 25% of vacation days value
+    reserva_prima_vacacional = reserva_vacaciones * 0.25
+
+    # 6. Optional PTU reserve
+    ptu_estimado = 0.0
+    if incluir_ptu:
+        # PTU is typically calculated on annual salary
+        # We estimate monthly reserve as (annual_salary * ptu_percentage) / 12
+        ptu_estimado = (salario_mensual_bruto * 12 * (porcentaje_ptu / 100)) / 12.0
+
+    # 7. Calculate totals
+    costo_total_mensual = (
+        salario_mensual_bruto
+        + cuotas_imss_patronales
+        + infonavit
+        + impuesto_nomina
+        + reserva_aguinaldo
+        + reserva_prima_vacacional
+        + reserva_vacaciones
+        + ptu_estimado
+    )
+
+    costo_total_anual = costo_total_mensual * 12
+
+    # Factor: how much the real cost is compared to base salary
+    factor_costo = costo_total_mensual / salario_mensual_bruto
+
+    return CostoTotalResult(
+        salario_bruto_mensual=salario_mensual_bruto,
+        cuotas_imss_patronales=cuotas_imss_patronales,
+        infonavit=infonavit,
+        impuesto_nomina=impuesto_nomina,
+        reserva_aguinaldo=reserva_aguinaldo,
+        reserva_prima_vacacional=reserva_prima_vacacional,
+        reserva_vacaciones=reserva_vacaciones,
+        ptu_estimado=ptu_estimado,
+        costo_total_mensual=costo_total_mensual,
+        costo_total_anual=costo_total_anual,
+        factor_costo=factor_costo,
+    )