![Estado](https://img.shields.io/badge/Estado-En%20desarrollo-blue)
# PyDNI

Es un módulo educativo de Python que permite validar DNIs y CIFs españoles de forma sencilla y rápida.  
Ideal para proyectos que necesiten comprobar la validez de identificadores fiscales o personales en España.


## Características

- Verificación de DNI (Documento Nacional de Identidad)
- Verificación de CIF (Código de Identificación Fiscal)
- Función unificada `verificar_identificador()` que detecta el tipo automáticamente
- Estructura modular, fácil de integrar en otros proyectos
- Código limpio y compatible con Python 3.10 o superior


## Instalación

```bash
pip install .
```

(Ejecuta este comando en la carpeta donde esté el `setup.py` del paquete.)

Si prefieres usarlo directamente sin instalarlo, puedes importarlo desde el directorio:

```python
from PyDNI import verificar_dni, verificar_cif, verificar_identificador
```


## Uso básico

```python
from PyDNI import verificar_dni, verificar_cif, verificar_identificador

# Verificar un DNI
print(verificar_dni("12345678Z"))   # True

# Verificar un CIF
print(verificar_cif("A58818501"))   # True

# Detección automática
print(verificar_identificador("12345678Z"))   # "DNI válido"
print(verificar_identificador("A58818501"))   # "CIF válido"
```

## Instalacion con pip desde PyPI
```bash
pip install PyDNI
```

https://pypi.org/project/PyDNI/

## Estructura del paquete

```
PyDNI/
├── .gitignore              # Archivos y carpetas que Git debe ignorar (ej. entornos, builds, cache)
├── CHANGELOG.md            # Registro de cambios por versión (historial de mejoras, fixes, nuevas features)
├── LICENSE                 # Licencia del proyecto (MIT)
├── README.md               # Documentación principal: descripción, instalación, uso y ejemplos
├── setup.py                # Script de configuración para instalar el paquete (PyPI)
├── test.py                 # Script rápido/manual para probar funciones básicas del paquete
│
├── PyDNI/                  # Carpeta principal del paquete (código fuente)
│   ├── __init__.py         # Inicializa el paquete y expone funciones principales
│   ├── dni.py              # Lógica de validación de DNI
│   ├── cif.py              # Lógica de validación de CIF
│   ├── nie.py              # Lógica de validación de NIE
│   ├── nif.py              # Lógica de validación de NIF
│   └── utils.py            # Funciones auxiliares
│
├── tests/                  # Carpeta con tests unitarios usando pytest
│   ├── test_dni.py         # Tests para verificar la función de DNI
│   ├── test_nie.py         # Tests para verificar la función de NIE
│   ├── test_cif.py         # Tests para verificar la función de CIF
│   ├── test_nif.py         # Tests para verificar la función de NIF genérico
│   └── test_utils.py       # Tests para verificar la función unificada de utils
│
└── tools/                  # Scripts auxiliares (ej. automatización, publicación, CI/CD, utilidades)

```


## Requisitos

- Python 3.10 o superior
- No requiere dependencias externas


## Test rápido

Ejecuta el archivo `test.py` incluido:

```bash
python test.py
```

Deberías ver algo como:

```
DNI 12345678Z: True
CIF A58818501: True
Auto (DNI): DNI válido
Auto (CIF): CIF válido
```
## Tests unitarios

Este proyecto incluye tests unitarios con pytest.  
Para ejecutarlos, asegúrate de tener instalado `pytest`:

```bash
pip install pytest
```
Luego, desde la raíz del proyecto:
```bash
 python -m pytest tests -v
 ```

Ejemplo de salida:
```bash
tests/test_cif.py::test_cif_valido_telefonica PASSED                                                             [  5%]
tests/test_cif.py::test_cif_valido_ayuntamiento_madrid PASSED                                                    [ 11%]
tests/test_cif.py::test_cif_invalido PASSED                                                                      [ 17%]
tests/test_dni.py::test_dni_valido PASSED                                                                        [ 23%]
tests/test_dni.py::test_dni_invalido_letra PASSED                                                                [ 29%]
tests/test_dni.py::test_dni_invalido_formato PASSED                                                              [ 35%]
tests/test_nie.py::test_nie_valido PASSED                                                                        [ 41%]
tests/test_nie.py::test_nie_invalido_letra_control PASSED                                                        [ 47%]
tests/test_nie.py::test_nie_invalido_formato PASSED                                                              [ 52%]
tests/test_nif.py::test_nif_dni_valido PASSED                                                                    [ 58%]
tests/test_nif.py::test_nif_nie_valido PASSED                                                                    [ 64%]
tests/test_nif.py::test_nif_cif_valido PASSED                                                                    [ 70%]
tests/test_nif.py::test_nif_invalido PASSED                                                                      [ 76%]
tests/test_utils.py::test_identificador_dni PASSED                                                               [ 82%]
tests/test_utils.py::test_identificador_nie PASSED                                                               [ 88%]
tests/test_utils.py::test_identificador_cif PASSED                                                               [ 94%]
tests/test_utils.py::test_identificador_formato_invalido PASSED                                                  [100%]

================================================= 17 passed in 0.05s ==================================================
```

## Autor

**Alberto Gonzalez**  
agonzalezla@protonmail.com  

## Licencia

Este proyecto se distribuye bajo la licencia MIT.  
Consulta el archivo `LICENSE`