as-cnpj 0.1.0

Biblioteca autoral AS-CNPJ para validacao, normalizacao e formatacao de CNPJ numerico e alfanumerico.

Biblioteca autoral do ecossistema AS-CNPJ para validação, normalização, formatação e cálculo de dígitos verificadores de CNPJ numérico e alfanumérico em Python.

Repositório · Site · Hub do ecossistema · API · Testes

Idiomas: Português (Brasil) | English | Español | Français

Status

• repositório público e ativo;
• CI rodando em Python 3.10, Python 3.11, Python 3.12, Python 3.13 e Python 3.14;
• API funcional e coberta por testes automatizados;
• release workflow preparado para publicação no PyPI via Trusted Publishing;
• candidato imediato à primeira publicação pública do port Python.

Instalação

Enquanto a publicação no PyPI não acontece, a forma mais direta de avaliação é instalar a partir do GitHub:

python -m pip install git+https://github.com/as-cnpj/as-cnpj-python.git

Import package:

from as_cnpj import is_valid_cnpj

Exemplo rápido

from as_cnpj import (
    assert_valid,
    calculate_cnpj_check_digits,
    format_cnpj,
    is_valid,
    normalize,
)

is_valid("12.ABC.345/01DE-35")
normalize("12.abc.345/01de-35")
format_cnpj("12ABC34501DE35")
assert_valid("12.ABC.345/01DE-35", strict=True)
calculate_cnpj_check_digits("12ABC34501DE")

Casos de uso

• formulários de cadastro B2B com aceitação do formato legado e do formato alfanumérico;
• backends Python que precisam validar payloads antes de persistir ou integrar com ERP;
• rotinas de saneamento e migração de base com normalização consistente;
• suites de teste e homologação que precisam gerar e validar exemplos de CNPJ.

O que esta biblioteca entrega

• validação de CNPJ numérico legado;
• validação de CNPJ alfanumérico previsto pela Receita Federal para julho de 2026;
• suporte a entradas com máscara e sem máscara;
• modo permissivo e modo estrito;
• zero dependências de runtime para o núcleo do algoritmo;
• consistência com vetores compartilhados do hub.

API pública

Funções principais:

• normalize(value)
• is_valid(value, strict=False)
• format(value, strict=False)
• assert_valid(value, strict=False)
• calculate_check_digits(base12)

Aliases explícitos:

• normalize_cnpj(value)
• is_valid_cnpj(value, strict=False)
• format_cnpj(value, strict=False)
• assert_valid_cnpj(value, strict=False)
• calculate_cnpj_check_digits(base12)

Garantias centrais

• aceita A-Z0-9 nos 12 primeiros caracteres;
• mantém os 2 dígitos verificadores como numéricos;
• usa módulo 11 com conversão ASCII - 48;
• normaliza entrada para caixa alta;
• rejeita repetições triviais inválidas;
• mantém o contrato alinhado aos vetores compartilhados do ecossistema.

Documentação e referências

• API da biblioteca
• Estratégia de testes
• Checklist de release
• Política de segurança
• Hub do ecossistema AS-CNPJ

Publicação

• pacote planejado no PyPI: as-cnpj
• import público: as_cnpj
• release via GitHub Releases com Trusted Publishing para o PyPI

Vetores compartilhados

O as-cnpj-python não define a verdade sozinho.

O contrato do ecossistema depende também de:

• vetores compartilhados no hub;
• regras documentadas a partir das fontes oficiais;
• convergência entre implementações em linguagens diferentes.

Manutenção

Maintainer: @0moura
Contato institucional: [e-mail]