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

catalogmx/validators/clabe.py

@@ -167,7 +167,7 @@ class CLABEValidator:
             return self.clabe[17]
         return None
 
-    def get_parts(self) -> dict[str, str] | None:
+    def get_parts(self) -> dict[str, str | None] | None:
         """
         Returns all CLABE parts as a dictionary
         :return: Dictionary with bank_code, branch_code, account_number, check_digit
@@ -222,7 +222,7 @@ def generate_clabe(bank_code: str | int, branch_code: str | int, account_number:
     return clabe_17 + check_digit
 
 
-def get_clabe_info(clabe: str | None) -> dict[str, str] | None:
+def get_clabe_info(clabe: str | None) -> dict[str, str | None] | None:
     """
     Helper function to get information from a CLABE
 
@@ -231,3 +231,53 @@ def get_clabe_info(clabe: str | None) -> dict[str, str] | None:
     """
     validator = CLABEValidator(clabe)
     return validator.get_parts()
+
+
+def generate_clabe_random(
+    bank_code: str | int | None = None,
+    plaza_code: str | int | None = None,
+    account_number: str | int | None = None,
+) -> str:
+    """
+    Generates a random valid CLABE with optional parameters.
+    Any parameter not provided will be randomly generated.
+
+    :param bank_code: Optional 3-digit bank code (e.g., '012' for BBVA)
+    :param plaza_code: Optional 3-digit plaza code
+    :param account_number: Optional 11-digit account number
+    :return: Complete 18-digit CLABE
+
+    Example:
+        >>> # Fully random CLABE
+        >>> clabe = generate_clabe_random()
+        >>> len(clabe)
+        18
+        >>> # CLABE for specific bank
+        >>> clabe = generate_clabe_random(bank_code='012')
+        >>> clabe[:3]
+        '012'
+        >>> # Fully specified
+        >>> clabe = generate_clabe_random('002', '010', '12345678901')
+        >>> clabe
+        '002010123456789018'
+    """
+    import random
+
+    # Generate bank code if not provided
+    if bank_code is None:
+        # Common SPEI bank codes
+        common_banks = ["002", "012", "014", "021", "036", "044", "058", "072", "127"]
+        bank_code = random.choice(common_banks)
+    bank_str = str(bank_code).zfill(3)
+
+    # Generate plaza code if not provided
+    if plaza_code is None:
+        plaza_code = random.randint(1, 999)
+    plaza_str = str(plaza_code).zfill(3)
+
+    # Generate account number if not provided
+    if account_number is None:
+        account_number = random.randint(0, 99999999999)
+    account_str = str(account_number).zfill(11)
+
+    return generate_clabe(bank_str, plaza_str, account_str)

catalogmx/validators/nss.py

@@ -4,18 +4,19 @@ NSS (Número de Seguridad Social) Validator
 
 NSS is the 11-digit social security number issued by IMSS (Instituto Mexicano del Seguro Social).
 
-Structure:
-    - 2 digits: Subdelegation code
-    - 2 digits: Year of registration (last 2 digits)
-    - 2 digits: Registration serial number
-    - 5 digits: Sequential number
+Structure (11 digits):
+    - 2 digits: Subdelegation code (IMSS office)
+    - 2 digits: Registration year (last 2 digits)
+    - 2 digits: Birth year (last 2 digits)
+    - 4 digits: Sequential number
     - 1 digit: Check digit (modified Luhn algorithm)
 
 Example: 12345678903
     12: Subdelegation
-    34: Year (2034 or 1934)
-    56: Serial
-    78903: Sequential and check digit
+    34: Registration year (2034 or 1934)
+    56: Birth year (2056 or 1956)
+    7890: Sequential
+    3: Check digit
 
 Note: The check digit uses a modified Luhn algorithm specific to NSS.
 """
@@ -145,7 +146,7 @@ class NSSValidator:
             return self.nss[:2]
         return None
 
-    def get_year(self) -> str | None:
+    def get_registration_year(self) -> str | None:
         """
         Extracts the registration year (digits 3-4, last 2 digits of year)
         Note: This is ambiguous - could be 19XX or 20XX
@@ -155,10 +156,11 @@ class NSSValidator:
             return self.nss[2:4]
         return None
 
-    def get_serial(self) -> str | None:
+    def get_birth_year(self) -> str | None:
         """
-        Extracts the registration serial (digits 5-6)
-        :return: Serial number as string
+        Extracts the birth year (digits 5-6, last 2 digits of year)
+        Note: This is ambiguous - could be 19XX or 20XX
+        :return: Year suffix as string
         """
         if len(self.nss) >= 6:
             return self.nss[4:6]
@@ -182,18 +184,18 @@ class NSSValidator:
             return self.nss[10]
         return None
 
-    def get_parts(self) -> dict[str, str] | None:
+    def get_parts(self) -> dict[str, str | None] | None:
         """
         Returns all NSS parts as a dictionary
-        :return: Dictionary with subdelegation, year, serial, sequential, check_digit
+        :return: Dictionary with subdelegation, registration_year, birth_year, sequential, check_digit
         """
         if not self.is_valid():
             return None
 
         return {
             "subdelegation": self.get_subdelegation(),
-            "year": self.get_year(),
-            "serial": self.get_serial(),
+            "registration_year": self.get_registration_year(),
+            "birth_year": self.get_birth_year(),
             "sequential": self.get_sequential(),
             "check_digit": self.get_check_digit(),
             "nss": self.nss,
@@ -212,39 +214,42 @@ def validate_nss(nss: str | None) -> bool:
 
 
 def generate_nss(
-    subdelegation: str | int, year: str | int, serial: str | int, sequential: str | int
+    subdelegation: str | int,
+    registration_year: str | int,
+    birth_year: str | int,
+    sequential: str | int,
 ) -> str:
     """
     Generates a complete NSS with check digit
 
     :param subdelegation: 2-digit subdelegation code
-    :param year: 2-digit year (last 2 digits)
-    :param serial: 2-digit serial number
+    :param registration_year: 2-digit registration year (last 2 digits)
+    :param birth_year: 2-digit birth year (last 2 digits)
     :param sequential: 4-digit sequential number
     :return: Complete 11-digit NSS
     """
     # Ensure all parts are strings and properly formatted
     subdelegation = str(subdelegation).zfill(2)
-    year = str(year).zfill(2)
-    serial = str(serial).zfill(2)
+    registration_year = str(registration_year).zfill(2)
+    birth_year = str(birth_year).zfill(2)
     sequential = str(sequential).zfill(4)
 
     if len(subdelegation) != 2:
         raise NSSStructureError("Subdelegation must be 2 digits")
-    if len(year) != 2:
-        raise NSSStructureError("Year must be 2 digits")
-    if len(serial) != 2:
-        raise NSSStructureError("Serial must be 2 digits")
+    if len(registration_year) != 2:
+        raise NSSStructureError("Registration year must be 2 digits")
+    if len(birth_year) != 2:
+        raise NSSStructureError("Birth year must be 2 digits")
     if len(sequential) != 4:
         raise NSSStructureError("Sequential must be 4 digits")
 
-    nss_10 = subdelegation + year + serial + sequential
+    nss_10 = subdelegation + registration_year + birth_year + sequential
     check_digit = NSSValidator.calculate_check_digit(nss_10)
 
     return nss_10 + check_digit
 
 
-def get_nss_info(nss: str | None) -> dict[str, str] | None:
+def get_nss_info(nss: str | None) -> dict[str, str | None] | None:
     """
     Helper function to get information from an NSS
 

catalogmx/validators/rfc.py

@@ -264,8 +264,7 @@ class RFCValidator(RFCGeneral):
                 return "Persona Física"
             if self.is_moral():
                 return "Persona Moral"
-        else:
-            return "RFC Inválido"
+        return "RFC Inválido"
 
     def is_generic(self) -> bool:
         """
@@ -322,7 +321,7 @@ class RFCValidator(RFCGeneral):
         return False
 
     @classmethod
-    def calculate_last_digit(cls, rfc: str, with_checksum: bool = True) -> str | bool:
+    def calculate_last_digit(cls, rfc: str, with_checksum: bool = True) -> str:
         """
         Calculates the checksum of an RFC.
 
@@ -332,7 +331,7 @@ class RFCValidator(RFCGeneral):
         if bool(rfc) and isinstance(rfc, str):
             str_rfc = rfc.strip().upper()
         else:
-            return False
+            return ""
         if with_checksum:
             str_rfc = str_rfc[:-1]
         assert len(str_rfc) in (11, 12)
@@ -412,14 +411,13 @@ class RFCGeneratorUtils(RFCGeneral):
         "MI",
         "COMPAÑIA",
         "COMPAÑÍA",
+        "COMPANIA",  # Without accent
         "CIA",
         "CIA.",
         "SOCIEDAD",
         "SOC",
         "SOC.",
-        "COOPERATIVA",
-        "COOP",
-        "COOP.",
+        # Note: COOPERATIVA is NOT excluded according to SAT spec
         "S.A.",
         "SA",
         "S.A",
@@ -511,6 +509,31 @@ class RFCGeneratorUtils(RFCGeneral):
         "18": "DIECIOCHO",
         "19": "DIECINUEVE",
         "20": "VEINTE",
+        "21": "VEINTIUNO",
+        "22": "VEINTIDOS",
+        "23": "VEINTITRES",
+        "24": "VEINTICUATRO",
+        "25": "VEINTICINCO",
+        "26": "VEINTISEIS",
+        "27": "VEINTISIETE",
+        "28": "VEINTIOCHO",
+        "29": "VEINTINUEVE",
+        "30": "TREINTA",
+        "40": "CUARENTA",
+        "50": "CINCUENTA",
+        "60": "SESENTA",
+        "70": "SETENTA",
+        "80": "OCHENTA",
+        "90": "NOVENTA",
+        "100": "CIEN",
+        "200": "DOSCIENTOS",
+        "300": "TRESCIENTOS",
+        "400": "CUATROCIENTOS",
+        "500": "QUINIENTOS",
+        "600": "SEISCIENTOS",
+        "700": "SETECIENTOS",
+        "800": "OCHOCIENTOS",
+        "900": "NOVECIENTOS",
     }
 
     # Tabla de números romanos a arábigos
@@ -535,8 +558,61 @@ class RFCGeneratorUtils(RFCGeneral):
         "XVIII": 18,
         "XIX": 19,
         "XX": 20,
+        "XXI": 21,
+        "XXII": 22,
+        "XXIII": 23,
+        "XXIV": 24,
+        "XXV": 25,
+        "XXVI": 26,
+        "XXVII": 27,
+        "XXVIII": 28,
+        "XXIX": 29,
+        "XXX": 30,
     }
 
+    @classmethod
+    def _convert_arabigo_a_texto(cls, num: int) -> str:
+        """Convert an Arabic number to text (supports 0-100000)"""
+        if num < 0:
+            return str(num)
+        if str(num) in cls.numeros_texto:
+            return cls.numeros_texto[str(num)]
+        if num == 100000:
+            return "CIEN MIL"
+
+        parts = []
+
+        # Thousands (1000-99999)
+        if num >= 1000:
+            thousands = num // 1000
+            if thousands == 1:
+                parts.append("MIL")
+            else:
+                parts.append(cls._convert_arabigo_a_texto(thousands))
+                parts.append("MIL")
+            num = num % 1000
+
+        # Hundreds (100-999)
+        if num >= 100:
+            hundreds = (num // 100) * 100
+            if str(hundreds) in cls.numeros_texto:
+                parts.append(cls.numeros_texto[str(hundreds)])
+            num = num % 100
+
+        # Tens and units (1-99)
+        if num > 0:
+            if str(num) in cls.numeros_texto:
+                parts.append(cls.numeros_texto[str(num)])
+            elif num >= 30:
+                tens = (num // 10) * 10
+                units = num % 10
+                if str(tens) in cls.numeros_texto:
+                    parts.append(cls.numeros_texto[str(tens)])
+                if units > 0 and str(units) in cls.numeros_texto:
+                    parts.append(cls.numeros_texto[str(units)])
+
+        return " ".join(parts) if parts else str(num)
+
     @classmethod
     def convertir_numero_a_texto(cls, numero_str: str) -> str:
         """Convierte un número (arábigo o romano) a su representación en texto"""
@@ -544,19 +620,14 @@ class RFCGeneratorUtils(RFCGeneral):
 
         # Intentar como número romano
         if numero_str in cls.numeros_romanos:
-            numero_arabigo = str(cls.numeros_romanos[numero_str])
-            if numero_arabigo in cls.numeros_texto:
-                return cls.numeros_texto[numero_arabigo]
+            arabigo = cls.numeros_romanos[numero_str]
+            return cls._convert_arabigo_a_texto(arabigo)
 
         # Intentar como número arábigo
-        if numero_str in cls.numeros_texto:
-            return cls.numeros_texto[numero_str]
-
-        # Si no está en la tabla, intentar convertir dígitos
         try:
             num = int(numero_str)
-            if 0 <= num <= 20:
-                return cls.numeros_texto[str(num)]
+            if num >= 0:
+                return cls._convert_arabigo_a_texto(num)
         except ValueError:
             pass
 
@@ -564,18 +635,25 @@ class RFCGeneratorUtils(RFCGeneral):
 
     @classmethod
     def clean_name(cls, nombre: str) -> str:
-        return (
-            "".join(
-                char if char in cls.allowed_chars else unidecode.unidecode(char)
-                for char in " ".join(
-                    elem for elem in nombre.split(" ") if elem not in cls.excluded_words_fisicas
-                )
-                .strip()
-                .upper()
-            )
-            .strip()
-            .upper()
+        # Remove apostrophes without adding space (O'farril -> OFARRIL)
+        nombre = nombre.replace("'", "")
+        # Remove dots
+        nombre = nombre.replace(".", " ")
+        # Process and filter excluded words
+        cleaned = " ".join(
+            elem for elem in nombre.split() if elem.upper() not in cls.excluded_words_fisicas
         )
+        # Convert each character: preserve allowed chars, use unidecode for others
+        result = []
+        for char in cleaned.upper():
+            if char in cls.allowed_chars or char == " ":
+                result.append(char)
+            else:
+                # Convert non-allowed characters via unidecode
+                decoded = unidecode.unidecode(char).upper()
+                result.append("".join(c for c in decoded if c in cls.allowed_chars or c == " "))
+        final = "".join(result)
+        return final.strip()
 
     @staticmethod
     def name_adapter(name: str, non_strict: bool = False) -> str:
@@ -607,7 +685,7 @@ class RFCGeneratorFisicas(RFCGeneratorUtils):
         return self._paterno
 
     @paterno.setter
-    def paterno(self, name: str):
+    def paterno(self, name: str) -> None:
         self._paterno = self.name_adapter(name)
 
     @property
@@ -615,7 +693,7 @@ class RFCGeneratorFisicas(RFCGeneratorUtils):
         return self._materno
 
     @materno.setter
-    def materno(self, name: str):
+    def materno(self, name: str) -> None:
         self._materno = self.name_adapter(name, non_strict=True)
 
     @property
@@ -623,7 +701,7 @@ class RFCGeneratorFisicas(RFCGeneratorUtils):
         return self._nombre
 
     @nombre.setter
-    def nombre(self, name: str):
+    def nombre(self, name: str) -> None:
         self._nombre = self.name_adapter(name)
 
     @property
@@ -631,7 +709,7 @@ class RFCGeneratorFisicas(RFCGeneratorUtils):
         return self._dob
 
     @dob.setter
-    def dob(self, date: datetime.date):
+    def dob(self, date: datetime.date) -> None:
         if isinstance(date, datetime.date):
             self._dob = date
 
@@ -648,27 +726,55 @@ class RFCGeneratorFisicas(RFCGeneratorUtils):
         return self.dob.strftime("%y%m%d")
 
     def generate_letters(self) -> str:
-        extra_letter = False
-        clave = []
-        clave.append(self.paterno_calculo[0])
-        second_value = list(
-            filter(lambda x: x >= 0, map(self.paterno_calculo[1:].find, self.vocales))
+        # Get parts of compound surnames
+        paterno_parts = [p for p in self.paterno_calculo.split() if p]
+        materno_parts = [p for p in self.materno_calculo.split() if p]
+
+        paterno_first = paterno_parts[0] if paterno_parts else ""
+        nombre_safe = self.nombre_iniciales if self.nombre_iniciales else "X"
+
+        # Check if materno originally had prepositions (de, del, la, los, las)
+        original_materno_upper = self.materno.upper().strip()
+        materno_had_prepositions = (
+            original_materno_upper.startswith("DE ")
+            or original_materno_upper.startswith("DEL ")
+            or original_materno_upper.startswith("LA ")
+            or original_materno_upper.startswith("LOS ")
+            or original_materno_upper.startswith("LAS ")
         )
-        if len(second_value) > 0:
-            clave.append(self.paterno_calculo[min(second_value) + 1])
-        else:
-            extra_letter = True
-        if self.materno_calculo:
-            clave.append(self.materno_calculo[0])
+
+        # Determine effective materno: use second word of paterno if materno was preposition-based or empty
+        effective_materno_first = materno_parts[0] if materno_parts else ""
+        if len(paterno_parts) >= 2 and (materno_had_prepositions or not effective_materno_first):
+            effective_materno_first = paterno_parts[1] if len(paterno_parts) >= 2 else ""
+
+        clave = ""
+
+        # Regla 4: Apellido paterno de 1-2 letras
+        if paterno_first and len(paterno_first) <= 2 and effective_materno_first:
+            clave = paterno_first[0] if paterno_first else "X"
+            clave += effective_materno_first[0] if effective_materno_first else "X"
+            clave += nombre_safe[0] if nombre_safe else "X"
+            clave += nombre_safe[1] if len(nombre_safe) > 1 else "X"
+        # Regla 7: Un solo apellido (sin materno)
+        elif not effective_materno_first:
+            apellido = paterno_first if paterno_first else "X"
+            clave = apellido[0] if apellido else "X"
+            clave += apellido[1] if len(apellido) > 1 else "X"
+            clave += nombre_safe[0] if nombre_safe else "X"
+            clave += nombre_safe[1] if len(nombre_safe) > 1 else "X"
+        # Regla 1: Formación básica
         else:
-            if extra_letter:
-                clave.append(self.paterno_calculo[1])
+            clave = paterno_first[0] if paterno_first else "X"
+            # Find first vowel after first letter
+            second_value = list(filter(lambda x: x >= 0, map(paterno_first[1:].find, self.vocales)))
+            if second_value:
+                clave += paterno_first[min(second_value) + 1]
             else:
-                extra_letter = True
-        clave.append(self.nombre_iniciales[0])
-        if extra_letter:
-            clave.append(self.nombre_iniciales[1])
-        clave = "".join(clave)
+                clave += "X"
+            clave += effective_materno_first[0] if effective_materno_first else "X"
+            clave += nombre_safe[0] if nombre_safe else "X"
+
         if clave in self.cacophonic_words:
             clave = clave[:-1] + "X"
         return clave
@@ -758,7 +864,7 @@ class RFCGeneratorMorales(RFCGeneratorUtils):
         return self._razon_social
 
     @razon_social.setter
-    def razon_social(self, name: str):
+    def razon_social(self, name: str) -> None:
         if isinstance(name, str):
             self._razon_social = name.upper().strip()
         else:
@@ -769,7 +875,7 @@ class RFCGeneratorMorales(RFCGeneratorUtils):
         return self._fecha
 
     @fecha.setter
-    def fecha(self, date: datetime.date):
+    def fecha(self, date: datetime.date) -> None:
         if isinstance(date, datetime.date):
             self._fecha = date
         else:
@@ -789,6 +895,16 @@ class RFCGeneratorMorales(RFCGeneratorUtils):
         """Generate date portion in YYMMDD format"""
         return self.fecha.strftime("%y%m%d")
 
+    # Special character to word conversions according to SAT specification
+    # These only apply when the character is standalone (surrounded by spaces/boundaries)
+    special_char_words = {
+        "@": "ARROBA",
+        "%": "PORCIENTO",
+        "#": "NUMERO",
+        "(": "ABRE",
+        "/": "DIAGONAL",
+    }
+
     @property
     def razon_social_calculo(self) -> str:
         """
@@ -800,8 +916,21 @@ class RFCGeneratorMorales(RFCGeneratorUtils):
         - Convert numbers (arabic and roman) to text
         - Handle consonant compounds (CH → C, LL → L)
         """
+        import re
+
         razon = self.razon_social.upper().strip()
 
+        # Step 0: Handle special characters - different treatment for standalone vs embedded
+        # Standalone special chars get converted to words, embedded ones are removed
+        for char, word in self.special_char_words.items():
+            # Replace standalone special chars with their word equivalents
+            escaped = re.escape(char)
+            razon = re.sub(rf"(^|\s){escaped}(\s|$)", rf"\1{word}\2", razon)
+
+        # Remove special characters that are embedded inside words (not standalone)
+        for char in self.special_char_words.keys():
+            razon = razon.replace(char, "")
+
         # Step 1: First pass - remove excluded words with punctuation patterns
         # This handles cases like "S.A.", "S. A.", etc.
         # Process longer words first to avoid partial matches (e.g., S.A.B. before S.A.)
@@ -878,8 +1007,12 @@ class RFCGeneratorMorales(RFCGeneratorUtils):
             elif word_clean not in self.excluded_words_morales:
                 filtered_words.append(word_clean)
 
+        # If ALL words were excluded, keep the original words (the company name itself)
+        # This handles cases like "Al" where "AL" is an excluded word but is the actual name
+        words_to_use = filtered_words if filtered_words else [w.upper() for w in words_converted]
+
         # Step 7: Clean remaining special characters and accents
-        cleaned = " ".join(filtered_words)
+        cleaned = " ".join(words_to_use)
         result = ""
         for char in cleaned:
             if char in self.allowed_chars: