brazilnum

0.8.8 · active · verified Thu Apr 16

brazilnum is a Python library (version 0.8.8) designed for validating and working with various Brazilian identification numbers. It provides functions to validate CNPJ, CEI, CPF, PIS/PASEP, CEP, and municipal codes, which are essential for identifying firms, people, and places in Brazil. While the latest release was in October 2016, it remains a functional tool for these specific validation tasks.

Common errors

```
ModuleNotFoundError: No module named 'brazilnum.cpf'
```
cause Attempting to import validation functions (e.g., `is_cpf`, `is_cnpj`) directly from the top-level `brazilnum` package.

fix Import specific validation functions from their respective submodules, like `from brazilnum.cpf import is_cpf`.
```
AttributeError: module 'brazilnum' has no attribute 'is_cnpj'
```
cause This error occurs when you import the main `brazilnum` package but then try to call a specific validation function directly from it, instead of importing it from its correct submodule.

fix Use a direct import from the submodule: `from brazilnum.cnpj import is_cnpj`.
```
ValueError: Invalid CNPJ format (or similar for other types)
```
cause The input string provided for validation does not conform to the expected format (e.g., 'XX.XXX.XXX/YYYY-ZZ' for CNPJ, 'XXX.XXX.XXX-YY' for CPF, 'XXXXX-XXX' for CEP) or contains invalid characters. Some functions are strict about formatting.

fix Ensure the input string is correctly formatted according to Brazilian standards (e.g., with dots, hyphens, and slashes) before passing it to the validation function.

Warnings

gotcha The project is classified with a 'Development Status :: 4 - Beta' on PyPI. While functional, this indicates it might not be considered fully stable or actively developed for critical production environments.
Fix: Be aware of its beta status and thoroughly test in your environment. Consider the lack of recent updates.
gotcha Some true municipal (município) codes do not strictly follow the standard verification pattern. The library is designed to correctly handle these known exceptions, but it's important for users to be aware of this nuance rather than expecting all valid codes to conform to a simple mathematical rule.
Fix: Rely on the library's `is_muni` function for accurate validation, understanding that internal logic accounts for exceptions.
gotcha The library was last updated in 2016 and explicitly states compatibility with Python 2.7 and 3. While PyPI also lists Python 3 support, users on very recent Python 3 versions (e.g., 3.10+) should perform compatibility testing, as issues might arise with newer language features or dependencies not present at the time of the last release.
Fix: Test thoroughly with your target Python 3 version before deploying. Consider forking or contributing updates if compatibility issues are found.

Install

pip install brazilnum Install latest version

Imports

is_cnpj
wrong:
```
from brazilnum import is_cnpj
```
correct:
```
from brazilnum.cnpj import is_cnpj
```
Validation functions are located in specific submodules.
is_cpf
wrong:
```
from brazilnum import is_cpf
```
correct:
```
from brazilnum.cpf import is_cpf
```
Validation functions are located in specific submodules.
is_cep
wrong:
```
from brazilnum import is_cep
```
correct:
```
from brazilnum.cep import is_cep
```
Validation functions are located in specific submodules.
is_muni
wrong:
```
from brazilnum import is_muni
```
correct:
```
from brazilnum.muni import is_muni
```
Validation functions are located in specific submodules.

Quickstart

This quickstart demonstrates how to import and use the `is_cnpj`, `is_cpf`, and `is_cep` functions to validate common Brazilian identification numbers.

from brazilnum.cnpj import is_cnpj
from brazilnum.cpf import is_cpf
from brazilnum.cep import is_cep

# Example CNPJ validation
cnpj_number = '00.000.000/0001-91'
print(f"Is '{cnpj_number}' a valid CNPJ? {is_cnpj(cnpj_number)}")

# Example CPF validation
cpf_number = '111.444.777-00'
print(f"Is '{cpf_number}' a valid CPF? {is_cpf(cpf_number)}")

# Example CEP validation
cep_number = '01001-000'
print(f"Is '{cep_number}' a valid CEP? {is_cep(cep_number)}")

view raw JSON →