doclatam 1.0.1
A robust library for validating and formatting Latin American documents
License: MIT
Requires Python: >=3.7
Keywords: validation, latam, cpf, cnpj, rut, cuit, curp, rfc, documents, latin-america

# DocLatam

**A solução definitiva para validação de documentos na América Latina.**

Desenvolvida pela **Sanches Tech**, a DocLatam oferece validação robusta, geração de dados e integração nativa com frameworks modernos para **11 países latino-americanos**.

[![PyPI version](https://img.shields.io/pypi/v/doclatam.svg)](https://pypi.org/project/doclatam/)
[![Tests](https://img.shields.io/badge/tests-57%20passed-success)](https://github.com/sanchestech/doclatam)
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/sanchestech/doclatam)
[![Python](https://img.shields.io/badge/python-3.7%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

## 🌎 Cobertura Continental

| Região | Países | Documentos |
|--------|--------|------------|
| **América do Sul** | 🇧🇷 🇦🇷 🇨🇱 🇺🇾 🇵🇾 🇧🇴 🇵🇪 🇪🇨 🇨🇴 🇻🇪 | 40+ validadores |
| **América do Norte** | 🇲🇽 | CURP, RFC, Placas |

## 🚀 Instalação

```bash
pip install doclatam
```

## 💻 Uso Rápido

### Validação Simples
```python
from doclatam.br import CPF
from doclatam.mx import CURP

# Aceita entrada "suja"
CPF.validate("123.456.789-09")  # True/False
CURP.validate("ABCD 901231 HDFXYZ 0")  # True/False
```

### Formatação
```python
from doclatam.cl import RUT

RUT.format("12345678k")  # "12.345.678-K"
```

### Geração de Dados (Testing)
```python
from doclatam.br import CPF
from doclatam.ar import CUIT

fake_cpf = CPF.generate()    # "123.456.789-09"
fake_cuit = CUIT.generate()  # "20-12345678-6"
```

### Integração FastAPI (Pydantic)
```python
from pydantic import BaseModel
from doclatam.integrations.pydantic import CPF, CURP

class Usuario(BaseModel):
    cpf: CPF    # Valida automaticamente
    curp: CURP  # Rejeita se inválido

# Uso
user = Usuario(cpf="123.456.789-09", curp="ABCD901231HDFXYZ0")
```

### Identificador de Placas
```python
from doclatam.utils import identify_plate

identify_plate("ABC1D23")   # ['Brasil']
identify_plate("AA123BB")   # ['Argentina']
identify_plate("ABCD123")   # ['Paraguai']
```

## 📋 Documentos Suportados

<details>
<summary><b>🇧🇷 Brasil</b></summary>

- CPF (Cadastro de Pessoas Físicas)
- CNPJ (Cadastro Nacional da Pessoa Jurídica)
- PIS/PASEP
- CNH (Carteira Nacional de Habilitação)
- Título de Eleitor
- Renavam
- Placa Mercosul (com conversão)
- Passaporte
</details>

<details>
<summary><b>🇦🇷 Argentina</b></summary>

- DNI (Documento Nacional de Identidad)
- CUIT/CUIL
- Placa Mercosul
- Passaporte
</details>

<details>
<summary><b>🇲🇽 México</b></summary>

- CURP (Clave Única de Registro de Población)
- RFC (Registro Federal de Contribuyentes)
- Placa
</details>

<details>
<summary><b>Outros Países</b></summary>

**Chile:** RUT, Placa, Passaporte  
**Uruguai:** CI, Placa Mercosul, Passaporte  
**Paraguai:** RUC, CIC, Placa Mercosul, Passaporte  
**Bolívia:** CI, Placa, Passaporte  
**Peru:** DNI, RUC, Placa, Passaporte  
**Equador:** CI, RUC, Placa, Passaporte  
**Colômbia:** NIT, Placa, Passaporte  
**Venezuela:** RIF, CI, Placa, Passaporte  
</details>

## 🛡️ Qualidade Garantida

- ✅ **57 testes** (unitários, integração, property-based)
- ✅ **100% de cobertura** nos validadores principais
- ✅ **Property-based testing** com Hypothesis
- ✅ **Zero dependências** pesadas
- ✅ **Type hints** completos

## 🎯 Diferenciais

| Funcionalidade | DocLatam | Outras Libs |
|----------------|----------|-------------|
| Países | **11** | 1-3 |
| Geração de Dados | ✅ | ❌ |
| Pydantic | ✅ | ❌ |
| Plate Identifier | ✅ | ❌ |
| Hypothesis Tests | ✅ | ❌ |

## 📖 Documentação

Visite [docs.sanchestech.com/doclatam](https://docs.sanchestech.com/doclatam) para:
- Guias de uso por país
- Referência completa da API
- Exemplos de integração
- Casos de uso reais

## 🤝 Contribuindo

Contribuições são bem-vindas! Veja [CONTRIBUTING.md](CONTRIBUTING.md).

## 📄 Licença

MIT License - © 2025 Sanches Tech

---

<div align="center">
    <p><strong>Desenvolvido com excelência por Sanches Tech</strong></p>
    <p>A melhor biblioteca de validação de documentos da América Latina.</p>
</div>