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

Tópico	Regra da frota
Async	Sem I/O bloqueante em `async def` sem `to_thread`
SQL	Consultas parametrizadas; ORM preferido
Logging	structlog JSON; sem f-string na mensagem de log
Testes	pytest; fixtures em vez de estado global
Config	pydantic-settings; sem `os.environ` bruto espalhado

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

Alternativa	Usar Quando	Não Usar Quando
Apenas Black (sem Ruff)	Legado	Novo na frota (Ruff substitui ambos)
mypy estrito em todo o repositório	Greenfield pequeno	Monólito legado grande
Guia de estilo do Google verbatim	Necessidade de referência externa	Frota tem layout customizado
Sem padrões	Encerramento iminente	Frota ativa multi-squad

FAQs

PEP 8 vs guia da frota?

Linha de base PEP 8; a frota adiciona regras de layout, tipagem, async, segurança.

Comprimento da linha 88 ou 100?

Esta frota usa 100; escolha um para toda a organização.

Exceções do Django?

Permitir imports do Django nas camadas apps/ e services/ por ADR do template Django.

Padrões de Notebook?

Notebooks não estão no caminho de produção; código promovido deve passar no mesmo lint em módulos.

Aceitar código não tipado?

Sim; novos módulos tipados; portão de caminho alterado em CI.

Quem atualiza os padrões?

Guilda de plataforma trimestralmente; RFC para mudanças controversas.

fmt ao salvar?

Recomendado; CI é a fonte da verdade.

Código gerado por terceiros?

Excluir em ruff por arquivo; documentar caminhos.

Estilo de Docstring?

Estilo Google ou NumPy uma escolha; opcionalmente aplicado em código novo.

Link para o artigo PEP 8?

PEP 8 & Referência de Estilo.

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

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

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

Tópico	Regra da frota
Async	Sem I/O bloqueante em `async def` sem `to_thread`
SQL	Consultas parametrizadas; ORM preferido
Logging	structlog JSON; sem f-string na mensagem de log
Testes	pytest; fixtures em vez de estado global
Config	pydantic-settings; sem `os.environ` bruto espalhado

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

Alternativa	Usar Quando	Não Usar Quando
Apenas Black (sem Ruff)	Legado	Novo na frota (Ruff substitui ambos)
mypy estrito em todo o repositório	Greenfield pequeno	Monólito legado grande
Guia de estilo do Google verbatim	Necessidade de referência externa	Frota tem layout customizado
Sem padrões	Encerramento iminente	Frota ativa multi-squad

FAQs

PEP 8 vs guia da frota?

Linha de base PEP 8; a frota adiciona regras de layout, tipagem, async, segurança.

Comprimento da linha 88 ou 100?

Esta frota usa 100; escolha um para toda a organização.

Exceções do Django?

Permitir imports do Django nas camadas apps/ e services/ por ADR do template Django.

Padrões de Notebook?

Notebooks não estão no caminho de produção; código promovido deve passar no mesmo lint em módulos.

Aceitar código não tipado?

Sim; novos módulos tipados; portão de caminho alterado em CI.

Quem atualiza os padrões?

Guilda de plataforma trimestralmente; RFC para mudanças controversas.

fmt ao salvar?

Recomendado; CI é a fonte da verdade.

Código gerado por terceiros?

Excluir em ruff por arquivo; documentar caminhos.

Estilo de Docstring?

Estilo Google ou NumPy uma escolha; opcionalmente aplicado em código novo.

Link para o artigo PEP 8?

PEP 8 & Referência de Estilo.

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

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

Buscar na documentação

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