validate-docbr

validate-docbr

validate-docbr is a Python package designed for validating Brazilian documents. It provides tools for verifying the authenticity of various identification numbers and generating valid documents for testing purposes.

Supported Document Types:

• CPF (Cadastro de Pessoas Físicas)
• CNPJ (Cadastro Nacional da Pessoa Jurídica)
• CNH (Carteira Nacional de Habilitação)
• CNS (Cartão Nacional de Saúde)
• PIS (Programa de Integração Social)
• Título Eleitoral (Voter ID)
• RENAVAM (Registro Nacional de Veículos Automotores)
• Certidão (Certificates)

Key Features:

• Validation: Check if a document number is valid according to official algorithms.
• Generation: Generate valid document numbers for use in automated tests or development environments.
• Formatting: Apply masks to document numbers for consistent presentation.

By default, validate-docbr considers CPFs with repeated digits (e.g., 111.111.111-11) as valid because some are linked to real people.

To reject these patterns, set the repeated_digits parameter to True during instantiation or update the repeated_digits attribute on the object.

• repeated_digits=True: Accepts repeated digit patterns.
• repeated_digits=False (default): Rejects repeated digit patterns.

from validate_docbr import CPF

# Accept repeated digits
cpf = CPF(repeated_digits=True)
cpf.validate("111.111.111-11")  # True

# Reject repeated digits
cpf.repeated_digits = False
cpf.validate("111.111.111-11")  # False

The package provides specialized classes for validating various Brazilian documents. Each document type follows a consistent API pattern. Supported documents include:

• CPF: Cadastro de Pessoas Físicas
• CNH: Carteira Nacional de Habilitação
• CNPJ: Cadastro Nacional da Pessoa Jurídica (supports both numeric and alphanumeric)
• CNS: Cartão Nacional de Saúde
• PIS: PIS/NIS/PASEP/NIT
• Título eleitoral: Voter registration
• RENAVAM: Registro Nacional de Veículos Automotores
• Certidão: Birth/Marriage/Death certificates

Install the validate-docbr Python package using pip or uv to enable validation of Brazilian documents.

pip install validate-docbr

The validate-docbr package provides specialized classes to validate various Brazilian identification documents. You can instantiate a specific document class (like CPF, CNPJ, or CNH) and use its validation methods, or use the validate_docs utility to validate multiple different document types at once.

from validate_docbr import CPF, CNPJ, validate_docs

# Validate a single CPF
cpf_validator = CPF()
is_valid = cpf_validator.validate('123.456.789-00')

# Validate multiple different documents
results = validate_docs({
    'cpf': '123.456.789-00',
    'cnpj': '12.345.678/0001-99'
})

You can run the validate-docbr application using Docker Compose. The service is configured to build from the current directory and maps the local directory to the /app directory inside the container, allowing for live development or volume-based data processing.

To start the service, run:

docker-compose up

services:
  app:
    build:
      context: .
    image: alvarofpp/validate-docbr
    container_name: validate-docbr
    volumes:
      - .:/app

Generate a single new valid document string using the generate() method.

Parameters:

• mask (bool, default False): If True, returns the document with formatting (e.g., dots and dashes).

from validate_docbr import CPF

cpf = CPF()

# Gerar novo CPF
new_cpf_one = cpf.generate()  # "01234567890"
new_cpf_two = cpf.generate(True)  # "012.345.678-90"

Generate a list of new valid documents using generate_list(n, mask, repeat).

Parameters:

• n (int): The number of documents to generate.
• mask (bool, default False): Whether to return documents with formatting.
• repeat (bool, default False): Whether to allow repeated documents in the list.

from validate_docbr import CPF

cpf = CPF()

# Gerar lista de CPFs
cpfs_one = cpf.generate_list(2)
# [ "85215667438", "28293145811" ]

cpfs_two = cpf.generate_list(2, True)
# [ "852.156.674-38", "282.931.458-11" ]

Use the validate(doc) method on a document instance (like CPF) to check if a document string is valid. It returns True if valid and False otherwise.

Parameters:

• doc (str): The document string to validate.

from validate_docbr import CPF

cpf = CPF()

# Validar CPF
cpf.validate("012.345.678-90")  # True
cpf.validate("012.345.678-91")  # False

Use validate_list(docs) to validate multiple documents of the same type at once. It returns a list of booleans corresponding to each input.

Parameters:

• docs (list[str]): A list of document strings.

from validate_docbr import CPF

cpf = CPF()

# Validar CPFs
cpf.validate_list(["012.345.678-90", "012.345.678-91"])
# [True, False]

Use the mask(doc) method to apply the standard formatting (mask) to a raw document string.

Parameters:

• doc (str): The unformatted document string.

from validate_docbr import CPF

cpf = CPF()

cpf_me = "01234567890"

# Mascara o CPF
cpf.mask(cpf_me)  # "012.345.678-90"

Document classes provide methods to generate new, valid documents.

.generate(mask=False)

Generates a single document as a str. Use mask=True to return the document with formatting (e.g., dots and dashes).

.generate_list(n=1, mask=False, repeat=False)

Generates a list of n documents.

• n: Quantity to generate.
• mask: Whether to include formatting.
• repeat: Whether to allow duplicate documents in the list.

from validate_docbr import CPF

cpf = CPF()

# Gerar novo CPF
new_cpf_one = cpf.generate()  # "01234567890"
new_cpf_two = cpf.generate(mask=True)  # "012.345.678-90"

# Gerar lista de CPFs
cpfs_one = cpf.generate_list(2)
# [ "85215667438", "28293145811" ]
cpfs_two = cpf.generate_list(2, mask=True)
# [ "852.156.674-38", "282.931.458-11" ]