validate-docbr

⚠️ Estamos planejando a versão 2.0.0 do pacote. Para saber as mudanças que estão por vir, leia a issue #67. Você também pode sugerir atualizações para o pacote na mesma issue, participe! ⚠️

Pacote Python para validação de documentos brasileiros.

Para instalar o pacote:

pip install validate-docbr

A documentação pode ser acessada clicando aqui.

Documentos

Documentos que estão no pacote:

• CPF: Cadastro de Pessoas Físicas;
• CNH: Carteira Nacional de Habilitação;
• CNPJ: Cadastro Nacional da Pessoa Jurídica;
• CNS: Cartão Nacional de Saúde;
• PIS: PIS/NIS/PASEP/NIT;
• Título eleitoral: Cadastro que permite cidadãos brasileiros votar;
• RENAVAM: Registro Nacional de Veículos Automotores.

Para entender melhor os documentos e suas respectivas classes, basta acessar a Wiki do projeto.

Métodos

Todos os documentos possuem os mesmos métodos e funcionam da mesma forma.

validate

Valida o documento passado como argumento. Retorna um bool, True caso seja válido, False caso contrário. Recebe os parâmetros:

Parâmetro	Tipo	Valor padrão	Obrigatório	Descrição
doc	str	''	X	O documento que se quer validar.

from validate_docbr import CPF

cpf = CPF()

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

Caso especial de CPF.

validate_list

Valida uma lista de documentos passado como argumento. Retorna uma lista de bool, True caso seja válido, False caso contrário. Recebe os parâmetros:

Parâmetro	Tipo	Valor padrão	Obrigatório	Descrição
docs	List[str]	[]	X	A lista de documentos para validar.

from validate_docbr import CPF

cpf = CPF()

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

validate_docs

Observação: diferente dos outros métodos, esse método é do escopo global do pacote, não precisa-se instanciar uma classe para uso.

Valida vários documentos difererentes. Retorna uma lista com valores bool para cada tupla da lista (na mesma ordem), True caso seja válido, False caso contrário. Recebe os parâmetros:

Parâmetro	Tipo	Valor padrão	Obrigatório	Descrição
documents	List[Tuple[BaseDoc, str]]	[]	X	Lista de tuplas, cada tupla possui como primeiro elemento o tipo de documento e o segundo elemento o valor que se deseja validar.

import validate_docbr as docbr


# Validar diferentes documentos
docs = [(docbr.CPF, '90396100457'), (docbr.CNPJ, '49910753848365')]
docbr.validate_docs(docs)  # [True, False]

generate

Gera um novo documento, retorna em formato de str. Recebe os parâmetros:

Parâmetro	Tipo	Valor padrão	Obrigatório	Descrição
mask	bool	False	-	Quando possui o valor True, o documento retornado estará formatado.

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"

generate_list

Gera uma lista de documentos, retorna em formato de list com elementos do tipo str. Recebe os parâmetros:

Parâmetro	Tipo	Valor padrão	Obrigatório	Descrição
n	int	1	X	A quantidade desejada de documentos que serão gerados.
mask	bool	False	-	Se os documentos gerados deverão ter ou não máscara.
repeat	bool	False	-	Se aceita ou não documentos repetidos.

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, mask=True)  # [ "852.156.674-38", "282.931.458-11" ]

mask

Mascara o documento passado como argumento. Retorna um str que é o documento mascarado. Recebe os parâmetros:

Parâmetro	Tipo	Valor padrão	Obrigatório	Descrição
doc	str	''	X	O documento que se quer mascarar.

from validate_docbr import CPF

cpf = CPF()

cpf_me = "01234567890"

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

Testes

Para realizar os testes basta executar o seguinte comando:

make test

Para verificar a cobertura de testes:

make test-coverage