Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/alvarofpp/validate-docbr
Pacote Python para validação de documentos brasileiros.
https://github.com/alvarofpp/validate-docbr
cnh cnpj cns cpf hacktoberfest nis nit pasep pis tituloeleitor validation-library
Last synced: 5 days ago
JSON representation
Pacote Python para validação de documentos brasileiros.
- Host: GitHub
- URL: https://github.com/alvarofpp/validate-docbr
- Owner: alvarofpp
- License: mit
- Created: 2019-03-07T19:27:23.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2024-08-14T13:54:56.000Z (4 months ago)
- Last Synced: 2024-12-05T07:04:40.528Z (19 days ago)
- Topics: cnh, cnpj, cns, cpf, hacktoberfest, nis, nit, pasep, pis, tituloeleitor, validation-library
- Language: Python
- Homepage: https://alvarofpp.github.io/validate-docbr/
- Size: 926 KB
- Stars: 468
- Watchers: 6
- Forks: 51
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# validate-docbr
> :warning: Estamos planejando a versão `2.0.0` do pacote. **Para saber as mudanças que estão por
> vir, leia a [issue #67](https://github.com/alvarofpp/validate-docbr/issues/67)**.
> Você também pode sugerir atualizações para o pacote na mesma issue, participe! :warning:
Pacote Python para validação de documentos brasileiros.
Para instalar o pacote:
```shell
pip install validate-docbr
```
A documentação pode ser acessada [clicando aqui](https://alvarofpp.github.io/validate-docbr).
## Documentos
Documentos que estão no pacote:
- [CPF](validate_docbr/CPF.py): Cadastro de Pessoas Físicas;
- [CNH](validate_docbr/CNH.py): Carteira Nacional de Habilitação;
- [CNPJ](validate_docbr/CNPJ.py): Cadastro Nacional da Pessoa Jurídica;
- [CNS](validate_docbr/CNS.py): Cartão Nacional de Saúde;
- [PIS](validate_docbr/PIS.py): PIS/NIS/PASEP/NIT;
- [Título eleitoral](validate_docbr/TituloEleitoral.py): Cadastro que permite cidadãos brasileiros votar;
- [RENAVAM](validate_docbr/RENAVAM.py): Registro Nacional de Veículos Automotores.
Para entender melhor os documentos e suas respectivas classes, basta acessar a [Wiki do projeto](https://github.com/alvarofpp/validate-docbr/wiki).
## 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. |
```python
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](https://alvarofpp.github.io/validate-docbr/guia-de-uso/#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. |
```python
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. |
```python
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. |
```python
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. |
```python
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. |
```python
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:
```shell
make test
```
Para verificar a cobertura de testes:
```shell
make test-coverage
```