Primeiros passos

🚀 Suporte total ao novo formato alfanumérico de CNPJ.

Kit de utilitários em Python para as principais operações com dados brasileiros: CPF (Cadastro de Pessoa Física) e CNPJ (Cadastro Nacional da Pessoa Jurídica). Oferece um wrapper de alto nível BrUtils em torno de cpf-utils e cnpj-utils, expondo todos os recursos empacotados em um caminho de importação unificado.

Recursos

• ✅ API unificada de alto nível: Uma instância BrUtils com acessores de domínio cpf e cnpj
• ✅ Domínios empacotados: cpf-utils e cnpj-utils instalados juntos
• ✅ CNPJ alfanumérico: Suporte completo ao novo formato alfanumérico de CNPJ (a partir de 2026)
• ✅ Padrões configuráveis: Defina opções de formatador, gerador e (para CNPJ) validador em cada instância de domínio
• ✅ Sobrescrita por chamada: Sobrescreva qualquer opção de componente em uma única chamada de método
• ✅ Duas formas de uso: Fachada de alto nível (BrUtils), agregadores de domínio (CpfUtils, CnpjUtils), componentes isolados e helpers funcionais
• ✅ Submódulos compartilhados: Símbolos de CPF em br_utils.cpf; símbolos de CNPJ em br_utils.cnpj
• ✅ Tratamento de erros tipado: Hierarquias dedicadas de exceções dos pacotes empacotados (modelo TypeError / Exception da v2 de cpf-utils e cnpj-utils)

Instalação

$ pip install br-utilities

Isso instala br-utilities junto com cpf-utils e cnpj-utils (que por sua vez trazem os pacotes componentes de CPF e CNPJ). Você não precisa de chamadas pip install separadas para os pacotes de domínio ao usar br-utilities.

Importação

Escolha a API que melhor se adapta ao seu caso.

Fachada de alto nível e singletons de domínio:

from br_utils import BrUtils, br_utils, CpfUtils, CnpjUtils, cpf_utils, cnpj_utils

Componentes e helpers de CPF (br_utils.cpf):

from br_utils.cpf import (
    CpfFormatter,
    CpfFormatterOptions,
    CpfGenerator,
    CpfGeneratorOptions,
    CpfValidator,
    cpf_fmt,
    cpf_gen,
    cpf_val,
)

Componentes e helpers de CNPJ (br_utils.cnpj):

from br_utils.cnpj import (
    CnpjFormatter,
    CnpjFormatterOptions,
    CnpjGenerator,
    CnpjGeneratorOptions,
    CnpjValidator,
    CnpjValidatorOptions,
    cnpj_fmt,
    cnpj_gen,
    cnpj_val,
)

Os helpers funcionais (cpf_fmt, cnpj_fmt e símbolos relacionados) não são reexportados na raiz do pacote — importe-os de br_utils.cpf ou br_utils.cnpj.

Início rápido

Com br_utils (singleton padrão):

from br_utils import br_utils

cpf = '11144477735'
cnpj = '03603568000195'

br_utils.cpf.format(cpf)      # '111.444.777-35'
br_utils.cpf.is_valid(cpf)    # True
br_utils.cpf.generate()       # ex.: '11508890048'

br_utils.cnpj.format(cnpj)    # '03.603.568/0001-95'
br_utils.cnpj.is_valid(cnpj)  # True
br_utils.cnpj.generate()      # ex.: '1GJTR3J3XSSA96'

Com agregadores de domínio:

from br_utils import CpfUtils, CnpjUtils

cpf = '11144477735'
cnpj = '03603568000195'

CpfUtils().format(cpf)      # '111.444.777-35'
CnpjUtils().format(cnpj)    # '03.603.568/0001-95'
CpfUtils().is_valid(cpf)    # True
CnpjUtils().is_valid(cnpj)  # True

Com helpers funcionais:

from br_utils.cpf import cpf_fmt, cpf_val
from br_utils.cnpj import cnpj_fmt, cnpj_val

cpf = '11144477735'
cnpj = '03603568000195'

cpf_fmt(cpf)     # '111.444.777-35'
cpf_val(cpf)     # True
cnpj_fmt(cnpj)   # '03.603.568/0001-95'
cnpj_val(cnpj)   # True

Utilização

Você pode trabalhar de quatro formas equivalentes:

1. br_utils — singleton pré-construído de BrUtils com padrões compartilhados entre os domínios CPF e CNPJ.
2. BrUtils — crie sua própria instância com configurações padrão customizadas de CPF e CNPJ.
3. Agregadores de domínio — CpfUtils e CnpjUtils diretamente (as mesmas classes usadas internamente por BrUtils).
4. Classes componentes e helpers funcionais — CpfFormatter, CnpjGenerator, cpf_fmt(), cnpj_gen() e símbolos relacionados.

Todas as abordagens expõem as mesmas opções e comportamento dentro de cada domínio. Para tabelas de opções completas e detalhes específicos de cada componente, consulte o README de cada pacote incluído.

br_utils (instância padrão)

O br_utils em nível de módulo é uma instância pré-construída de BrUtils. Use para chamadas rápidas:

• cpf: Acesso aos utils de CPF (CpfUtils). Use br_utils.cpf.format(), br_utils.cpf.generate(), br_utils.cpf.is_valid() com as mesmas opções do cpf-utils.
• cnpj: Acesso aos utils de CNPJ (CnpjUtils). Use br_utils.cnpj.format(), br_utils.cnpj.generate(), br_utils.cnpj.is_valid() com as mesmas opções do cnpj-utils.

BrUtils (classe)

Para utils de CPF ou CNPJ padrão customizados, crie sua própria instância:

from br_utils import BrUtils

utils = BrUtils(
    cpf={
        'formatter': {'hidden': True, 'hidden_key': '#'},
        'generator': {'format': True},
    },
    cnpj={
        'formatter': {'hidden': True},
        'generator': {'type': 'numeric', 'format': True},
        'validator': {'type': 'numeric'},
    },
)

utils.cpf.format('11144477735')        # '111.###.###-##'
utils.cpf.generate()                   # ex.: '005.265.352-88'
utils.cnpj.format('03603568000195')    # '03.603.***/****-**'
utils.cnpj.generate()                  # ex.: '73.008.535/0005-06'

# Acessar instâncias internas de domínio
utils.cpf    # CpfUtils
utils.cnpj   # CnpjUtils

• __init__(…): Todos os argumentos são somente por palavra-chave e opcionais.
  • cpf / cnpj: Uma instância pronta de CpfUtils / CnpjUtils ou um mapeamento de configuração repassado ao construtor do utils correspondente. Dentro desse mapeamento, cada chave de recurso (formatter, generator e validator para CNPJ) aceita um objeto de opções ou um mapeamento de valores de opção.
  • cpf_formatter, cpf_generator, cnpj_formatter, cnpj_generator, cnpj_validator: Argumentos planos de conveniência quando apenas componentes individuais precisam de customização. São ignorados quando o argumento cpf ou cnpj correspondente é fornecido.
• cpf, cnpj: Propriedades com getters e setters das instâncias de utils de domínio. Os setters aceitam uma instância de utils, um mapeamento de configuração ou None para voltar aos padrões (substitui a instância inteira; não faz merge).

Opções planas no construtor (alternativa aos mapeamentos aninhados cpf / cnpj):

from br_utils import BrUtils
from br_utils.cpf import CpfFormatterOptions, CpfGeneratorOptions
from br_utils.cnpj import CnpjFormatterOptions, CnpjGeneratorOptions, CnpjValidatorOptions

utils = BrUtils(
    cpf_formatter=CpfFormatterOptions(hidden=True, hidden_key='#'),
    cpf_generator=CpfGeneratorOptions(format=True),
    cnpj_formatter=CnpjFormatterOptions(hidden=True, hidden_key='#'),
    cnpj_generator=CnpjGeneratorOptions(format=True, type='numeric'),
    cnpj_validator=CnpjValidatorOptions(type='numeric'),
)

Padrões da instância e sobrescritas por chamada

from br_utils import BrUtils

utils = BrUtils(
    cpf={
        'formatter': {'hidden': True, 'hidden_key': '#'},
        'generator': {'format': True},
    },
    cnpj={
        'formatter': {'hidden': True, 'hidden_key': '#'},
        'generator': {'format': True},
        'validator': {'type': 'numeric'},
    },
)

cpf = '11144477735'
cnpj = '03603568000195'

utils.cpf.format(cpf)                  # '111.###.###-##'
utils.cpf.format(cpf, hidden=False)    # '111.444.777-35'
utils.cpf.generate(format=False)       # ex.: '58450042259'

utils.cnpj.format(cnpj)                  # '03.603.###/####-##'
utils.cnpj.format(cnpj, hidden=False)    # '03.603.568/0001-95'
utils.cnpj.is_valid('1QB5UKALPYFP59')    # False
utils.cnpj.is_valid(                     # True
    '1QB5UKALPYFP59',
    type='alphanumeric',
)

Passar uma instância de CnpjFormatterOptions, CnpjGeneratorOptions ou CnpjValidatorOptions ao construtor de BrUtils armazena esse objeto por referência — mutá-lo depois afeta chamadas subsequentes sem sobrescrita por chamada.

Operações de CPF

Os métodos de CPF são acessados via utils.cpf, CpfUtils ou os helpers cpf_*() de br_utils.cpf. O CPF usa a API v2 de cpf-utils: entrada str ou sequência em format() / is_valid(), sobrescritas por mapeamento ou palavra-chave por chamada e exceções estruturadas.

Formatação (format / cpf_fmt)

Opção	Tipo	Padrão	Descrição
hidden	bool	False	Quando True, mascara dígitos em hidden_start–hidden_end com hidden_key
hidden_key	str	'*'	Caractere(s) usados para substituir dígitos mascarados
hidden_start	int	3	Índice inicial (0–10, inclusivo) do intervalo a ocultar
hidden_end	int	10	Índice final (0–10, inclusivo) do intervalo a ocultar
dot_key	str	'.'	Delimitador de ponto (ex.: em 123.456.789)
dash_key	str	'-'	Delimitador de traço (ex.: antes dos dígitos verificadores …-09)
escape	bool	False	Quando True, escapa caracteres especiais HTML no resultado
encode	bool	False	Quando True, codifica o resultado para URL (similar ao encodeURIComponent do JavaScript)
on_fail	Callable	retorna ''	Callback quando o comprimento sanitizado ≠ 11; o valor de retorno é usado como resultado

O on_fail padrão retorna uma string vazia. Comprimento inválido não lança exceção em format().

from br_utils import br_utils
from br_utils.cpf import cpf_fmt

cpf = '11144477735'

br_utils.cpf.format(cpf)                                        # '111.444.777-35'
br_utils.cpf.format(cpf, hidden=True, hidden_key='#')           # '111.###.###-##'
br_utils.cpf.format(cpf, dot_key='', dash_key='_')              # '111444777_35'

cpf_fmt(cpf, hidden=True)                                       # '111.***.***-**'

Geração (generate / cpf_gen)

Opção	Tipo	Padrão	Descrição
format	bool	False	Quando True, retorna o CPF gerado no formato padrão (000.000.000-00)
prefix	str	''	String parcial inicial (0–9 dígitos). Não dígitos são removidos; caracteres faltantes são gerados e os dígitos verificadores calculados. Prefixos com mais de 9 dígitos são truncados silenciosamente.

Regras de prefixo: a base (primeiros 9 dígitos) não pode ser toda zeros; 9 dígitos repetidos (ex.: 999999999) não são permitidos.

from br_utils import br_utils
from br_utils.cpf import cpf_gen

br_utils.cpf.generate()                      # ex.: '11508890048'
br_utils.cpf.generate(format=True)             # ex.: '661.134.831-00'
br_utils.cpf.generate(prefix='123456789')    # '12345678909'
cpf_gen(prefix='123456789', format=True)     # '123.456.789-09'

Validação (is_valid / cpf_val)

Aceita CPF formatado ou não (ou sequência de strings). Retorna True ou False sem lançar exceção para CPF inválido. Não há opções de validador.

from br_utils import br_utils
from br_utils.cpf import cpf_val

br_utils.cpf.is_valid('11144477735')      # True
br_utils.cpf.is_valid('111.444.777-35')   # True
br_utils.cpf.is_valid('11144477736')      # False
cpf_val('11144477735')                    # True

Operações de CNPJ

Os métodos de CNPJ são acessados via utils.cnpj, CnpjUtils ou os helpers cnpj_*() de br_utils.cnpj. O CNPJ usa a API v2 de cnpj-utils.

Formatação (format / cnpj_fmt)

Opção	Tipo	Padrão	Descrição
hidden	bool	False	Quando True, mascara caracteres em hidden_start–hidden_end com hidden_key
hidden_key	str	'*'	Caractere(s) usados para substituir caracteres mascarados
hidden_start	int	5	Índice inicial (0–13, inclusivo) do intervalo a ocultar
hidden_end	int	13	Índice final (0–13, inclusivo) do intervalo a ocultar
dot_key	str	'.'	Delimitador de ponto (ex.: em 12.345.678)
slash_key	str	'/'	Delimitador de barra (ex.: antes do bloco da filial …/0001-90)
dash_key	str	'-'	Delimitador de traço (ex.: antes dos dígitos verificadores …-90)
escape	bool	False	Quando True, escapa caracteres especiais HTML no resultado
encode	bool	False	Quando True, codifica o resultado para URL (similar ao encodeURIComponent do JavaScript)
on_fail	Callable	retorna ''	Callback quando o comprimento sanitizado ≠ 14; o valor de retorno é usado como resultado

O on_fail padrão retorna uma string vazia. Tipos de entrada incorretos lançam CnpjFormatterInputTypeError.

from br_utils import br_utils
from br_utils.cnpj import cnpj_fmt

cnpj = '03603568000195'

br_utils.cnpj.format(cnpj)              # '03.603.568/0001-95'
br_utils.cnpj.format('12ABC34500DE99')   # '12.ABC.345/00DE-99'
br_utils.cnpj.format(                     # '03.603.###/####-##'
    cnpj,
    hidden=True,
    hidden_key='#',
)
br_utils.cnpj.format(                     # '03603568|0001_95'
    cnpj,
    dot_key='',
    slash_key='|',
    dash_key='_',
)

cnpj_fmt(cnpj)   # '03.603.568/0001-95'

Geração (generate / cnpj_gen)

Opção	Tipo	Padrão	Descrição
format	bool	False	Quando True, retorna o CNPJ gerado no formato padrão (00.000.000/0000-00)
prefix	str	''	String parcial inicial (0–12 caracteres alfanuméricos). Caracteres faltantes são gerados e os dígitos verificadores calculados.
type	'numeric' | 'alphabetic' | 'alphanumeric'	'alphanumeric'	Conjunto de caracteres para a parte gerada aleatoriamente. Os dígitos verificadores são sempre numéricos.

Regras de prefixo: o ID base (primeiros 8 caracteres) e o ID da filial (caracteres 9–12) não podem ser todos zeros; 12 dígitos repetidos (ex.: 111111111111) também não são permitidos.

from br_utils import br_utils
from br_utils.cnpj import cnpj_gen

br_utils.cnpj.generate()               # ex.: '1GJTR3J3XSSA96'
br_utils.cnpj.generate(format=True)    # ex.: 'V1.J0V.8WE/DVZ7-50'
br_utils.cnpj.generate(                # ex.: '12345678855883'
    prefix='12345678',
    type='numeric',
)
cnpj_gen(type='numeric')               # ex.: '65453043000178'

Validação (is_valid / cnpj_val)

Opção	Tipo	Padrão	Descrição
case_sensitive	bool	True	Quando False, letras minúsculas são aceitas para CNPJ alfanumérico (a entrada é convertida para maiúsculas antes da validação).
type	'numeric' | 'alphanumeric'	'alphanumeric'	'numeric': apenas dígitos (0–9); 'alphanumeric': dígitos e letras (0–9, A–Z).

from br_utils import br_utils
from br_utils.cnpj import cnpj_val

br_utils.cnpj.is_valid('98765432000198')   # True
br_utils.cnpj.is_valid('98765432000199')   # False
br_utils.cnpj.is_valid('1QB5UKALPYFP59')   # True
br_utils.cnpj.is_valid('1QB5UKALpyfp59')   # False
br_utils.cnpj.is_valid(                     # True
    '1QB5UKALpyfp59',
    case_sensitive=False,
)
br_utils.cnpj.is_valid(                     # False
    '1QB5UKALPYFP59',
    type='numeric',
)

cnpj_val('98765432000198')                         # True
cnpj_val('1QB5UKALpyfp59', case_sensitive=False)   # True
cnpj_val('1QB5UKALPYFP59', type='numeric')         # False

CNPJ inválido retorna False sem lançar exceção. Tipos de entrada incorretos lançam CnpjValidatorInputTypeError.

Agregadores de domínio (isolados)

Use CpfUtils ou CnpjUtils diretamente quando precisar de apenas um domínio:

from br_utils import CpfUtils, CnpjUtils

cpf_utils = CpfUtils(
    formatter={'hidden': True},
    generator={'format': True},
)

cnpj_utils = CnpjUtils(
    formatter={'hidden': True},
    generator={'format': True},
    validator={'type': 'numeric'},
)

cpf_utils.format('11144477735')       # '111.***.***-**'
cnpj_utils.format('03603568000195')   # '03.603.***/****-**'

Os singletons cpf_utils e cnpj_utils em nível de módulo (reexportados das dependências) também estão disponíveis na raiz do pacote:

from br_utils import cpf_utils, cnpj_utils

cpf_utils.format('11144477735')       # '111.444.777-35'
cnpj_utils.format('03603568000195')   # '03.603.568/0001-95'

Acessando componentes

Cada agregador de domínio expõe seu formatador, gerador e validador internos:

from br_utils import BrUtils

utils = BrUtils()

utils.cpf.formatter.format('11144477735', hidden=True)   # '111.***.***-**'
utils.cpf.generator.generate(format=True)                # ex.: '545.507.690-68'
utils.cpf.validator.is_valid('11144477735')              # True

utils.cnpj.formatter.format('12ABC34500DE99')    # '12.ABC.345/00DE-99'
utils.cnpj.generator.generate(format=True)       # ex.: '8O.BE5.2KL/UI0Y-06'
utils.cnpj.validator.is_valid('03603568000195')  # True

Misturando estilos

Use BrUtils onde uma configuração compartilhada ajuda, e componentes ou helpers isolados em outros pontos — são as mesmas classes subjacentes:

from br_utils import BrUtils
from br_utils.cnpj import CnpjFormatter
from br_utils.cpf import cpf_fmt
from br_utils.cnpj import cnpj_val

utils = BrUtils(cnpj={'validator': {'type': 'numeric'}})

# Via fachada
utils.cpf.format('11144477735')   # '111.444.777-35'

# Via componente retornado pela fachada
utils.cnpj.formatter.format('12ABC34500DE99')   # '12.ABC.345/00DE-99'

# Via instância de componente separada
CnpjFormatter().format('03603568000195')   # '03.603.568/0001-95'

# Via helpers funcionais
cpf_fmt('11144477735')           # '111.444.777-35'
cnpj_val('98.765.432/0001-98')   # True

API

Exportações

Raiz do pacote (br_utils):

• br_utils: Instância pré-construída de BrUtils com cpf e cnpj.
• BrUtils: Classe para criar uma instância com configurações opcionais dos utils de CPF e CNPJ.
• CpfUtils, cpf_utils: Agregador de domínio CPF e seu singleton padrão (de cpf-utils).
• CnpjUtils, cnpj_utils: Agregador de domínio CNPJ e seu singleton padrão (de cnpj-utils).

br_utils.cpf — todas as exportações de cpf-utils (ex.: cpf_fmt, cpf_gen, cpf_val, classes de formatador/gerador/validador, opções, exceções).

br_utils.cnpj — todas as exportações de cnpj-utils (ex.: cnpj_fmt, cnpj_gen, cnpj_val, classes de formatador/gerador/validador, opções, exceções).

Erros e exceções

BrUtils não define seus próprios tipos de exceção; propaga erros dos pacotes empacotados:

• Formatação de CPF: CpfFormatterInputTypeError, CpfFormatterOptionsTypeError, CpfFormatterOptionsHiddenRangeInvalidException, CpfFormatterOptionsForbiddenKeyCharacterException e classes relacionadas.
• Geração de CPF: CpfGeneratorOptionsTypeError, CpfGeneratorOptionPrefixInvalidException e classes relacionadas.
• Validação de CPF: CpfValidatorInputTypeError e classes relacionadas.
• Formatação de CNPJ: CnpjFormatterInputTypeError, CnpjFormatterOptionsTypeError, CnpjFormatterOptionsHiddenRangeInvalidException, CnpjFormatterOptionsForbiddenKeyCharacterException e classes relacionadas.
• Geração de CNPJ: CnpjGeneratorOptionsTypeError, CnpjGeneratorOptionPrefixInvalidException, CnpjGeneratorOptionTypeInvalidException e classes relacionadas.
• Validação de CNPJ: CnpjValidatorInputTypeError, CnpjValidatorOptionsTypeError, CnpjValidatorOptionTypeInvalidException e classes relacionadas.

Tipos de opção inválidos são subclasses de TypeError; valores de opção inválidos são subclasses de Exception. Falhas de validação de CPF e CNPJ retornam False. Falhas de comprimento na formatação são tratadas por on_fail (padrão: retorna '').

from br_utils import BrUtils
from br_utils.cnpj import CnpjFormatterInputTypeError, CnpjValidatorInputTypeError

br_utils = BrUtils()

try:
    br_utils.cnpj.format(12345)   # lança CnpjFormatterInputTypeError
except CnpjFormatterInputTypeError as e:
    print(e)

try:
    br_utils.cnpj.is_valid(12345678000198)   # lança CnpjValidatorInputTypeError
except CnpjValidatorInputTypeError as e:
    print(e)

cpf_out = br_utils.cpf.format(     # 'invalid'
    'short',
    on_fail=lambda value, exception=None: 'invalid',
)
cnpj_out = br_utils.cnpj.format(   # 'invalid'
    'short',
    on_fail=lambda value, exception=None: 'invalid',
)

Para listas exaustivas de exceções e comportamento em casos extremos, consulte o README de cada pacote incluído.

Pacotes incluídos

Pacote	Principais recursos	README
cpf-utils	CpfUtils, CpfFormatter, CpfGenerator, CpfValidator, cpf_fmt(), cpf_gen(), cpf_val()	docs
cnpj-utils	CnpjUtils, CnpjFormatter, CnpjGenerator, CnpjValidator, cnpj_fmt(), cnpj_gen(), cnpj_val()	docs

Todos os símbolos de CPF estão disponíveis em br_utils.cpf; todos os de CNPJ em br_utils.cnpj. Demos interativas: CPF e CNPJ.

Contribuição e suporte

Contribuições são bem-vindas! Consulte as Diretrizes de contribuição. Se o projeto for útil para você, considere:

• ⭐ Dar uma estrela no repositório
• 🤝 Contribuir com código
• 💡 Sugerir novas funcionalidades
• 🐛 Reportar bugs

Licença

Este projeto está sob a licença MIT — veja o arquivo LICENSE.

Changelog

Veja o CHANGELOG para alterações e histórico de versões.

---

Feito com ❤️ por Lacus Solutions