brazilian-utils/brutils-python

Biblioteca de utilitários projetada para validar, gerar e manipular dados de acordo com as particularidades do Brasil 🇧🇷

🇧🇷 Brazilian Utils

Utils library for Brazilian-specific businesses.

📖 Documentation

---

Vidas Negras Importam | Black Lives Matter. ✊🏽✊🏾✊🏿

To know how to help, just go to Vidas Negras Importam or Black Lives Matter.

---

We are changing

After one year of Brazilian Utils and lots of feedback, we decided to refactor our library to fix issues, create a website and make it easier for other developers to contribute. If you use v0 version, please, check v0 branch.

---

Table of Contents

• Getting Started
  • Installation
  • Usage
  • Contributors
  • License

Getting Started

Brazilian Utils is a library focused on solving problems that we face daily in the development of applications for the Brazilian business.

Installation

Using Brazilian Utils is quite simple and you can use it in some ways:

as npm package:

npm install --save @brazilian-utils/brazilian-utils

with yarn package manager:

yarn add @brazilian-utils/brazilian-utils

or <script> tag (global brazilianUtils):

<script src="https://unpkg.com/@brazilian-utils/brazilian-utils/dist/brazilian-utils.cjs.production.min.js"></script>

Usage

To use one of our utilities you just need to import the required function as in the example below:

import { isValidCPF } from '@brazilian-utils/brazilian-utils';

isValidCPF('1232454233345'); // false

You can check a list of utilities by clicking here.

Contributors

Our "thank you" goes to these wonderful people (emoji key):

Hyan Mandian 💻 📖 🤔 ⚠️	Lucas Veloso 💻 📖 🤔 ⚠️	Andreo Vieira 💻 📖 🤔 🔧	Matheus Almeida 💻 📖 ⚠️	Fernando Rogelin 💻 📖 ⚠️	rodineijf 💻 📖 ⚠️	Emerson Laurentino 💻 📖 ⚠️
Leonardo Dutra 💻 📖 ⚠️	Victor Magalhães 💻 🔧	Amauri Dias 💻 🔧	Felipe F. Diogo 💻 ⚠️	Alan Raso 💻 ⚠️	Felipe Fetter 📖	Rafael Franco 💻 📖
Rafael Pezzetti 💻 ⚠️ 📖	Antonio Roberto Furlaneto 💻 📖 ⚠️	Felipe Nolleto Nascimento 💻 📖 ⚠️	Saulo Joab 📖	Pedro Arantes 💻 📖 ⚠️	Silvio Clécio 💻 📖 ⚠️	Lucas Nascimento 💻
Lincon Kusunoki 💻 📖 ⚠️	Marcelo Cristiano 💻 📖 ⚠️	Tarcísio Batista de Freitas Junior 📖	Lucas Carrias 📖 ⚠️ 💻 🔧

This project follows the all-contributors specification. Contributions of any kind are welcome!

License

MIT

brutils-python's Issues

Add github action to run tests on every push

Add github action to run tests on every push. Example:

https://github.com/brazilian-utils/python/blob/master/.github/workflows/test.yaml

Lançar versão

Seguindo esses padrões: https://keepachangelog.com/en/1.0.0/

Configurar workflow de testes para rodar em pull requests

Atualmente só está rodando quando acontece um push

Adicionar instruções de como lançar uma nova versão

Adicionar instruções de como fazer uma release. Esta informação deve estar presente nos arquivos CONTRIBUTING.md e CONTRIBUTING_EN.md

O passo a passo é muito semelhante aos descritos aqui https://github.com/scanapi/scanapi/wiki/Deploy, porém desconsiderando tudo que é relacionado ao Docker ou Twitter.

Add .gitignore fille

Add .gitignore file to avoid pushing files that we should not, like:

~/workspace/brutils-python  main ✗                                                                     1h47m ◒
▶ git status
On branch main
Your branch is up to date with 'origin/main'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	brutils/__pycache__/
	tests/__pycache__/

nothing added to commit but untracked files present (use "git add" to track)

Add code lint checker

Add a make command to check the code's. Related to #5

Format README's to make them look like the JS API docs

Format README's to make it looks like the JS API docs

https://brazilian-utils.com.br/#/getting-started

Validação de número de telefone fixo brasileiro

Formatação de CEPs

Implementar um utilitário que recebe um CEP apenas com dígitos e retorna o CEP com símbolos (ponto e traço)

Improve is_valid_cpf

Rename master branch to main

Rename master branch to main to avoid slavery references.

Reason: https://github.com/github/renaming

create a folder with old documentation

in order to show older documentation to 1.0.1 version users

Validação de CEPs

Implementar um utilitário que valida CEPs

Add Pytest

Add pytest

Some good points to start using pytest:

• https://blog.j-labs.pl/2019/02/Pytest-why-its-more-popular-than-unittest
• https://www.guru99.com/pytest-tutorial.html#2

Add `isValidCNPJ ` method

In order to make it with the same API as js brutils

Gerar CEPs aleatórios e válidos

Implementar um utilitário que retorna um CEP aleatório válido

Melhorar os testes do método parse do CNPJ

Ao invés de chamar os mesmos asserts do sieve, verificar se o método sieve foi chamado.

Ideia Análoga:

brutils-python/tests/test_cpf.py

Lines 35 to 39 in c741843

	def test_parse(self):
	with patch("brutils.cpf.sieve") as mock_sieve:
	# When call parse, it calls sieve
	parse("123.456.789-10")
	mock_sieve.assert_called()

Add commit message lint check

Maybe gitlint?

Renomear métodos parse para algum nome que seja mais explícito

Talvez "remove_symbols", "remove_symbols_cpf" e "remove_symbols_cnpj"?

Add Poetry

Add Poetry

Some good points to start using Poetry:

• https://nanthony007.medium.com/stop-using-pip-use-poetry-instead-db7164f4fc72
• https://andrewbrookins.com/python/why-poetry/

Validação de número de telefone brasileiro (fixo ou móvel)

Criar mais testes para o utilitário is_valid_cnpj

Criar mais casos de teste para o utilitário is_valid_cnpj.

Alguns exemplos:

• testar quando o input não é uma string
• testar quando o input não tem o tamanho correto
• testar quando o input não contém apenas dígitos

Você pode utilizar o exemplo do CPF como base:

brutils-python/tests/test_cpf.py

Line 64 in 1b12ebf

def test_is_valid(self):

O algoritmo considerado para validação é este: https://www.geradorcnpj.com/algoritmo_do_cnpj.htm

Lembre-se também que você pode consultar como foi feita a implementação na biblioteca JS: https://github.com/brazilian-utils/brazilian-utils/tree/main/src/utilities/cnpj

Add a pre-commit hook to check and format the code

Add a pre-commit hook to check and format the code. Related to #5 and #6

Add a static analysis checker

Add a static analysis checker to:

• measure test coverage
• check security issues
• doc string coverage
• style issues

My suggestion: https://deepsource.io

Add brazilian-utils header to README.md and README_EN.md files

Add brazilian-utils header to README.md and README_EN.md files

Like this:

The same we have for JS version: https://github.com/brazilian-utils/brazilian-utils/blob/main/README.md

Code:

<div align="center">
<h1>🇧🇷 Brazilian Utils</h1>

<p>Utils library for Brazilian-specific businesses.</p>
</div>

Format `generate` method

In order to make it the same as the other methods.
@camilamaia

Validação de número de telefone móvel brasileiro

Fix make install

It should be

install:
	@poetry install
	@poetry run pre-commit install -f -t pre-commit --hook-type commit-msg

instead of:

install:
	@poetry run pre-commit install -f -t pre-commit --hook-type commit-msg
	@poetry install

Validação de Boletos

Implementar um utilitário que valida boletos

Remover Símbolos de CEPs

Implementar um utilitário que recebe um CEP com símbolos (ponto e traço) e retorna esse CEP apenas com dígitos

Tapa no arquivo de CNPJ

• Arrumar a ordem das funções
• Definir funções privadas
• Arrumar testes faltantes

Utilizar `assert` métodos do unittest ao invés do assert que já vem no Python

ex: ao invés de : https://docs.python.org/3/library/unittest.html#test-cases mudar para utilizar assertEqual (https://docs.python.org/3/library/unittest.html#test-cases)

Mudar os nomes de classes de teste para começar com a palavra `Test`

Para seguir padrão.

Examplo: https://github.com/brazilian-utils/brutils-python/blob/67a255e355cc5f1e056813bd18c2324ed05e1a34/tests/test_cpf.py#L26C1-L26C1

ao invés de

class CPF(TestCase):

deveria ser:

class TestCPF(TestCase):

Add formatCNPJ method

In order to make it with the same API as js brutils

Adicionar seções ao readme de "Novos Utilitários/Reportar Bugs" e "Dúvidas? Ideias?"

Para indicar como os usuários podem interagir com a gente da melhor forma :)

Add `isValidCPF ` method

In order to make it with the same API as js brutils

Add a github action to check code format

Related to #6

Refatoracao do codigo dos utilitarios de CPF

Criar um Código de Conduta para o repositório

1. Criar um arquivo na raíz do projecto chamado CODE_OF_CONDUCT.md. Ele deve conter o Código de Conduta do repositório em português.
2. Criar um arquivo na raíz do projecto chamado CODE_OF_CONDUCT_EN.md. Ele deve conter o Código de Conduta do repositório em inglês.

Sobre Código de Conduta:

• https://opensource.guide/pt/code-of-conduct/#:~:text=Um%20código%20de%20conduta%20é,seus%20participantes%2C%20mas%20você%20mesmo.

Exemplos:

• https://github.com/okfn-brasil/.github/blob/main/profile/CODE_OF_CONDUCT.md / https://github.com/okfn-brasil/.github/blob/4bc836cd985fcf95f9f868d79cccecc48817dcb9/profile/CODE_OF_CONDUCT-en-US.md
• https://github.com/scanapi/scanapi/blob/main/CODE_OF_CONDUCT.md
• https://www.contributor-covenant.org

Melhorar format_cnpj e o seus testes

1. Chamar a função is_valid e formatar o cnpj, sem utilizar o método display.
   Código referência:
   

   brutils-python/brutils/cpf.py

   Lines 38 to 48 in 756f126

   	def format_cpf(cpf): # type: (str) -> str
   	"""
   	Format an adequately formatted numbers-only CPF string,
   	Returns a cpf formatted with standard visual aid symbols.
   	Returns None if cpf is invalid.
   	"""
   	if not is_valid(cpf):
   	return None
   	return "{}.{}.{}-{}".format(cpf[:3], cpf[3:6], cpf[6:9], cpf[9:])

2. Melhorar os testes da função format_cnpj:

Código referência:

brutils-python/tests/test_cpf.py

Lines 47 to 57 in 756f126

	def test_format_cpf(self):
	with patch("brutils.cpf.is_valid", return_value=True) as mock_is_valid:
	# When cpf is_valid, returns formatted cpf
	assert format_cpf("11144477735") == "111.444.777-35"
	# Checks if function is_valid_cpf is called
	mock_is_valid.assert_called_once_with("11144477735")
	with patch("brutils.cpf.is_valid", return_value=False) as mock_is_valid:
	# When cpf isn't valid, returns None
	assert format_cpf("11144477735") is None

Add a github action to automatically publish the package into Pypi

Add a github action to automatically publish the package into Pypi. This way, we skip a manual process and we don't need to give pypi access to more people.

Example:
https://github.com/scanapi/scanapi/blob/master/.github/workflows/publish-to-pypi.yml

Add a changelog file

Create a changelog file. More info at: https://keepachangelog.com/en/1.0.0/

Melhorando a função format_cpf

Chama a função is_valid para checar o CPF, se True retorna o número com os símbolos, senão, retorna None.

Adicionar CODEOWNERs

Adicionar maintainers e core team como CODEOWNERs

https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners

Add `parse_cpf` method

To map sieve to parse_cpf in order to make the name compatible with the js brutils

Atualizar arquivos de Contribuição

• Renomear o arquivo https://github.com/brazilian-utils/brutils-python/blob/main/CONTRIBUTING.md para https://github.com/brazilian-utils/brutils-python/blob/main/CONTRIBUTING_EN.md
• Criar um arquivo https://github.com/brazilian-utils/brutils-python/blob/main/CONTRIBUTING.md com o conteúdo em português
• Adicionar uma seção de contribuição como essa no README.md e README_EN.md

Add `parse_cnpj` method

To map sieve to parse_cnpj in order to make the name compatible with the js brutils

Add code formatter

Add a make command to auto format the code. flake8 might be a good option.

Adicionar flake8

https://flake8.pycqa.org/en/latest/

1. Adicionar flake8 como dependência dev:
   

   brutils-python/pyproject.toml

   Lines 34 to 36 in ddb26d9

   	[tool.poetry.group.dev.dependencies]
   	black = "^23.3.0"
   	pre-commit = "^2.21.0"

2. Rodar o flake8 no comando make format. Análogo ao black:

   brutils-python/Makefile

   Line 12 in ddb26d9

   @poetry run black -l 80 . --exclude=.venv

O comando make format deve rodar tanto o black quanto o flake8, algo como:

format:
	@poetry run black -l 80 . --exclude=.venv
        @poetry run flake8

Add `formatCPF` method

In order to make it with the same API as js brutils