Fundamentos de Python: Melhores Práticas

Hábitos essenciais que mantêm o código Python legível, correto e de fácil manutenção antes de você recorrer a frameworks ou ferramentas de dados. Trate isso como uma lista de verificação de integração para cada novo módulo ou repositório.

Como Usar Esta Lista

• Revise ao iniciar um novo pacote ou integrar um novo membro na equipe.
• Aplique durante a revisão de código para arquivos que tocam nos fundamentos (I/O, imports, funções).
• Releia após incidentes originados em mutabilidade, codificação ou deriva de ambiente.
• Emparelhe com CI de ruff/mypy para que as regras se tornem automáticas, não aspiracionais.

A - Ambiente e Ferramentas

• Crie um ambiente virtual antes de instalar pacotes de terceiros. Nunca polua o Python do sistema (PEP 668).
• Fixe dependências com pyproject.toml e um lockfile (uv.lock). CI e clones reproduzíveis.
• Use recursos do Python 3.14+ apenas quando o pin do runtime permitir. Documente requires-python em pyproject.toml.
• Execute ruff check e ruff format em todo PR. Feedback rápido de estilo e linting.
• Habilite mypy ou pyright incrementalmente em novos módulos. Tipos trazem retorno nas fronteiras da API.

B - Estilo de Código e Legibilidade

• Siga a nomenclatura PEP 8: funções snake_case, classes PascalCase, constantes UPPER.
• Prefira f-strings em vez de formatação % e format() para código novo. Mais claro e rápido.
• Use pathlib.Path em vez de manipulação de strings com os.path. Junções seguras multiplataforma.
• Mantenha funções curtas com uma única responsabilidade clara. Extraia quando a aninhamento exceder dois níveis.
• Escreva docstrings em módulos, classes e funções públicas. Resumo de uma linha mais parâmetros quando não óbvio.

C - Dados e Correção

• Nunca use argumentos padrão mutáveis (def f(x=[])). Use None e atribua internamente.
• Use Decimal para dinheiro, não float binário. Evite surpresas de 0.1 + 0.2 em faturamento.
• Especifique encoding="utf-8" em todo I/O de arquivo de texto. Evite bugs padrão da plataforma.
• Copie estruturas aninhadas com copy.deepcopy quando a independência for importante. Cópias rasas compartilham listas internas.
• Use isinstance para verificações de tipo, não type(x) is Cls em subclasses. Amigável à polimorfismo.

D - Fluxo de Controle e APIs

• Prefira compreensões ou geradores em vez de loops manuais de append ao transformar sequências. Legível e frequentemente mais rápido.
• Use match/case para ramificação estrutural em dicionários e dataclasses. Mais limpo que cadeias profundas de if.
• Exponha opções somente por palavra-chave após * em APIs públicas. Evita chamadas ambíguas.
• Proteja scripts com if __name__ == "__main__":. Módulos importáveis sem efeitos colaterais.
• Execute pacotes com python -m package.module. Importações relativas e __package__ corretos.

E - Imports e Layout

• Use imports absolutos em código de aplicação (from myapp.utils import x). Mais claro que relativos em árvores grandes.
• Quebre importações circulares com imports preguiçosos ou módulos types compartilhados. Falhe cedo em tempo de design, quando possível.
• Evite sombrear nomes de módulos da stdlib (json.py, types.py). Quebra imports misteriosamente.
• Adote o layout src/ para pacotes instaláveis. Evita imports acidentais da raiz do repositório.
• Mantenha efeitos colaterais de tempo de importação mínimos. Sem rede ou banco de dados ao carregar módulos em bibliotecas.

FAQs

Relacionados

• Fundamentos de Python - tour introdutório executável
• Variáveis, Tipos e Tipagem Dinâmica - semântica de referência
• Guia Rápido de Ambientes Virtuais - fluxo de trabalho uv
• Fundamentos de Type Hints - introdução à tipagem estática

Versões da 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+.