Padrões de Codificação e Guias de Estilo

Os padrões Python de toda a frota estendem o PEP 8 com regras de tipagem, layout de projeto, tratamento de erros e expectativas de revisão - aplicados por Ruff 0.9+, pyright em caminhos alterados e templates que novos repositórios copiam.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# pyproject.toml (linha de base da frota)
[tool.ruff]
line-length = 100
target-version = "py314"
select = ["E", "F", "I", "UP", "B", "ASYNC", "S"]
 
[tool.pyright]
pythonVersion = "3.14"
typeCheckingMode = "standard"

src/<package>/
  api/        # Apenas HTTP
  domain/     # sem imports de FastAPI/Django
  infra/      # DB, filas, IO externo

Quando usar isto:

• Inicialização de novo serviço
• Debates de PR repetindo os mesmos argumentos de estilo
• Auditoria de segurança pede consistência
• Checklist de integração

Exemplo de Trabalho

"""domain/orders.py - atende aos padrões da frota."""
from __future__ import annotations
 
from dataclasses import dataclass
from decimal import Decimal
 
 
@dataclass(frozen=True)
class OrderTotal:
    subtotal: Decimal
    tax: Decimal
 
    @property
    def grand_total(self) -> Decimal:
        return self.subtotal + self.tax
 
 
def compute_total(subtotal: Decimal, tax_rate: Decimal) -> OrderTotal:
    tax = (subtotal * tax_rate).quantize(Decimal("0.01"))
    return OrderTotal(subtotal=subtotal, tax=tax)

# api/routes/orders.py - limite fino
from fastapi import APIRouter
from pydantic import BaseModel
 
from domain.orders import compute_total
 
router = APIRouter()
 
 
class TotalRequest(BaseModel):
    subtotal: float
    tax_rate: float
 
 
@router.post("/total")
def total(body: TotalRequest) -> dict[str, float]:
    result = compute_total(body.subtotal, body.tax_rate)
    return {"grand_total": float(result.grand_total)}

O que isto demonstra:

• O módulo de domínio tem tipos e sem imports de framework
• Dinheiro usa Decimal no domínio; float apenas na fronteira HTTP com política explícita de conversão
• O roteador permanece fino; regras de negócio testáveis sem HTTP
• Os padrões se alinham com o layout de referência do SaaS

Mergulho Profundo

Como Funciona

• Automatizar detalhes triviais - Ruff formata + faz lint em CI; humanos revisam o design.
• Tipagem - Funções públicas anotadas; Any requer justificativa em comentário.
• Imports - isort via Ruff; sem imports de estrela em código de produção.
• Erros - Hierarquia de exceções customizada por serviço; sem except genérico.
• Segurança - Regras Bandit/S no Ruff para problemas comuns.

Padrões Além do PEP 8

Notas Python

uv run ruff check .
uv run ruff format --check .
uv run pyright src/

Armadilhas

• 100% perfeição de estilo antes de recursos - A velocidade morre. Correção: Automatizar; aceitar legado com rigor em caminhos alterados.
• Templates de repositório inconsistentes - Cada serviço diferente. Correção: Template interno do Cookiecutter atualizado trimestralmente.
• Decimal em todo lugar no JSON - Dor de serialização. Correção: Política: domínio Decimal, float/str na API com validação.
• Ignorando regras ASYNC - Incidentes depois. Correção: ASYNC na seleção padrão do Ruff.
• Documento de padrões não lido - Link do template de PR e mensagens do linter.

Alternativas

FAQs

Relacionado

• Convenções de Documentação - padrões de docs
• Diretrizes de Contribuição - processo de PR
• Linting & Formatação - ferramentas
• Melhores Práticas de Dicas de Tipo - profundidade de tipagem
• Regras Python - lista de regras

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+.