pydantic-brasil 🇧🇷
Tipos de dados e validadores brasileiros modernos e de alta performance desenvolvidos nativamente para Pydantic v2 e FastAPI.
💡 Por que usar o pydantic-brasil?
- 🚀 Desenvolvido nativamente para Pydantic v2: Conectado diretamente ao núcleo
pydantic-corevia__get_pydantic_core_schema__, sem hacks ou regexes lentas de pré-validação. - 🛡️ Pronto para o CNPJ Alfanumérico 2026: Compatibilidade completa tanto com o CNPJ numérico tradicional quanto com o novo padrão alfanumérico regulamentado pela Receita Federal do Brasil.
- 🔒 Mascaramento em conformidade com a LGPD: Propriedade
.maskednativa em todos os documentos (123.***.***-00) para exibição em interfaces, logs seguros e telemetria. - 🗄️ Otimizado para Bancos de Dados:
model_dump()serializa documentos, telefones e CEPs diretamente em dígitos puros e desformatados ("12345678900"), permitindo indexação eficiente em PostgreSQL, MySQL, SQLite e MongoDB. - 📦 Sem Dependências Externas: Construído unicamente sobre
pydantic>=2.0.0etyping-extensions. Não traz pacotes pesados ou desatualizados. - 🎯 100% Tipado (PEP 561): Total compatibilidade com IDEs (VS Code, Cursor, PyCharm) e checadores estritos como
mypy --strictepyright. - 🧪 Geradores de Dados Válidos para Testes: Todos os documentos contam com
.generate()para acelerar a criação de fixtures e testes automatizados. - 🌐 Suporte OpenAPI / FastAPI: Documentação interativa Swagger UI (
/docs) e Redoc geradas automaticamente com exemplos e descrições ricas.
📦 Tipos Brasileiros Suportados (22 Tipos)
Documentos Pessoais, Fiscais e E-commerce
| Tipo | Alias | Propriedades Principais | Descrição |
|---|---|---|---|
CPF |
— | .fiscal_region, .formatted, .digits, .masked, .generate() |
Cadastro de Pessoas Físicas com Módulo 11 e região fiscal emissora. |
CNPJ |
— | .is_matriz, .is_filial, .branch_number, .formatted, .digits, .masked, .generate() |
Cadastro Nacional da Pessoa Jurídica (tradicional + alfanumérico 2026). |
CPFouCNPJ |
DocumentoBR |
.is_cpf, .is_cnpj, .as_cpf(), .as_cnpj() |
Documento fiscal polimórfico com auto-detecção entre CPF e CNPJ. |
InscricaoEstadual |
— | .state, .is_isento, .formatted, .digits, .masked |
Validação específica por UF (SP, RJ, MG, RS, PR, SC), produtor rural 'P' e ISENTO. |
ChaveDFe |
ChaveAcessoNFe, ChaveNFe |
.uf, .ano_mes, .cnpj_emitente, .modelo, .serie, .numero, .formatted, .generate() |
Chave oficial de 44 dígitos da SEFAZ para NF-e, NFC-e, CT-e e MDF-e com Módulo 11. |
GTIN |
EAN, EAN13 |
.is_brazilian, .gtin_type, .dv, .formatted, .masked, .generate() |
Código de Barras GS1 (GTIN-8, 12, 13 e 14) com detecção de produtos brasileiros (789/790). |
Endereço, Logística e Meios de Pagamento
| Tipo | Alias | Propriedades Principais | Descrição |
|---|---|---|---|
CEP |
— | .state, .formatted, .digits, .generate() |
Código de Endereçamento Postal com inferência automática de UF. |
RastreioCorreios |
CodigoRastreio |
.service_code, .serial_number, .origin_country, .is_national, .tracking_url, .generate() |
Rastreamento de encomendas dos Correios no padrão internacional S10 da UPU (13 caracteres). |
TelefoneBR |
— | .ddd, .e164, .whatsapp_link, .is_mobile, .is_landline, .generate() |
Celular (9 dígitos) e fixo (8 dígitos) com validação de DDDs da ANATEL e link WhatsApp. |
ChavePIX |
PixKey |
.key_type, .normalized, .formatted, .masked, .generate_evp() |
Validação e tipagem oficial Bacen (CPF, CNPJ, E-mail, Telefone, Chave Aleatória/EVP). |
BoletoBancario |
LinhaDigitavel, CodigoBarrasBoleto |
.codigo_barras, .linha_digitavel, .banco, .data_vencimento, .valor, .is_arrecadacao, .generate() |
Boletos de cobrança (47 dígitos) e arrecadação/concessionárias (48 dígitos) FEBRABAN. |
IBANBrasil |
IBAN |
.country_code, .check_digits, .ispb, .banco, .agencia, .conta, .tipo_conta, .generate() |
Conta Internacional Brasileira regulamentada pelo Bacen (29 caracteres) com Módulo 97. |
DinheiroBRL |
BRL |
.centavos, .formatted, from_centavos(), operações matemáticas |
Precisão monetária financeira via Decimal (evita bugs de arredondamento de float). |
BancoBR |
CodigoBanco |
.code, .name, .short_name, .ispb, .formatted, search() |
Catálogo oficial de bancos e instituições de pagamento homologadas no Bacen. |
Cidadania, Trabalho e Saúde
| Tipo | Alias | Propriedades Principais | Descrição |
|---|---|---|---|
PIS |
PASEP, NIS, NIT |
.formatted, .digits, .masked, .generate() |
Identificação do trabalhador CLT / servidor com verificação Módulo 11. |
TituloEleitor |
TituloEleitoral |
.state, .uf_code, .formatted, .digits, .masked, .generate() |
Título eleitoral com validação de UF e dois dígitos verificadores (TSE). |
CNS |
CartaoSUS |
.is_definitivo, .is_provisorio, .formatted, .digits, .masked, .generate() |
Cartão Nacional de Saúde (SUS) definitivo (1, 2) e provisório (7, 8, 9). |
CertidaoCivil |
Certidao |
.year, .type_code, .type_name, .cartorio_cns, .formatted, .generate() |
Padrão unificado do CNJ (32 dígitos) para Nascimento, Casamento e Óbito. |
ProcessoCNJ |
ProcessoJudicial |
.year, .segment_id, .segment_name, .tribunal, .formatted, .generate() |
Numeração Única de Processos Judiciais (20 dígitos) com Módulo 97 (ISO 7064). |
Trânsito e Veículos
| Tipo | Alias | Propriedades Principais | Descrição |
|---|---|---|---|
PlacaVeiculo |
— | .is_mercosul, .is_antiga, .to_mercosul(), .to_antiga() |
Placas padrão Mercosul (ABC1D23) e padrão antigo cinza (ABC-1234) com conversão. |
RENAVAM |
— | .formatted, .digits, .masked, .generate() |
Registro Nacional de Veículos Automotores (11 dígitos) com Módulo 11. |
CNH |
— | .formatted, .digits, .masked, .generate() |
Carteira Nacional de Habilitação (11 dígitos) com verificação dupla de DV. |
🚀 Instalação
pip install pydantic-brasil
Ou com Poetry:
poetry add pydantic-brasil
Ou com uv:
uv add pydantic-brasil
🛠️ Exemplos de Uso
1. Modelo de Cadastro Completo
from pydantic import BaseModel
from pydantic_brasil import (
CPF,
CNPJ,
CEP,
TelefoneBR,
ChavePIX,
DinheiroBRL,
PIS,
CNS,
BancoBR,
)
class Cliente(BaseModel):
nome: str
cpf: CPF
cnpj_empresa: CNPJ
cep: CEP
telefone: TelefoneBR
chave_pix: ChavePIX
limite_credito: DinheiroBRL
pis: PIS
cns: CNS
banco: BancoBR
# Aceita pontuado, dígitos puros, inteiros, etc.
cliente = Cliente(
nome="Ana Souza",
cpf="123.456.789-09",
cnpj_empresa="12.ABC.345/0001-67", # Suporta CNPJ alfanumérico 2026!
cep="01310-100",
telefone="(11) 98765-4321",
chave_pix="ana.souza@email.com",
limite_credito="R$ 15.000,50",
pis="120.41440.45-9",
cns="123 4567 8901 0002",
banco="Nubank", # Busca automática por nome comercial ou código COMPE ("260")
)
# Acesso a propriedades ricas
print(cliente.cpf.formatted) # "123.456.789-09"
print(cliente.cpf.masked) # "123.***.***-09" (Seguro para LGPD)
print(cliente.cpf.fiscal_region) # ["SP"]
print(cliente.telefone.e164) # "+5511987654321"
print(cliente.telefone.whatsapp_link) # "https://wa.me/5511987654321"
print(cliente.chave_pix.key_type) # PixKeyType.EMAIL
print(cliente.limite_credito.centavos)# 1500050 (int puro, ideal para gateways como Asaas/Pagar.me)
print(cliente.banco.code) # "260"
print(cliente.banco.name) # "Nu Pagamentos S.A. - Instituição de Pagamento"
print(cliente.banco.ispb) # "18236120"
# Serialização limpa para salvar no banco de dados:
print(cliente.model_dump())
# {
# "nome": "Ana Souza",
# "cpf": "12345678909",
# "cnpj_empresa": "12ABC345000167",
# "cep": "01310100",
# "telefone": "11987654321",
# "chave_pix": "ana.souza@email.com",
# "limite_credito": 15000.5,
# "pis": "12041440459",
# "cns": "123456789010002",
# "banco": "260"
# }
2. Integração com FastAPI
Os tipos do pydantic-brasil geram metadados OpenAPI automaticamente:
from fastapi import FastAPI
from pydantic import BaseModel
from pydantic_brasil import CPF, ChavePIX, DinheiroBRL
app = FastAPI(title="API de Pagamentos PIX")
class SolicitacaoTransferencia(BaseModel):
cpf_origem: CPF
chave_pix_destino: ChavePIX
valor: DinheiroBRL
@app.post("/transferir")
def transferir(dados: SolicitacaoTransferencia):
return {
"status": "sucesso",
"tipo_chave": dados.chave_pix_destino.key_type,
"chave_destino": dados.chave_pix_destino.normalized,
"valor_em_centavos": dados.valor.centavos,
"pagador": dados.cpf_origem.masked,
}
🔍 Exemplos Práticos por Domínio
CNPJ Alfanumérico 2026
A partir de 2026, a Receita Federal do Brasil passa a emitir CNPJs com caracteres alfanuméricos na base (12.ABC.345/0001-67). O pydantic-brasil suporta ambas as especificações:
from pydantic_brasil import CNPJ
# CNPJ tradicional
cnpj_antigo = CNPJ("12.345.678/0001-95")
# CNPJ alfanumérico 2026
cnpj_novo = CNPJ("12.ABC.345/0001-67")
print(cnpj_novo.is_matriz) # True
print(cnpj_novo.branch_number) # "0001"
print(cnpj_novo.masked) # "12.***.***/0001-67"
Processo Judicial CNJ (Numeração Única)
Validação matemática estrita de processos judiciais utilizando Módulo 97 (ISO 7064):
from pydantic_brasil import ProcessoCNJ
proc = ProcessoCNJ("0001234-71.2024.8.26.0100")
print(proc.year) # 2024
print(proc.segment_name) # "Justiça dos Estados e do Distrito Federal"
print(proc.tribunal) # "26" (TJSP)
print(proc.origin) # "0100" (Comarca da Capital)
Título de Eleitor e Identificação de UF
from pydantic_brasil import TituloEleitor
titulo = TituloEleitor.generate(state="MG")
print(titulo.state) # "MG"
print(titulo.uf_code) # "02"
print(titulo.formatted) # "1234 5678 02 14"
Conversão de Placas de Veículos (Mercosul ↔ Antiga)
from pydantic_brasil import PlacaVeiculo
placa = PlacaVeiculo("ABC-1234")
print(placa.is_antiga) # True
print(placa.to_mercosul()) # "ABC1C34"
mercosul = PlacaVeiculo("ABC1C34")
print(mercosul.is_mercosul) # True
print(mercosul.to_antiga()) # "ABC-1234"
Dinheiro BRL e Precisão Financeira
from pydantic_brasil import DinheiroBRL
preco = DinheiroBRL("R$ 1.250,50")
print(preco.centavos) # 125050 (int)
print(preco.formatted) # "R$ 1.250,50"
# Criar a partir de centavos recebidos de gateway
tarifa = DinheiroBRL.from_centavos(490) # R$ 4,90
total = preco + tarifa
print(total.formatted) # "R$ 1.255,40"
Catálogo de Bancos Brasileiros (COMPE / ISPB)
from pydantic_brasil import BancoBR
# Por código numérico (ex: 1 é normalizado para "001")
banco1 = BancoBR(1) # Banco do Brasil ("001")
banco2 = BancoBR("260") # Nubank
banco3 = BancoBR("Inter") # Busca por nome -> "077"
# Busca rápida de bancos no catálogo Bacen
bancos_cooperativos = BancoBR.search("cooperativo")
Chave de Acesso DF-e (NF-e, NFC-e, CT-e, MDF-e)
Validação matemática de 44 dígitos no Módulo 11 da SEFAZ com extração completa de metadados:
from pydantic_brasil import ChaveDFe
chave = ChaveDFe("352410000000000000550010000123451123456781")
print(chave.uf) # "SP"
print(chave.uf_code) # 35
print(chave.year) # 2024
print(chave.month) # 10
print(chave.modelo_nome) # "NF-e (Nota Fiscal Eletrônica)"
print(chave.serie) # "001"
print(chave.numero) # "000012345"
print(chave.cnpj_emitente) # CNPJ("00000000000000")
print(chave.formatted) # "3524 1000 0000 0000 0055 0010 0001 2345 1123 4567 81"
Boletos Bancários e Linha Digitável (FEBRABAN)
Conversão automática bidirecional entre linha digitável e código de barras, com extração de vencimento e valor:
from pydantic_brasil import BoletoBancario
# Aceita tanto a linha digitável (47 dígitos) quanto o código de barras (44 dígitos)
boleto = BoletoBancario("00190.00009 01234.567802 00000.000001 5 100000000000")
print(boleto.banco.name) # "Banco do Brasil S.A."
print(boleto.valor.formatted) # "R$ 100,00"
print(boleto.data_vencimento) # 2025-02-22 (calculado via fator FEBRABAN)
print(boleto.codigo_barras) # "00195100000000000000000012345678000000000001"
print(boleto.is_arrecadacao) # False (ou True se for água/luz/tributo com 48 dígitos)
Rastreamento de Encomendas dos Correios (Padrão S10)
from pydantic_brasil import RastreioCorreios
encomenda = RastreioCorreios("QC123456785BR")
print(encomenda.service_code) # "QC"
print(encomenda.is_national) # True
print(encomenda.tracking_url) # "https://rastreamento.correios.com.br/app/index.php?codigo=QC123456785BR"
print(encomenda.formatted) # "QC 12345678 5 BR"
IBAN Brasileiro (Conta Internacional Bacen)
from pydantic_brasil import IBANBrasil
iban = IBANBrasil("BR1200000000000010000123456C1")
print(iban.country_code) # "BR"
print(iban.agencia) # "00001"
print(iban.conta) # "0000123456"
print(iban.tipo_conta) # "C" (Conta Corrente)
print(iban.banco.name) # "Banco do Brasil S.A."
Código de Barras GTIN / EAN (GS1 Brasil)
from pydantic_brasil import GTIN
produto = GTIN("7891000315507")
print(produto.is_brazilian) # True (prefixo 789/790 atribuído à GS1 Brasil)
print(produto.gtin_type) # "GTIN-13" (EAN-13)
🧪 Qualidade, Testes e Tipagem
# Executar suíte de testes com cobertura de código
pytest --cov=pydantic_brasil --cov-report=term-missing
# Verificação estrita de tipos
mypy pydantic_brasil tests
# Linting e estilo
flake8
black --check .
🤝 Contribuições
Contribuições, correções de bugs e sugestões de novos documentos brasileiros são extremamente bem-vindas!
- Faça um Fork do projeto
- Crie uma branch de funcionalidade (
git checkout -b feature/MeuDocumento) - Adicione testes unitários e verifique com
pytestemypy - Envie o commit (
git commit -m 'feat: Adiciona validador para Documento') - Abra um Pull Request
📄 Licença
Distribuído sob a Licença MIT. Consulte o arquivo LICENSE para mais detalhes.
Metadata
Release files for pydantic-brasil 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pydantic_brasil-0.3.0.tar.gz | 56.9 kB | Without provenance | Details for pydantic_brasil-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pydantic_brasil-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for pydantic_brasil-0.3.0-py3-none-any.whl |
Total release size: 111.4 kB
Release files / pydantic_brasil-0.3.0.tar.gz
| Download URL | pydantic_brasil-0.3.0.tar.gz |
|---|---|
| Size | 56.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
533afceb9a5bd9624f0c71ffc804eba707bf5334099b8ab685286e5bbd3b594d
|
|
BLAKE2b-256 checksum How to use checksums |
a9ca44d6f282be48ef60b5c01a4a9bbaeca16541a591c7360c2ba66bf4ec6e54
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Release files / pydantic_brasil-0.3.0-py3-none-any.whl
| Download URL | pydantic_brasil-0.3.0-py3-none-any.whl |
|---|---|
| Size | 54.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
41dccab8e437afadc8deffa6c4f88e642f0ec2b9a41fbeceb9dfdc4bcf131a55
|
|
BLAKE2b-256 checksum How to use checksums |
12a53502ab3a4cf0a00bef420a2d605ce58dfca4c1d9e0388dc75a8c5d0c930c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Security for pydantic-brasil 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.