Convenções e Guia de Estilo
Idiomas Python acordados para a equipe - formatação, nomenclatura, tipagem, erros e commits - aplicados pelo ruff em CI e documentados aqui para que as revisões se concentrem no design, não no gosto.
//
Busque em todas as páginas da documentação
Idiomas Python acordados para a equipe - formatação, nomenclatura, tipagem, erros e commits - aplicados pelo ruff em CI e documentados aqui para que as revisões se concentrem no design, não no gosto.
from __future__ import annotations
from pathlib import Path
DATA_DIR = Path(__file__).resolve().parent / "data"
def load_config(path: Path) -> dict[str, str]:
try:
text = path.read_text(encoding="utf-8")
except OSError as exc:
raise ConfigError(f"não é possível ler {path}") from exc
return parse_env(text)Quando usar isso:
# modules/billing/services/tax.py
from decimal import Decimal
from billing.domain.models import LineItem
from billing.settings import Settings
class TaxService:
def __init__(self, settings: Settings) -> None:
self._rate = Decimal(settings.vat_rate)
def compute(self, items: list[LineItem]) -> Decimal:
subtotal = sum((i.unit_price * i.quantity for i in items), start=Decimal("0"))
return (subtotal * self._rate).quantize(Decimal("0.01"))Mensagem de commit:
feat(billing): aplica IVA a itens de linha da UE [BILL-91]
Usa Decimal para matemática monetária. Adiciona teste de regressão para itens de quantidade zero.O que isso demonstra:
from __future__ import annotations para referências futurasDecimal para moeda - não float_rate; métodos públicos tipadospyproject.toml.snake_case, classes PascalCase, constantes SCREAMING_SNAKE.from module import * de wildcard.| Tópico | Convenção |
|---|---|
| Strings | f-strings preferenciais |
| Caminhos | pathlib.Path em vez de os.path.join |
| Exceções | Tipos específicos; raise ... from exc |
| Logging | logging.getLogger(__name__) em vez de print |
| Async | Sem IO bloqueante em rotas async def |
| Dinheiro | Decimal ou centavos inteiros |
# trecho de pyproject.toml
[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM"]
ignore = ["E501"] # se o formatador lida com o comprimento da linhauv sync fixa as versões das ferramentas.# type: ignore[arg-type] # BILL-99.0.1 + 0.2. Correção: Decimal ou centavos inteiros.except: nu - Mascara KeyboardInterrupt. Correção: capturar no mínimo Exception, preferencialmente tipos específicos.| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Documento de regras Python para toda a organização | Padrões entre equipes | Necessita de substituições específicas do serviço |
| Apenas ruff automatizado | Equipe pequena | Necessita de exemplos em texto para onboarding |
| Guia de estilo Python do Google | Referência externa | Conflitos com a configuração do ruff |
| Sem guia de estilo | Nunca | Revisões de detalhes sem fim |
ruff format quando o ruff for adotado - uma ferramenta; não execute ambos.
O formatador ruff escolhe consistentemente - não lute manualmente na revisão.
API pública e locais não óbvias - não name = "ada" em funções pequenas.
Módulos/classes/funções públicas sim - estilo Google ou numpy conforme README.
Escolha um em pyproject.toml - corresponda às expectativas do formatador e do revisor.
Absolutos from billing.domain import models em aplicativos - relativos apenas dentro de pacotes pequenos por ADR.
StrEnum ou Literal para conjuntos pequenos e fechados - documentar na seção de type-hints.
test_<comportamento>_quando_<condição> - saída de falha legível.
feat, fix, chore, docs, refactor, test - corresponder à automação de changelog, se houver.
ADR ou comentário inline com motivo - não um único caso silencioso em um PR.
Versões de Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026