Estilo e Documentação de Código Python

Um estilo de código consistente e documentação clara tornam bases de código fáceis de manter e colaborativas. Esta habilidade abrange ferramentas modernas de Python, convenções de nomenclatura e padrões de documentação.

Quando Usar Esta Habilidade

• Configurar linting e formatação para um novo projeto
• Escrever ou revisar docstrings
• Estabelecer padrões de codificação em equipe
• Configurar ruff, mypy ou pyright
• Revisar código para consistência de estilo
• Criar documentação de projeto

Conceitos Principais

1. Formatação Automatizada

Deixe ferramentas lidarem com debates de formatação. Configure uma vez, aplique automaticamente.

2. Nomenclatura Consistente

Siga as convenções do PEP 8 com nomes significativos e descritivos.

3. Documentação como Código

Docstrings devem ser mantidas junto com o código que descrevem.

4. Anotações de Tipo

Código Python moderno deve incluir dicas de tipo para todas as APIs públicas.

Início Rápido

# Install modern tooling
pip install ruff mypy

# Configure in pyproject.toml
[tool.ruff]
line-length = 120
target-version = "py312"  # Adjust based on your project's minimum Python version

[tool.mypy]
strict = true

Padrões Fundamentais

Padrão 1: Ferramentas Modernas de Python

Use ruff como um linter e formatador tudo-em-um. Ele substitui flake8, isort e black por uma única ferramenta rápida.

# pyproject.toml
[tool.ruff]
line-length = 120
target-version = "py312"  # Adjust based on your project's minimum Python version

[tool.ruff.lint]
select = [
    "E",    # pycodestyle errors
    "W",    # pycodestyle warnings
    "F",    # pyflakes
    "I",    # isort
    "B",    # flake8-bugbear
    "C4",   # flake8-comprehensions
    "UP",   # pyupgrade
    "SIM",  # flake8-simplify
]
ignore = ["E501"]  # Line length handled by formatter

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

Execute com:

ruff check --fix .  # Lint and auto-fix
ruff format .       # Format code

Padrão 2: Configuração de Verificação de Tipo

Configure verificação de tipo rigorosa para código de produção.

# pyproject.toml
[tool.mypy]
python_version = "3.12"
strict = true
warn_return_any = true
warn_unused_ignores = true
disallow_untyped_defs = true
disallow_incomplete_defs = true

[[tool.mypy.overrides]]
module = "tests.*"
disallow_untyped_defs = false

Alternativa: Use pyright para verificação mais rápida.

[tool.pyright]
pythonVersion = "3.12"
typeCheckingMode = "strict"

Padrão 3: Convenções de Nomenclatura

Siga o PEP 8 com ênfase na clareza sobre a brevidade.

Arquivos e Módulos:

# Good: Descriptive snake_case
user_repository.py
order_processing.py
http_client.py

# Avoid: Abbreviations
usr_repo.py
ord_proc.py
http_cli.py

Classes e Funções:

# Classes: PascalCase
class UserRepository:
    pass

class HTTPClientFactory:  # Acronyms stay uppercase
    pass

# Functions and variables: snake_case
def get_user_by_email(email: str) -> User | None:
    retry_count = 3
    max_connections = 100

Constantes:

# Module-level constants: SCREAMING_SNAKE_CASE
MAX_RETRY_ATTEMPTS = 3
DEFAULT_TIMEOUT_SECONDS = 30
API_BASE_URL = "https://api.example.com"

Padrão 4: Organização de Importações

Agrupe importações em uma ordem consistente: biblioteca padrão, terceiros, local.

# Standard library
import os
from collections.abc import Callable
from typing import Any

# Third-party packages
import httpx
from pydantic import BaseModel
from sqlalchemy import Column

# Local imports
from myproject.models import User
from myproject.services import UserService

Use importações absolutas exclusivamente:

# Preferred
from myproject.utils import retry_decorator

# Avoid relative imports
from ..utils import retry_decorator

Padrões Avançados

Padrão 5: Docstrings Estilo Google

Escreva docstrings para todas as classes, métodos e funções públicas.

Função Simples:

def get_user(user_id: str) -> User:
    """Retrieve a user by their unique identifier."""
    ...

Função Complexa:

def process_batch(
    items: list[Item],
    max_workers: int = 4,
    on_progress: Callable[[int, int], None] | None = None,
) -> BatchResult:
    """Processa itens concorrentemente usando um pool de workers.

    Processa cada item no lote usando o número configurado de
    workers. O progresso pode ser monitorado através do callback opcional.

    Args:
        items: Os itens a serem processados. Não pode estar vazio.
        max_workers: Número máximo de workers concorrentes. O padrão é 4.

…