Metadata-Version: 2.4
Name: rut-validator
Version: 0.1.0
Summary: Chilean RUT validation library with Pydantic, Django, and SQLAlchemy support
License: MIT
License-File: LICENSE
Keywords: rut,chile,validation,pydantic,django,sqlalchemy,fastapi
Author: Eli-ezer Reuven Ramirez Ruiz
Author-email: ramirez.ruiz.eliezer.reuven@gmail.com
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: fastapi
Provides-Extra: pydantic
Requires-Dist: black ; extra == "dev"
Requires-Dist: click (>=8.0.0,<9.0.0)
Requires-Dist: django (>=3.2,<5.0)
Requires-Dist: fastapi (>=0.111.0,<1.0.0) ; extra == "fastapi"
Requires-Dist: flake8 ; extra == "dev"
Requires-Dist: isort ; extra == "dev"
Requires-Dist: mypy ; extra == "dev"
Requires-Dist: myst-parser ; extra == "docs"
Requires-Dist: pre-commit ; extra == "dev"
Requires-Dist: pydantic (>=2.12.5,<3.0.0) ; extra == "pydantic"
Requires-Dist: pytest (>=7.0.0) ; extra == "dev"
Requires-Dist: pytest-cov ; extra == "dev"
Requires-Dist: ruff ; extra == "dev"
Requires-Dist: sphinx ; extra == "docs"
Requires-Dist: sphinx-rtd-theme ; extra == "docs"
Requires-Dist: sqlalchemy (>=2.0.49,<3.0.0)
Project-URL: Changelog, https://github.com/yourusername/rut-validator/blob/main/CHANGELOG.md
Project-URL: Documentation, https://rut-validator.readthedocs.io/
Project-URL: Homepage, https://github.com/yourusername/rut-validator
Project-URL: Issues, https://github.com/yourusername/rut-validator/issues
Project-URL: Repository, https://github.com/yourusername/rut-validator
Description-Content-Type: text/markdown

# rut-validator

[![PyPI version](https://badge.fury.io/py/rut-validator.svg)](https://pypi.org/project/rut-validator/)
[![Python versions](https://img.shields.io/pypi/pyversions/rut-validator.svg)](https://pypi.org/project/rut-validator/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/yourusername/rut-validator/workflows/CI/badge.svg)](https://github.com/yourusername/rut-validator/actions)
[![codecov](https://codecov.io/gh/yourusername/rut-validator/branch/main/graph/badge.svg)](https://codecov.io/gh/yourusername/rut-validator)
[![Documentation Status](https://readthedocs.org/projects/rut-validator/badge/?version=latest)](https://rut-validator.readthedocs.io/en/latest/?badge=latest)

Librería para validar RUT chileno con enfoque Pydantic-first y soporte completo para frameworks web.

## ✨ Características

- ✅ **Validación pura de RUT chileno** usando algoritmo módulo 11
- ✅ **Detección automática de formato**: dotted (`12.345.678-9`), hyphenated (`12345678-9`), numeric (`123456789`)
- ✅ **Integración completa con Pydantic** (`RutStr`)
- ✅ **Campo Django** (`RUTField`) listo para usar
- ✅ **Tipo SQLAlchemy** (`RutSQLAlchemy`) para bases de datos
- ✅ **Compatible con FastAPI** y otros frameworks web
- ✅ **Type hints completos** para mejor desarrollo
- ✅ **Sin dependencias externas** para funcionalidad core
- ✅ **Tests exhaustivos** con alta cobertura

## 🚀 Instalación

```bash
pip install rut-validator

# Con soporte Pydantic
pip install rut-validator[pydantic]

# Con soporte FastAPI
pip install rut-validator[fastapi]

# Para desarrollo
pip install rut-validator[dev]
```

## 📖 Uso Básico

### Validación Simple

```python
from rut_validator import RutValidator

# Validar RUT con cualquier formato
rut = RutValidator.validate("20.884.437-7")
print(f"RUT válido: {rut.formatted}")  # "20.884.437-7"
print(f"Número: {rut.number}")          # 20884437
print(f"Dígito: {rut.digit}")          # "7"
print(f"Formato: {rut.format}")        # RutFormat.DOTTED
```

### Detección de Formato

```python
from rut_validator import RutValidator

# La librería detecta automáticamente el formato de entrada
formats = [
    "20.884.437-7",  # Formato dotted
    "20884437-7",    # Formato hyphenated
    "208844377",     # Formato numeric
]

for rut_str in formats:
    rut = RutValidator.validate(rut_str)
    print(f"'{rut_str}' -> Formato: {rut.format}, Es dotted: {rut.is_dotted}")
```

### Con Pydantic

```python
from pydantic import BaseModel
from rut_validator import RutStr

class User(BaseModel):
    name: str
    rut: RutStr  # Validación automática

# Uso
user = User(name="Juan Pérez", rut="12.345.678-5")
print(user.rut)  # "12.345.678-5"
```

### Con Django

```python
from django.db import models
from rut_validator.core.orm.django.schema import RUTField

class Person(models.Model):
    name = models.CharField(max_length=100)
    rut = RUTField(unique=True)  # Validación automática en DB
```

### Con SQLAlchemy

```python
from sqlalchemy import Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from rut_validator.core.orm.sqlalchemy.schema import RutSQLAlchemy

Base = declarative_base()

class Person(Base):
    __tablename__ = 'persons'

    id = Column(Integer, primary_key=True)
    name = Column(String)
    rut = Column(RutSQLAlchemy)  # Validación automática
```

## 📚 Guía Completa

Lee la documentación completa en [docs/GUIA_RUT_VALIDATOR.md](docs/GUIA_RUT_VALIDATOR.md)

## 🧪 Ejemplos

- [Validación pura](examples/01_pure_validation.py)
- [Uso con Pydantic](examples/02_pydantic_usage.py)
- [Uso con FastAPI](examples/03_fastapi_usage.py)

## 🔧 Desarrollo

### Configuración del entorno

```bash
# Clonar repositorio
git clone https://github.com/yourusername/rut-validator.git
cd rut-validator

# Instalar dependencias de desarrollo
poetry install --with dev

# Ejecutar tests
poetry run pytest

# Ejecutar linting
poetry run black src/ tests/
poetry run isort src/ tests/
poetry run flake8 src/ tests/
poetry run mypy src/rut_validator/
```

### Pre-commit hooks

```bash
poetry run pre-commit install
```

## 🤝 Contribuir

1. Fork el proyecto
2. Crea una rama para tu feature (`git checkout -b feature/AmazingFeature`)
3. Commit tus cambios (`git commit -m 'Add some AmazingFeature'`)
4. Push a la rama (`git push origin feature/AmazingFeature`)
5. Abre un Pull Request

## 📄 Licencia

Este proyecto está bajo la Licencia MIT - ver el archivo [LICENSE](LICENSE) para más detalles.

## 🙏 Agradecimientos

- Algoritmo de validación basado en el estándar chileno del Servicio de Impuestos Internos
- Inspirado en bibliotecas similares pero con enfoque moderno y tipado fuerte

## 📞 Soporte

- 🐛 [Reportar bugs](https://github.com/yourusername/rut-validator/issues)
- 💡 [Sugerir features](https://github.com/yourusername/rut-validator/issues)
- 📖 [Documentación](https://rut-validator.readthedocs.io/)

