Metadata-Version: 2.4
Name: identity_mx
Version: 0.1.1
Summary: Generador de CURP y RFC mexicanos
Author-email: Kinnara Digital <feedback@kinnaradigital.com>
License: MIT
Project-URL: Homepage, https://github.com/Kinnara-Digital/identity-mx
Project-URL: Repository, https://github.com/Kinnara-Digital/identity-mx
Project-URL: Issues, https://github.com/Kinnara-Digital/identity-mx/issues
Project-URL: Documentation, https://github.com/Kinnara-Digital/identity-mx#readme
Keywords: México,mexico,MX,mx,CURP,curp,RFC,rfc,generador,identificacion
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

## Generador de CURP y RFC para ciudadanos mexicanos

Herramienta para generar Clave Única de Registro de Población (CURP) y el Registro Federal de Contribuyentes (RFC),
datos que se emplean en diversos trámites en México.
- La CURP es asignada por la Secretaría de Gobernación (SEGOB) y sirve para demostrar que existes legalmente ante el gobierno mexicano. Se estructura con 18 caracteres alfanuméricos (letras y números) que se dividen en 7 bloques de información personal. Su diseño permite que cada clave sea única para cada habitante de México.
- El RFC es asignado por el Servicio de Administración Tributaria (SAT) y sirve para dar seguimiento a tus obligaciones y derechos relacionados al ser contribuyente. El RFC para personas físicas se estructura con 13 caracteres alfanuméricos (letras y números). Utiliza una fórmula muy similar a la de la CURP, pero es más corto e incluye tres dígitos finales únicos generados por el SAT

> **Aviso importante:** los valores generados no deben considerarse oficiales
> ni sustituir una validación ante las autoridades correspondientes. Esta
> herramienta sirve únicamente como apoyo para generar la estructura base de
> la CURP y el RFC, con base en la documentación consultada a finales de 2021.

## Instalación

### Usando pip

```bash
pip install identity_mx
```

### Desde el repositorio

```bash
git clone https://github.com/Kinnara-Digital/identity-mx.git
cd identity-mx
pip install .
```

## Uso

### Como librería Python

```python
from identity_mx import generar_curp_rfc

datos = {
    "nombre": "Juan",
    "primero": "Pérez",
    "segundo": "López",
    "genero": "H",
    "edo_nac": "DF",
    "dia_nac": "20",
    "mes_nac": "06",
    "anio_nac": "1999"
}

resultado = generar_curp_rfc(datos)
print(resultado)
# {'curp': 'PELJ990620HDFRPN04', 'rfc': 'PELJ9906202A3'}
```

### Por línea de comandos

Una vez instalado, puedes usar el comando `identity-mx`:

```bash
identity-mx Juan Pérez López H DF 20 06 1999
```

Salida:
```
{'curp': 'PELJ990620HDFRPN04', 'rfc': 'PELJ9906202A3'}
```

### Casos especiales

Si no tienes segundo apellido:

```python
datos = {
    "nombre": "María",
    "primero": "González",
    "segundo": "",  # Vacío
    "genero": "M",
    "edo_nac": "MC",
    "dia_nac": "20",
    "mes_nac": "06",
    "anio_nac": "1999"
}

resultado = generar_curp_rfc(datos)
print(resultado)
# {'curp': 'GOXM990620MMCNXR07', 'rfc': 'GOMA990620PA8'}
```


Si no necesitas la CURP (solo RFC), se utiliza el género 'X' correspondiente a 'No Binario' 
y el estado de nacimiento 'NE' correspondiente a 'Nacido en el Extranjero':

```python
datos = {
    "nombre": "Carlos",
    "primero": "Sánchez",
    "segundo": "Martínez",
    "genero": "X",  # No Binario
    "edo_nac": "NE",  # Nacido en el Extranjero
    "dia_nac": "20",
    "mes_nac": "06",
    "anio_nac": "1999"
}
```


## Datos requeridos

- Nombre(s).
- Primer apellido.
- Segundo apellido (opcional).
- Género: únicamente `H` (Hombre) / `M` (Mujer) / `X` (No Binario).
- Clave del estado de nacimiento.
- Día de nacimiento con exactamente 2 dígitos.
- Mes de nacimiento con exactamente 2 dígitos.
- Año de nacimiento con exactamente 4 dígitos.

### Claves de estado aceptadas

`AS`, `BC`, `BS`, `CC`, `CS`, `CH`, `CL`, `CM`, `DF`, `DG`, `GT`, `GR`, `HG`,
`JC`, `MC`, `MN`, `MS`, `NT`, `NL`, `OC`, `PL`, `QT`, `QR`, `SP`, `SL`, `SR`,
`TC`, `TS`, `TL`, `VZ`, `ZS` y `NE`.


## Manejo de errores

La función lanza excepciones `ValueError` cuando los datos no son válidos:

```python
from identity_mx import generar_curp_rfc

try:
    # Mes inválido (mes 13 no existe)
    resultado = generar_curp_rfc({
        "nombre": "Test",
        "primero": "Test",
        "segundo": "",
        "genero": "H",
        "edo_nac": "DG",
        "dia_nac": "15",
        "mes_nac": "13",  # ❌ Inválido
        "anio_nac": "1990"
    })
except ValueError as e:
    print(f"Error: {e}")
    # Error: El campo Mes de nacimiento(mes_nac) debe estar entre 01 y 12.
```

### Guía completa de errores y soluciones

| Mensaje de Error | Causa | Solución |
|---|---|---|
| `Los siguientes parámetros no pueden estar vacíos: [campos]` | Uno o más campos requeridos están vacíos o contienen solo espacios | Asegúrate de proporcionar valores válidos para `nombre`, `primero`, `genero`, `edo_nac`, `dia_nac`, `mes_nac` y `anio_nac`. El campo `segundo` (segundo apellido) es opcional. |
| `Los siguientes campos contienen caracteres inválidos (solo letras, espacios y letras acentuadas/ñ permitidos): [campos]` | Nombres o apellidos contienen números, símbolos o caracteres especiales no permitidos | Usa solo letras (con o sin acentos), espacios y puntos. Ejemplos válidos: `Juan`, `José María`, `García-López` |
| `El campo Género(genero) debe ser 'H', 'M' o 'X'.` | Género no es uno de los valores permitidos | Utiliza: `H` (Hombre), `M` (Mujer) o `X` (No Binario). Asegúrate de usar mayúsculas. |
| `El campo Estado de nacimiento(edo_nac) debe ser uno de los siguientes valores: AS, BC, BS, ...` | Código de estado inválido o no reconocido | Usa uno de los códigos válidos: `AS`, `BC`, `BS`, `CC`, `CS`, `CH`, `CL`, `CM`, `DF`, `DG`, `GT`, `GR`, `HG`, `JC`, `MC`, `MN`, `MS`, `NT`, `NL`, `OC`, `PL`, `QT`, `QR`, `SP`, `SL`, `SR`, `TC`, `TS`, `TL`, `VZ`, `ZS`, `NE`. Verifica que sea un código de 2 caracteres en mayúsculas. |
| `El campo Año de nacimiento(anio_nac) debe ser un número entero.` | El año no es un número válido o contiene caracteres no numéricos | Proporciona un año como número entero (ej: `1990`, `2005`). No uses comillas ni caracteres especiales. |
| `El campo Año de nacimiento(anio_nac) debe estar entre 1900 y [año actual].` | El año está fuera del rango permitido | Usa un año entre 1900 y el año actual. Ejemplo: `1985`, `2000`, etc. |
| `El campo Mes de nacimiento(mes_nac) debe tener exactamente 2 dígitos.` | El mes no tiene exactamente 2 dígitos (ej: `1` en lugar de `01`) | Siempre usa 2 dígitos, incluyendo cero a la izquierda: `01`, `02`, ..., `12`. |
| `El campo Mes de nacimiento(mes_nac) debe estar entre 01 y 12.` | El mes está fuera del rango válido (menor a 01 o mayor a 12) | Usa meses entre `01` y `12`. Ejemplos: `01` (enero), `06` (junio), `12` (diciembre). |
| `El campo Día de nacimiento(dia_nac) debe tener exactamente 2 dígitos.` | El día no tiene exactamente 2 dígitos (ej: `5` en lugar de `05`) | Siempre usa 2 dígitos, incluyendo cero a la izquierda: `01`, `02`, ..., `31`. |
| `El campo Día de nacimiento(dia_nac) debe estar entre 01 y 31.` | El día está fuera del rango válido (menor a 01 o mayor a 31) | Usa días entre `01` y `31`. Ejemplos: `01`, `15`, `31`. |
| `El campo Día de nacimiento(dia_nac) no es válido para la fecha DD/MM/YYYY.` | La fecha es imposible (ej: 31 de febrero, 31 de abril) o 29 de febrero en año no bisiesto | Verifica que la fecha sea válida. Por ejemplo: febrero solo tiene 28 o 29 días (29 solo en años bisiestos), abril solo tiene 30 días. |

### Ejemplo completo de manejo de errores

```python
from identity_mx import generar_curp_rfc

datos_invalidos = {
    "nombre": "Juan123",      # ❌ Contiene números
    "primero": "Pérez",
    "segundo": "López",
    "genero": "Z",            # ❌ Género inválido
    "edo_nac": "XX",          # ❌ Estado inválido
    "dia_nac": "5",           # ❌ Solo 1 dígito (debe ser "05")
    "mes_nac": "13",          # ❌ Mes fuera de rango
    "anio_nac": "1850"        # ❌ Año antes de 1900
}

try:
    resultado = generar_curp_rfc(datos_invalidos)
except ValueError as e:
    print(f"Error de validación: {e}")
```

La librería validará los campos en orden y reportará el **primer error** encontrado.
