Boas Práticas de Padrões Pythonicos
Regras para estrutura Python legível e de fácil manutenção - de EAFP à conexão de dependências.
Como Usar Esta Lista
- Aplique durante revisões de design antes de adicionar novas camadas de abstração.
- Prefira um padrão claro por limite - não misture estilos de dispatch no mesmo módulo.
- Aplique com ruff, mypy/pyright e testes de arquitetura, sempre que possível.
A - Idiomas e Legibilidade
- Prefira EAFP quando o sucesso for comum. Caminhos felizes lineares superam guardas aninhadas; capture exceções específicas.
- Use
withpara pares de aquisição/liberação. Arquivos, locks e transações precisam de desmontagem garantida. - Alcance o dispatch de dict antes que cadeias elif cresçam além de cinco ramificações. Registre plugins explicitamente.
- Nomeie funções de fábrica
coisa_do_env/construir_coisa. Chamadores reconhecem helpers de raiz de composição. - Legibilidade conta mais que esperteza. Se um júnior não consegue rastrear em cinco minutos, simplifique.
B - Estrutura e Acoplamento
- Injete dependências através de construtores. Sem singletons ocultos de
get_db()em métodos de serviço. - Dependa de protocolos, conecte concretos na raiz. O código da aplicação permanece testável e substituível.
- Use objetos nulos para colaboradores opcionais de no-op. Não para dependências de produção necessárias.
- Publique eventos de domínio através de uma interface de barramento. Manipuladores permanecem pequenos; falhas são registradas por manipulador.
- Divida objetos "god" por responsabilidade antes de adicionar o décimo método. Extraia protocolos primeiro.
C - Padrões e Segurança
- Nunca use argumentos padrão mutáveis. Sentinela
Nonemais um novo contêiner dentro da função. - Use sentinelas explícitas quando
Nonefor dado válido. Documente verificaçõesispara objetosUNSET. - Valide builders em
build(), não em setters. Mantenha o estado parcial do builder interno. - Evite I/O e rede no momento da importação. Hooks de inicialização e manipuladores de tempo de vida são donos de efeitos colaterais.
- Capture exceções específicas; nunca
exceptnu. Registre o contexto; re-levante a menos que a supressão seja contratual.
D - Disciplina de Abstração
- Regra de três antes de extrair interfaces. Espere por três duplicações reais, não futuros imaginados.
- Prefira funções e dataclasses a herança profunda. Composição e dispatch cobrem a maioria dos casos Python.
- Substitua a proliferação de flags booleanas por enums ou estratégias. Modos são tipos, não quatro parâmetros
True/False. - Mantenha APIs públicas explícitas -
**kwargsmínimo. TypedDict ou Pydantic em limites HTTP/CLI. - Documente chaves de registro e nomes de eventos válidos.
StrEnumouLiteralpara verificação estática.
E - Revisão e Evolução
- Verifique anti-padrões em módulos de alta rotatividade trimestralmente. Padrões mutáveis e erros engolidos primeiro.
- Um teste de integração por dispatcher/registro. Chaves e tipos desconhecidos falham com mensagens claras.
- Refatore extração por protocolo em PRs pequenos. Facade delega até que os chamadores migrem.
- Combine o padrão com o tamanho do problema. Scripts permanecem simples; serviços recebem injeção e eventos.
- Vincule ADRs ao escolher chamadas de barramento vs diretas. Leitores futuros conhecem o trade-off aceito.
FAQs
Qual é a prática de maior impacto para código novo?
Injeção de construtor mais protocolos - os testes melhoram imediatamente sem frameworks.
Quando devo pular padrões completamente?
Scripts únicos com menos de ~100 linhas: funções simples, sem barramento, sem builder.
Como eu aplico o dispatch de dict?
Módulo de registro central, chaves tipadas como StrEnum e testes que falham em chaves desconhecidas.
Gerenciadores de contexto baseados em classe são obrigatórios?
Não. @contextmanager cobre a maioria dos casos; classes quando o estado de entrada/saída é substancial.
Como isso se relaciona com o PEP 20?
Explícito, legível, plano - estas práticas operacionalizam o Zen de Python na arquitetura.
Todo serviço deve emitir eventos?
Apenas para limites que outros módulos assinam. Etapas internas mantêm chamadas diretas.
Como migrar cadeias elif com segurança?
Introduza um mapeamento de dicionário das ramificações existentes; mantenha elif delegando até que a cobertura corresponda; exclua ramificações.
O FastAPI muda o conselho de DI?
Depends() é injeção de parâmetro nas rotas - mesmo princípio, escopo gerenciado pelo framework por requisição.
Quais regras de lint ajudam mais?
ruff B006 (padrões mutáveis), E722 (except nu) e pyright em implementações de protocolo.
Como eu ensino padrões para juniores?
Comece com Noções Básicas de Padrões Pythonicos, depois revise um anti-padrão por sprint.
Relacionado
- Noções Básicas de Padrões Pythonicos - exemplos práticos
- Anti-Padrões Comuns - erros a evitar
- EAFP vs LBYL - estilo de exceção
- Injeção de Dependência em Python - detalhes de conexão
Versões do 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+.