Metadata-Version: 2.4
Name: br-kit
Version: 0.1.0
Summary: Zero-dependency Brazilian document utils — CPF, CNPJ (alphanumeric-ready), CEP, phone, currency, dates. Mirrored TypeScript + Python APIs.
Project-URL: Homepage, https://github.com/victorhurchella/br-kit
Project-URL: Source, https://github.com/victorhurchella/br-kit
Project-URL: Bug Tracker, https://github.com/victorhurchella/br-kit/issues
Project-URL: Changelog, https://github.com/victorhurchella/br-kit/blob/main/CHANGELOG.md
Author: Victor Hugo
License: MIT
License-File: LICENSE
Keywords: brasil,brazil,cep,cnpj,cpf,validation,validator,zero-dependency
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Portuguese (Brazilian)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
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
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# br-kit (Python)

> Validação, formatação, parsing e geração de documentos brasileiros — **zero
> dependências**, pronto para o **CNPJ alfanumérico** (julho/2026).
>
> Validation, formatting, parsing and generation of Brazilian documents — **zero
> dependencies**, ready for the **alphanumeric CNPJ** (July 2026).

API espelhada com o pacote npm [`br-kit`](https://www.npmjs.com/package/br-kit)
(TS `camelCase` ↔ Py `snake_case`), com comportamento travado por uma suíte de
vetores de conformidade compartilhada.

## Instalação

```bash
pip install br-kit
```

## Uso

```python
from br_kit import cpf, cnpj, currency

cpf.is_valid("390.533.447-05")            # True
cpf.format("39053344705")                 # "390.533.447-05"
cpf.validate_detailed("111.111.111-11")   # ValidationResult(valid=False, reason="repeated-digits")

cnpj.is_valid("12.ABC.345/01DE-35")       # True  ← alfanumérico
cnpj.is_alphanumeric("12ABC34501DE35")    # True

currency.format_brl(1234.56)              # "R$ 1.234,56"
currency.parse_brl("R$ 1.234,56")         # 1234.56
```

Import granular: `from br_kit.cpf import is_valid`.

## API (v0.1)

| Módulo | Funções |
|---|---|
| `cpf` | `is_valid` · `validate_detailed` · `format` · `strip` · `generate` |
| `cnpj` | `is_valid` · `is_alphanumeric` · `validate_detailed` · `format` · `strip` · `generate` |
| `cep` | `is_valid` · `format` · `strip` |
| `phone` | `is_valid` · `parse` · `format` · `strip` |
| `currency` | `format_brl` · `parse_brl` |
| `dates` | `parse_pt_br` · `format_pt_br` |

**Contrato (idêntico ao pacote npm, em `snake_case`):**

- `is_valid(value)` → `bool`, **nunca levanta exceção**.
- `validate_detailed(value)` → `ValidationResult(valid, reason)`. `reason` é estável:
  `invalid-characters` · `invalid-length` · `repeated-digits` · `invalid-check-digit`.
- `format(value)` / `parse(value)` **levantam `ValueError`** em input inválido
  (em TypeScript: `RangeError`).
- `strip(value)` remove a máscara; `generate()` é **só para testes/fixtures** —
  nunca trate o resultado como documento real.

Totalmente tipado (`py.typed` incluído). Documentação do algoritmo do CNPJ
alfanumérico: [docs/cnpj-alphanumeric.md](https://github.com/victorhurchella/br-kit/blob/main/docs/cnpj-alphanumeric.md).

## ✅ Pronto para o CNPJ alfanumérico (julho/2026)

A partir de julho de 2026 a Receita Federal emite CNPJs com letras (A–Z) nos 12
primeiros caracteres (IN RFB 2.229/2024). `br-kit.cnpj` valida ambos os formatos
de forma transparente — `\d{14}` quebra, `br-kit` não.

Licença MIT. Documentação completa e suíte de conformidade:
<https://github.com/victorhurchella/br-kit>
