br-kit 0.1.0

Zero-dependency Brazilian document utils — CPF, CNPJ (alphanumeric-ready), CEP, phone, currency, dates. Mirrored TypeScript + Python APIs.

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 (TS camelCase ↔ Py snake_case), com comportamento travado por uma suíte de vetores de conformidade compartilhada.

Instalação

pip install br-kit

Uso

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.

✅ 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