catalogmx 0.3.0__py3-none-any.whl

catalogmx/helpers.py

@@ -0,0 +1,324 @@
+#!/usr/bin/python
+"""
+Modern, user-friendly API for RFC and CURP generation and validation.
+
+This module provides simple functions for common use cases, making it easier
+to work with Mexican identification codes without dealing with class constructors.
+"""
+
+import datetime
+
+from .validators.curp import CURPGenerator, CURPValidator
+from .validators.rfc import RFCGeneratorFisicas, RFCGeneratorMorales, RFCValidator
+
+# ============================================================================
+# RFC Helper Functions
+# ============================================================================
+
+
+def generate_rfc_persona_fisica(
+    nombre: str,
+    apellido_paterno: str,
+    apellido_materno: str,
+    fecha_nacimiento: datetime.date | str,
+    **kwargs,
+) -> str:
+    """
+    Generate RFC for a natural person (Persona Física).
+
+    Args:
+        nombre: First name(s)
+        apellido_paterno: Father's surname
+        apellido_materno: Mother's surname
+        fecha_nacimiento: Birth date (datetime.date or 'YYYY-MM-DD' string)
+        **kwargs: Additional arguments passed to RFCGeneratorFisicas
+
+    Returns:
+        str: 13-character RFC code
+
+    Example:
+        >>> rfc = generate_rfc_persona_fisica(
+        ...     nombre='Juan',
+        ...     apellido_paterno='Pérez',
+        ...     apellido_materno='García',
+        ...     fecha_nacimiento='1990-05-15'
+        ... )
+        >>> print(rfc)  # PEGJ900515...
+    """
+    # Convert string date to datetime.date if needed
+    if isinstance(fecha_nacimiento, str):
+        fecha_nacimiento = datetime.datetime.strptime(fecha_nacimiento, "%Y-%m-%d").date()
+
+    generator = RFCGeneratorFisicas(
+        paterno=apellido_paterno,
+        materno=apellido_materno,
+        nombre=nombre,
+        fecha=fecha_nacimiento,
+        **kwargs,
+    )
+    return generator.rfc
+
+
+def generate_rfc_persona_moral(
+    razon_social: str, fecha_constitucion: datetime.date | str, **kwargs
+) -> str:
+    """
+    Generate RFC for a legal entity (Persona Moral/company).
+
+    Args:
+        razon_social: Company name
+        fecha_constitucion: Constitution date (datetime.date or 'YYYY-MM-DD' string)
+        **kwargs: Additional arguments passed to RFCGeneratorMorales
+
+    Returns:
+        str: 12-character RFC code
+
+    Example:
+        >>> rfc = generate_rfc_persona_moral(
+        ...     razon_social='Grupo Bimbo S.A.B. de C.V.',
+        ...     fecha_constitucion='1981-06-15'
+        ... )
+        >>> print(rfc)  # GBI810615...
+    """
+    # Convert string date to datetime.date if needed
+    if isinstance(fecha_constitucion, str):
+        fecha_constitucion = datetime.datetime.strptime(fecha_constitucion, "%Y-%m-%d").date()
+
+    generator = RFCGeneratorMorales(razon_social=razon_social, fecha=fecha_constitucion, **kwargs)
+    return generator.rfc
+
+
+def validate_rfc(rfc: str, check_checksum: bool = True) -> bool:
+    """
+    Validate an RFC code.
+
+    Args:
+        rfc: RFC code to validate
+        check_checksum: Whether to validate the checksum digit (default: True)
+
+    Returns:
+        bool: True if valid, False otherwise
+
+    Example:
+        >>> validate_rfc('PEGJ900515KL8')
+        True
+        >>> validate_rfc('INVALID')
+        False
+    """
+    try:
+        validator = RFCValidator(rfc)
+        if not validator.validate_general_regex():
+            return False
+        if check_checksum:
+            return validator.validate_checksum()
+        return True
+    except:
+        return False
+
+
+def detect_rfc_type(rfc: str) -> str | None:
+    """
+    Detect the type of RFC (Persona Física, Persona Moral, or Genérico).
+
+    Args:
+        rfc: RFC code to analyze
+
+    Returns:
+        str: 'fisica', 'moral', 'generico', or None if invalid
+
+    Example:
+        >>> detect_rfc_type('PEGJ900515KL8')
+        'fisica'
+        >>> detect_rfc_type('GBI810615945')
+        'moral'
+    """
+    try:
+        validator = RFCValidator(rfc)
+        tipo = validator.detect_fisica_moral()
+        if tipo == "Persona Física":
+            return "fisica"
+        elif tipo == "Persona Moral":
+            return "moral"
+        elif tipo == "Genérico":
+            return "generico"
+        return None
+    except:
+        return None
+
+
+# ============================================================================
+# CURP Helper Functions
+# ============================================================================
+
+
+def generate_curp(
+    nombre: str,
+    apellido_paterno: str,
+    apellido_materno: str | None,
+    fecha_nacimiento: datetime.date | str,
+    sexo: str,
+    estado: str,
+    differentiator: str | None = None,
+) -> str:
+    """
+    Generate a CURP code.
+
+    Args:
+        nombre: First name(s)
+        apellido_paterno: Father's surname
+        apellido_materno: Mother's surname (can be empty string or None)
+        fecha_nacimiento: Birth date (datetime.date or 'YYYY-MM-DD' string)
+        sexo: Gender ('H' for male, 'M' for female)
+        estado: Birth state (name or 2-letter code)
+        differentiator: Optional custom differentiator (position 17)
+
+    Returns:
+        str: 18-character CURP code
+
+    Example:
+        >>> curp = generate_curp(
+        ...     nombre='Juan',
+        ...     apellido_paterno='Pérez',
+        ...     apellido_materno='García',
+        ...     fecha_nacimiento='1990-05-15',
+        ...     sexo='H',
+        ...     estado='Jalisco'
+        ... )
+        >>> print(curp)  # PEGJ900515HJCRRN...
+    """
+    # Convert string date to datetime.date if needed
+    if isinstance(fecha_nacimiento, str):
+        fecha_nacimiento = datetime.datetime.strptime(fecha_nacimiento, "%Y-%m-%d").date()
+
+    # Handle empty apellido_materno
+    if not apellido_materno:
+        apellido_materno = ""
+
+    generator = CURPGenerator(
+        nombre=nombre,
+        paterno=apellido_paterno,
+        materno=apellido_materno,
+        fecha_nacimiento=fecha_nacimiento,
+        sexo=sexo,
+        estado=estado,
+    )
+
+    # If custom differentiator is provided, regenerate homoclave
+    if differentiator is not None:
+        # Generate base CURP (first 16 characters)
+        base = (
+            generator.generate_letters()
+            + generator.generate_date()
+            + generator.sexo
+            + generator.get_state_code(generator.estado)
+            + generator.generate_consonants()
+        )
+        # Add custom differentiator and calculate check digit
+        check_digit = CURPGenerator.calculate_check_digit(base + differentiator)
+        return base + differentiator + check_digit
+
+    return generator.curp
+
+
+def validate_curp(curp: str, check_digit: bool = True) -> bool:
+    """
+    Validate a CURP code.
+
+    Args:
+        curp: CURP code to validate
+        check_digit: Whether to validate the check digit (default: True)
+
+    Returns:
+        bool: True if valid, False otherwise
+
+    Example:
+        >>> validate_curp('PEGJ900515HJCRRN05')
+        True
+        >>> validate_curp('INVALID')
+        False
+    """
+    try:
+        validator = CURPValidator(curp)
+        if not validator.validate():
+            return False
+        if check_digit:
+            return validator.validate_check_digit()
+        return True
+    except:
+        return False
+
+
+def get_curp_info(curp: str) -> dict | None:
+    """
+    Extract information from a CURP code.
+
+    Args:
+        curp: CURP code to analyze
+
+    Returns:
+        dict: Extracted information or None if invalid
+
+    Example:
+        >>> info = get_curp_info('PEGJ900515HJCRRN05')
+        >>> print(info['fecha_nacimiento'])
+        '1990-05-15'
+        >>> print(info['sexo'])
+        'Hombre'
+    """
+    try:
+        validator = CURPValidator(curp)
+        if not validator.validate():
+            return None
+
+        # Extract information
+        year = int(curp[4:6])
+        # Assume year 2000+ if < 50, otherwise 1900+
+        year = 2000 + year if year < 50 else 1900 + year
+        month = int(curp[6:8])
+        day = int(curp[8:10])
+
+        sexo_code = curp[10]
+        estado_code = curp[11:13]
+
+        return {
+            "fecha_nacimiento": f"{year:04d}-{month:02d}-{day:02d}",
+            "sexo": "Hombre" if sexo_code == "H" else "Mujer",
+            "sexo_code": sexo_code,
+            "estado_code": estado_code,
+            "differentiator": curp[16],
+            "check_digit": curp[17],
+            "check_digit_valid": validator.validate_check_digit(),
+        }
+    except:
+        return None
+
+
+# ============================================================================
+# Quick validation functions
+# ============================================================================
+
+
+def is_valid_rfc(rfc: str) -> bool:
+    """Quick RFC validation. Alias for validate_rfc()."""
+    return validate_rfc(rfc)
+
+
+def is_valid_curp(curp: str) -> bool:
+    """Quick CURP validation. Alias for validate_curp()."""
+    return validate_curp(curp)
+
+
+# ============================================================================
+# Path Helper Functions
+# ============================================================================
+from pathlib import Path
+
+
+def get_project_root() -> Path:
+    """Returns the project root folder by searching for a .git directory."""
+    current_path = Path(__file__).parent
+    while current_path.parent != current_path:
+        if (current_path / ".git").exists():
+            return current_path
+        current_path = current_path.parent
+    raise FileNotFoundError("Project root not found. Could not find .git directory.")

catalogmx/utils/text.py

@@ -0,0 +1,55 @@
+"""
+Text normalization utilities for catalogmx
+==========================================
+
+Provides accent-insensitive text normalization for searching across catalogs.
+"""
+
+try:
+    from unidecode import unidecode
+except ImportError:
+    # Fallback if unidecode not available
+    def unidecode(text: str) -> str:
+        """Fallback implementation using unicodedata."""
+        import unicodedata
+
+        nfd = unicodedata.normalize("NFD", text)
+        return "".join(char for char in nfd if unicodedata.category(char) != "Mn")
+
+
+def normalize_text(text: str) -> str:
+    """
+    Normalize text by removing accents and converting to uppercase.
+    Makes text searchable without worrying about accents or case.
+
+    Args:
+        text: Text to normalize
+
+    Returns:
+        Normalized text (uppercase, no accents)
+
+    Examples:
+        >>> normalize_text("México")
+        'MEXICO'
+        >>> normalize_text("San José")
+        'SAN JOSE'
+        >>> normalize_text("Michoacán de Ocampo")
+        'MICHOACAN DE OCAMPO'
+    """
+    return unidecode(text).upper()
+
+
+def normalize_for_search(text: str) -> str:
+    """
+    Alias for normalize_text for clarity in search contexts.
+
+    Args:
+        text: Text to normalize for searching
+
+    Returns:
+        Normalized text suitable for accent-insensitive search
+    """
+    return normalize_text(text)
+
+
+__all__ = ["normalize_text", "normalize_for_search", "unidecode"]

catalogmx/validators/clabe.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+"""
+CLABE (Clave Bancaria Estandarizada) Validator
+
+CLABE is the standardized 18-digit bank account number used in Mexico for
+interbank electronic transfers (SPEI).
+
+Structure:
+    - 3 digits: Bank code
+    - 3 digits: Branch/Plaza code
+    - 11 digits: Account number
+    - 1 digit: Check digit (modulo 10 algorithm)
+
+Example: 002010077777777771
+    002: Banamex
+    010: Branch code
+    07777777777: Account number
+    1: Check digit
+"""
+
+
+class CLABEException(Exception):
+    pass
+
+
+class CLABELengthError(CLABEException):
+    pass
+
+
+class CLABEStructureError(CLABEException):
+    pass
+
+
+class CLABECheckDigitError(CLABEException):
+    pass
+
+
+class CLABEValidator:
+    """
+    Validates CLABE (Clave Bancaria Estandarizada) bank account numbers
+    """
+
+    LENGTH = 18
+
+    # Weights for check digit calculation (positions 0-16)
+    WEIGHTS = [3, 7, 1] * 6  # Pattern repeats: 3,7,1,3,7,1,...
+
+    def __init__(self, clabe: str | None) -> None:
+        """
+        :param clabe: The CLABE number to validate
+        """
+        self.clabe = ""
+        if bool(clabe) and isinstance(clabe, str):
+            self.clabe = clabe.strip()
+
+    def validate(self) -> bool:
+        """
+        Validates the CLABE structure and check digit
+        :return: True if valid, raises exception if invalid
+        """
+        value = self.clabe
+
+        # Check length
+        if len(value) != self.LENGTH:
+            raise CLABELengthError(f"CLABE length must be {self.LENGTH} digits, got {len(value)}")
+
+        # Check if all characters are digits
+        if not value.isdigit():
+            raise CLABEStructureError("CLABE must contain only digits")
+
+        # Validate check digit
+        if not self.verify_check_digit(value):
+            raise CLABECheckDigitError("Invalid CLABE check digit")
+
+        return True
+
+    def is_valid(self) -> bool:
+        """
+        Checks if CLABE is valid without raising exceptions
+        :return: True if valid, False otherwise
+        """
+        try:
+            return self.validate()
+        except CLABEException:
+            return False
+
+    @classmethod
+    def calculate_check_digit(cls, clabe_17: str) -> str:
+        """
+        Calculates the check digit for a 17-digit CLABE
+
+        Algorithm:
+        1. Multiply each digit by its weight (3,7,1 pattern)
+        2. Take modulo 10 of each result
+        3. Sum all results
+        4. Take modulo 10 of the sum
+        5. Subtract from 10
+        6. Take modulo 10 of the result
+
+        :param clabe_17: First 17 digits of CLABE
+        :return: Check digit (0-9)
+        """
+        if len(clabe_17) != 17:
+            raise CLABELengthError("Need exactly 17 digits to calculate check digit")
+
+        if not clabe_17.isdigit():
+            raise CLABEStructureError("CLABE must contain only digits")
+
+        # Calculate weighted sum
+        weighted_sum = 0
+        for i, digit in enumerate(clabe_17):
+            product = int(digit) * cls.WEIGHTS[i]
+            weighted_sum += product % 10
+
+        # Calculate check digit
+        check_digit = (10 - (weighted_sum % 10)) % 10
+
+        return str(check_digit)
+
+    @classmethod
+    def verify_check_digit(cls, clabe: str) -> bool:
+        """
+        Verifies the check digit of an 18-digit CLABE
+
+        :param clabe: Complete 18-digit CLABE
+        :return: True if check digit is valid, False otherwise
+        """
+        if len(clabe) != cls.LENGTH:
+            return False
+
+        calculated = cls.calculate_check_digit(clabe[:17])
+        return calculated == clabe[17]
+
+    def get_bank_code(self) -> str | None:
+        """
+        Extracts the bank code (first 3 digits)
+        :return: Bank code as string
+        """
+        if len(self.clabe) >= 3:
+            return self.clabe[:3]
+        return None
+
+    def get_branch_code(self) -> str | None:
+        """
+        Extracts the branch/plaza code (digits 4-6)
+        :return: Branch code as string
+        """
+        if len(self.clabe) >= 6:
+            return self.clabe[3:6]
+        return None
+
+    def get_account_number(self) -> str | None:
+        """
+        Extracts the account number (digits 7-17)
+        :return: Account number as string
+        """
+        if len(self.clabe) >= 17:
+            return self.clabe[6:17]
+        return None
+
+    def get_check_digit(self) -> str | None:
+        """
+        Extracts the check digit (digit 18)
+        :return: Check digit as string
+        """
+        if len(self.clabe) == self.LENGTH:
+            return self.clabe[17]
+        return None
+
+    def get_parts(self) -> dict[str, str] | None:
+        """
+        Returns all CLABE parts as a dictionary
+        :return: Dictionary with bank_code, branch_code, account_number, check_digit
+        """
+        if not self.is_valid():
+            return None
+
+        return {
+            "bank_code": self.get_bank_code(),
+            "branch_code": self.get_branch_code(),
+            "account_number": self.get_account_number(),
+            "check_digit": self.get_check_digit(),
+            "clabe": self.clabe,
+        }
+
+
+def validate_clabe(clabe: str | None) -> bool:
+    """
+    Helper function to validate a CLABE
+
+    :param clabe: CLABE number as string
+    :return: True if valid, False otherwise
+    """
+    validator = CLABEValidator(clabe)
+    return validator.is_valid()
+
+
+def generate_clabe(bank_code: str | int, branch_code: str | int, account_number: str | int) -> str:
+    """
+    Generates a complete CLABE with check digit
+
+    :param bank_code: 3-digit bank code
+    :param branch_code: 3-digit branch code
+    :param account_number: 11-digit account number
+    :return: Complete 18-digit CLABE
+    """
+    # Ensure all parts are strings and properly formatted
+    bank_code = str(bank_code).zfill(3)
+    branch_code = str(branch_code).zfill(3)
+    account_number = str(account_number).zfill(11)
+
+    if len(bank_code) != 3:
+        raise CLABEStructureError("Bank code must be 3 digits")
+    if len(branch_code) != 3:
+        raise CLABEStructureError("Branch code must be 3 digits")
+    if len(account_number) != 11:
+        raise CLABEStructureError("Account number must be 11 digits")
+
+    clabe_17 = bank_code + branch_code + account_number
+    check_digit = CLABEValidator.calculate_check_digit(clabe_17)
+
+    return clabe_17 + check_digit
+
+
+def get_clabe_info(clabe: str | None) -> dict[str, str] | None:
+    """
+    Helper function to get information from a CLABE
+
+    :param clabe: CLABE number as string
+    :return: Dictionary with CLABE parts or None if invalid
+    """
+    validator = CLABEValidator(clabe)
+    return validator.get_parts()