diff --git a/.lint/.markdownlintrc b/.lint/.markdownlintrc new file mode 100644 index 0000000..e004882 --- /dev/null +++ b/.lint/.markdownlintrc @@ -0,0 +1,11 @@ +{ + "default": true, + "heading-style": { "style": "atx" }, + "ul-style": { "style": "dash" }, + "line-length": { "line_length": 100 }, + "no-duplicate-heading": { "allow_different_nesting": true }, + "no-trailing-punctuation": { "punctuation": ".,;:!" }, + "no-blanks-blockquote": false, + "no-inline-html": { "allowed_elements": ["p", "a", "img"] }, + "hr-style": { "style": "---" } +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9f85695..5fadba8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,16 @@ # Contribuindo + Para contribuir com o pacote com a inserção de um novo documento: + - Crie uma _issue_ dizendo sobre o documento que deseja inserir ao pacote; - Preferencialmente coloque links que ajudem a entender o algoritmo de geração e válidação do documento. - Realize os procedimentos padrões, sendo que na hora de criar a sua _branch_, referencie a sua _issue_; - Realize o _pull request_ para a branch _master_. ## Sobre o código + Para novos documentos: + - Criar uma classe com as siglas do documento (herdando a classe pai `BaseDoc`); - Importar a classe no `__init__.py`; - Criar testes em `test/`. diff --git a/LICENSE b/LICENSE index 6fb0f45..40bbeae 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright (c) 2021, Álvaro Ferreira Pires de Paiva +Copyright (c) 2019, Álvaro Ferreira Pires de Paiva Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation diff --git a/README.md b/README.md index 0da9464..8c47520 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # validate-docbr + latest release @@ -6,20 +7,15 @@ Pacote Python para validação de documentos brasileiros. Para instalar o pacote: -```bash + +```shell pip install validate-docbr ``` A documentação pode ser acessada [clicando aqui](https://alvarofpp.github.io/validate-docbr). -## Testes -Para realizar os testes basta executar o seguinte comando: - -```shell -coverage run -m unittest discover tests && coverage report -m -``` - ## Documentos + Documentos que estão no pacote: - [CPF](validate_docbr/CPF.py): Cadastro de Pessoas Físicas; @@ -33,10 +29,13 @@ Documentos que estão no pacote: 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: + +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 | | --------- | ---- | ----------- | ------------ | --------- | @@ -56,7 +55,8 @@ cpf.validate("012.345.678-91") # False ### 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: +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 | | --------- | ---- | ----------- | ------------ | --------- | @@ -72,14 +72,21 @@ 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: +**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 @@ -90,12 +97,17 @@ 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 @@ -107,14 +119,16 @@ 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: + +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 @@ -126,7 +140,9 @@ cpfs_two = cpf.generate_list(2, mask=True) # [ "852.156.674-38", "282.931.458-1 ``` ### mask -Mascara o documento passado como argumento. Retorna um `str` que é o documento mascarado . Recebe os parâmetros: + +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 | | --------- | ---- | ----------- | ------------ | --------- | @@ -142,3 +158,11 @@ 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 +coverage run -m unittest discover tests && coverage report -m +``` diff --git a/docs/guia-de-uso.md b/docs/guia-de-uso.md index 20434b3..0259310 100644 --- a/docs/guia-de-uso.md +++ b/docs/guia-de-uso.md @@ -1,9 +1,11 @@ -# Métodos +# Guia de uso + 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: + +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 | | --------- | ---- | ----------- | ------------ | --------- | @@ -20,7 +22,13 @@ cpf.validate("012.345.678-91") # False ``` ### Caso especial de CPF -Os CPFs de 000.000.000-00 até 999.999.999-99 são considerados como válidos pois, em alguns casos, existem pessoas vinculadas a eles. Usei a base de dados da [Coleção de CNPJs e CPFs brasileiros do Brasil.IO](https://brasil.io/dataset/documentos-brasil/documents) para verificar esses documentos: + +Os CPFs de 000.000.000-00 até 999.999.999-99 são considerados como válidos pois, em alguns casos, +existem pessoas vinculadas a eles. Usei a base de dados da +[Coleção de CNPJs e CPFs brasileiros do Brasil.IO][brasil.io] +para verificar esses documentos: + + | CPF | Pessoa | Consulta | | --- | ------ | -------- | @@ -35,7 +43,11 @@ Os CPFs de 000.000.000-00 até 999.999.999-99 são considerados como válidos po | 888.888.888-88 | - | `https://brasil.io/dataset/documentos-brasil/documents?search=88888888888&document_type=CPF&document=&name=&sources=` | | 999.999.999-99 | JOAQUIM ROCHA MATOS | `https://brasil.io/dataset/documentos-brasil/documents?search=99999999999&document_type=CPF&document=&name=&sources=` | -Porém, é comum optar por não validar esses CPFs. Para isso basta usar o parâmetro `repeated_digits` (por padrão é `False`) da classe `CPF` ou mudar a variável de mesmo nome no objeto criado. + + +Porém, é comum optar por não validar esses CPFs. Para isso basta usar o parâmetro `repeated_digits` +(por padrão é `False`) da classe `CPF` ou mudar a variável de mesmo nome no objeto criado. + ```python from validate_docbr import CPF @@ -51,10 +63,10 @@ cpf.repeated_digits = False cpf.validate("111.111.111-11") # False ``` ------------- ## 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: +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 | | --------- | ---- | ----------- | ------------ | --------- | @@ -69,16 +81,22 @@ cpf = CPF() 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: +**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 @@ -88,14 +106,18 @@ 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 @@ -106,8 +128,8 @@ new_cpf_one = cpf.generate() # "01234567890" new_cpf_two = cpf.generate(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 | @@ -126,9 +148,9 @@ cpfs_one = cpf.generate_list(2) # [ "85215667438", "28293145811" ] cpfs_two = cpf.generate_list(2, 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: + +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 | | --------- | ---- | ----------- | ------------ | --------- | @@ -144,3 +166,5 @@ cpf_me = "01234567890" # Mascara o CPF cpf.mask(cpf_me) # "012.345.678-90" ``` + +[brasil.io]: https://brasil.io/dataset/documentos-brasil/documents diff --git a/docs/index.md b/docs/index.md index d3a850a..091d7db 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,5 @@ # validate-docbr + latest release diff --git a/docs/licenca.md b/docs/licenca.md index 7bd0069..8fb24c0 100644 --- a/docs/licenca.md +++ b/docs/licenca.md @@ -1,21 +1,24 @@ # MIT License -Copyright (c) 2018 The Python Packaging Authority +Copyright (c) 2019, Álvaro Ferreira Pires de Paiva -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: +Permission is hereby granted, free of charge, to any person +obtaining a copy of this software and associated documentation +files (the “Software”), to deal in the Software without +restriction, including without limitation the rights to use, +copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the +Software is furnished to do so, subject to the following +conditions: -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. diff --git a/docs/sobre.md b/docs/sobre.md index a0713a5..0ddffa0 100644 --- a/docs/sobre.md +++ b/docs/sobre.md @@ -1,6 +1,9 @@ +# Sobre + Pacote Python para validação de documentos brasileiros. ## Documentos + Documentos que estão no pacote: - CPF: Cadastro de Pessoas Físicas; diff --git a/mkdocs.yml b/mkdocs.yml index 8864ffc..b66a28d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,13 +1,14 @@ +--- site_name: validate-docbr site_url: https://github.com/alvarofpp/validate-docbr site_description: Pacote Python para validação de documentos brasileiros. site_author: MkDocs Team nav: - - Instalação: index.md - - Guia de uso: guia-de-uso.md - - Sobre: sobre.md - - Licença: licenca.md + - Instalação: index.md + - Guia de uso: guia-de-uso.md + - Sobre: sobre.md + - Licença: licenca.md repo_url: https://github.com/alvarofpp/validate-docbr