50 Regras de Python que Todo Especialista Deve Seguir

Uma lista de verificação mestre de hábitos que separam o Python de produção do código de tutorial. Agrupadas por domínio; cada regra é acionável e aplicável com ferramentas onde indicado.

Receita

Analise esta lista trimestralmente. Ative as regras do ruff/mypy que automatizam cada item "aplicável".

Quando usar isso:

• Integração de desenvolvedores Python seniores
• Revisões de arquitetura e bases para auditoria de código
• Configuração de políticas de lint e CI da equipe

Referência de Regras de Python

Mergulho Profundo

Estilo e Legibilidade (1-10)

1. Siga a PEP 8 - linhas de 88 caracteres com ruff format; sem debates manuais de estilo.
2. Use nomes descritivos - total_fatura, não x ou tmp.
3. Prefira f-strings - f"{nome}" em vez de "{}".format() e formatação %.
4. Ordem de importação: stdlib, terceiros, próprios - deixe o ruff isort impor.
5. Uma instrução por linha - sem cadeias de ponto e vírgula ou if foo: bar() compostos.
6. Explícito é melhor que implícito - sem números mágicos; use constantes nomeadas.
7. Plano é melhor que aninhado - retornos antecipados em vez de indentação de 5 níveis.
8. Use pathlib.Path - não os.path.join para código novo.
9. Use enum.Enum - para conjuntos fixos de constantes, não literais de string.
10. Docstrings em APIs públicas - estilo Google ou NumPy; mínimo de uma linha.

Tipos e Contratos (11-20)

11. Anote tipos de todas as funções públicas - parâmetros e tipos de retorno.
12. Execute mypy ou pyright em CI - tipos são contratos, não sugestões.
13. Use X | None, não Optional[X] - sintaxe de união do Python 3.14.
14. Prefira list[str] em vez de List[str] - genéricos embutidos (PEP 585).
15. Use TypedDict ou Pydantic - para dicionários estruturados, não dict brutos.
16. Estreite tipos com isinstance - não verificações type() nuas.
17. Use Protocol para duck typing - subtipagem estrutural em vez de ABCs quando apropriado.
18. Marque any intencional com comentários - # type: ignore precisa de um motivo.
19. Dataclasses para contêineres de dados - frozen=True quando imutável.
20. Pydantic 2 para limites de validação - entrada HTTP, configuração, dados externos.

Estrutura e Módulos (21-30)

21. Layout src/ - pacote instalável e testável como os consumidores o veem.
22. Uma responsabilidade por módulo - arquivos com menos de 300 linhas; divida quando maiores.
23. Sem importações circulares - reestruture ou use importações preguiçosas TYPE_CHECKING.
24. Importações absolutas - from myapp.services import billing, não cadeias de pontos relativas em bibliotecas.
25. __all__ explícito - para a superfície da API pública do pacote.
26. Sem lógica em __init__.py - apenas reexportações; mantenha-o fino.
27. Injeção de dependência em vez de globais - passe dependências como parâmetros ou fixtures.
28. Configuração via ambiente + pydantic-settings - não segredos ou caminhos codificados.
29. Separe o domínio de I/O - funções puras testáveis sem mocks.
30. Use pyproject.toml - configuração única para dependências, ferramentas e build.

Erros e Testes (31-40)

31. Exceções específicas - raise ValueError("pct deve ser 0-100"), não raise Exception nu.
32. Nunca engula exceções - except: pass é quase sempre errado.
33. Use encadeamento de exceções - raise NewError(...) from original.
34. Gerenciadores de contexto para recursos - with open(...) e @contextmanager.
35. pytest para todos os testes - sem boilerplate unittest para código novo.
36. Um comportamento por teste - nomes descritivos: test_discount_over_100_raises.
37. Mock nas fronteiras - HTTP, DB, sistema de arquivos; não lógica interna.
38. Piso de cobertura de 80% - cobertura de ramificação em módulos críticos.
39. Sem print em bibliotecas - use logging com logger em nível de módulo.
40. Logging estruturado em produção - logs JSON com IDs de correlação.

Segurança e Operações (41-50)

41. Nunca comite segredos - variáveis de ambiente, gerenciadores de segredos, .env ignorado pelo git.
42. Fixe dependências - lockfile commitado; uv sync --frozen em CI.
43. Valide toda entrada externa - Pydantic nas fronteiras da API.
44. Use o módulo secrets - não random para tokens e senhas.
45. SQL parametrizado - nunca use f-string em consultas SQL.
46. Mantenha o Python atualizado - patches de segurança em até 30 dias após o lançamento.
47. Execute pip-audit em CI - varredura semanal de vulnerabilidades de dependência.
48. Menor privilégio - permissões mínimas de IAM, DB e acesso a arquivos.
49. Desligamento gracioso - manipule SIGTERM; descarregue logs e feche conexões.
50. Meça antes de otimizar - perfil primeiro; legibilidade como padrão em vez de velocidade.

Armadilhas

• Tratar regras como dogma - o contexto importa; documente exceções em ADRs. Correção: regras guiam padrões, não absolutos.
• Ativar todas as regras do ruff no primeiro dia - fadiga de alertas. Correção: adote incrementalmente por grupo acima.
• Tipos sem testes - mypy verde, mas comportamento incorreto. Correção: combine tipos com cobertura pytest.
• 50 regras, zero automação - regras decaem sem CI. Correção: mapeie regras para gates do ruff/mypy/pre-commit.
• Aplicar regras de biblioteca a scripts - scripts únicos podem relaxar regras de estrutura. Correção: escopo das regras por tipo de pacote.

Alternativas

FAQs

Relacionados

• PEP 8 e Referência de Estilo - detalhes de estilo
• 30 Regras de Segurança para Python - mergulho profundo em segurança
• Decisões de Arquitetura Python - escolhas estruturais
• Melhores Práticas de Linting e Formatação - aplicação de ferramentas

Versões de Stack: Esta página foi escrita para Python 3.14.0, 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+.