PythonCodingGuidelines
1.0.0
As Diretrizes de codificação Python são um conjunto de diretrizes, regras e práticas recomendadas testadas e comprovadas sobre codificação em Python.
O objetivo das diretrizes é ajudar os desenvolvedores a usar o Python de maneira eficaz e fornecer um estilo Python moderno e mais legível. Um código de fácil manutenção e escalonável. Além disso, estabelecer um padrão de desenvolvimento a ser seguido no desenvolvimento de aplicações ou bibliotecas em Python.
Espero que este documento também possa ajudá-lo a começar a usar Python. Se você vem de outra linguagem de script como JavaScript, descobrirá que Python é muito semelhante e este documento é uma forma de fazer a transição para Python.
As diretrizes estão focadas em todos os recursos fornecidos pela Linguagem Python normalmente definidos no Padrão PEP8. PEP8 PEP8 aqui é usado apenas como base para esta proposta de diretriz de codificação. Quero promover um estilo Python mais legível e moderno.
Você pode achar que algumas das regras desta diretriz são contrárias às suas expectativas ou até mesmo contrárias à sua experiência.
Se eu não sugeri que você mudasse seu estilo de codificação de alguma forma, falhei!
Por favor, tente verificar ou refutar as regras desta diretriz. Em particular, eu realmente gostaria que algumas das regras propostas fossem apoiadas por medições e exemplos melhores.
É uma regra geral de desenvolvimento de software criar aplicativos que sejam legíveis, fáceis de manter e escaláveis. Isso nem sempre é verdade, mas almejamos esse objetivo.
Os padrões de código são ferramentas que ajudam a construir aplicações com os princípios da tríade mencionados acima. Aqui estão alguns dos benefícios fornecidos pelo estabelecimento de um padrão de desenvolvimento consistente:
️ Aviso: Este é um documento vivo em constante melhoria. Comentários e sugestões de melhorias são bem-vindos. Pretendo modificar e ampliar este documento à medida que nossa compreensão melhorar e a linguagem do conjunto de bibliotecas disponíveis evoluir.
| Nome | Convenção | Exemplo de código |
|---|---|---|
| nome de variável única | caso_cobra | age: int = 100 |
| nome da variável composta | caso_cobra | first_name: str = "Akira" |
| nome constante | CONST | CPU: number = 8 |
| nome constante composto | CONST | MAX_NUMBER: number = 100 |
| nome da enumeração | Caso Pascal | class Color(Enum): RED = 1 GREEN = 2 |
| nome da função | caso_cobra | def main() |
| função com parâmetros | caso_cobra | def calculate(n1: int, n2: int) |
| função com tipo de retorno | caso_cobra | def calculate(n1: int, n2: int) -> int: |
| nome da função composta | caso_cobra | def add_two_numbers(n1: int, n2: int) -> int: |
| nome da classe | Caso Pascal | class Base |
| nome da classe composta | Caso Pascal | class MyClass |
| interfaces | Caso Pascal | class IUser(ABC) |
| fundição | padrão | age: int = int(100) |
| lista | camelCase | myList: list[int] = [1,2,3] |
| tupla | camelCase | myTuple: tuple[int] = (1,2,3) |
| definir | caso_cobra | my_set: set[int] = {1,2,3} |
| dicionário | caso_cobra | my_dictionary: dict = {"name": "John", "age": 100} |
| dicas de vários tipos | caso_cobra | var_a: Union[int, str] |
Propusemos usar o Google Doc Style para documentação Python, pois é o mais fácil de ler e entender. O guia de estilo do Google também é muito popular e amplamente utilizado na comunidade Python.
def add_binary ( a : int , b : int ) -> int :
"""
Returns the sum of two decimal numbers in binary format.
Parameters:
a (int): First number to add
b (int): Second number to add
Returns:
binary (int): Binary int of the sum of a and b
"""
binary_sum = bin ( a + b )[ 2 :]
return int ( binary_sum )A dica de tipo é uma solução formal para indicar estaticamente o tipo de valor.
Exemplo:
def addBinary(a: int, b: int)-> int:
...
Nesta função acima, está explícito que a função espera pelo valor int nas variáveis a e b e retorna o valor int .
Verifique este link: Documentação oficial de digitação em Python
Mas o python não é uma linguagem não digitada? Sim, não é. Se você passar algum valor diferente de int , funciona.
Como verificar o tipo atingido em Python?
Você deve usar a biblioteca mypy .
Mypy é um verificador de tipo estático opcional para Python que visa combinar os benefícios da digitação dinâmica (ou "duck") e da digitação estática. (Fonte: Documentação Oficial)
pip install mypy
mypy mycode.py
A ideia de usar linter para python é fazer cumprir as diretrizes de codificação propostas neste documento. Usarei o Pré-commit.
pip install pre-commit
Configuração básica:
.pre-commit-config.yml para salvar configurações de pré-commitNeste exemplo abaixo o script executará estas etapas:
Exemplo:
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v2.3.0
hooks:
- id: check-yaml
- id: end-of-file-fixer
- id: trailing-whitespace
- id: check-json
- id: detect-private-key
- repo: https://github.com/PyCQA/isort
rev: 5.12.0
hooks:
- id: isort
- repo: https://github.com/psf/black
rev: 22.12.0
hooks:
- id: black
language_version: python3.10
- repo: https://github.com/charliermarsh/ruff-pre-commit
rev: 'v0.0.260'
hooks:
- id: ruff
pyproject.toml para salvar as configurações dos executores de pré-commitExemplo:
[tool.black]
line-length = 80
target-version = ['py310']
include = '.pyi?$'
[tool.isort]
line_length = 79
multi_line_output = 3
include_trailing_comma = true
force_grid_wrap = 0
use_parentheses = true
ensure_newline_before_comments = true
Após essas configurações, toda vez que você fizer um commit, o pré-commit será executado
Pré-comprometer a documentação oficial
O framework proposto para testes é o pytest. É também uma estrutura de teste muito popular para Python.
tests : pytest
pytest --cov . 
Para mais comandos pytest siga a documentação oficial aqui pytest
Aqui está um exemplo de definição de função para um teste:
Depois de criar sua função conforme mostrado no exemplo abaixo: 
Você pode criar seu teste de unidade seguindo estas etapas:
test_ no nome da função.
Para iniciar um novo projeto você pode clonar o projeto usando o seguinte comando:
git clone https://github.com/rsaz/python-project-templateAqui está uma estrutura padrão proposta para o projeto.
A estrutura do projeto é baseada no seguinte:
| Pasta/Arquivo | Descrição |
|---|---|
| utilitários | Scripts PowerShell que permitem criar, ativar, desativar e excluir ambientes, bem como atualizar e criar dependências |
| .vscode | Configuração específica do editor |
| fonte | Pasta de origem principal do projeto |
| teste | Pasta que contém todos os testes unitários do aplicativo |
| venv | Ambiente virtual Python |
| .pylintrc | Arquivo de configuração para analisador de código estático pylint para Python |
| pytest.ini | Arquivo de configuração para pytest |
| LICENÇA.txt | Termos de licença do projeto |
| README.md | Detalhes do projeto |
| requisitos.txt | Dependências do projeto |
| setup.cfg e setup.py | Configuração inicial do projeto |
