Melhores Práticas de Dicas de Tipo

Tipos devem reduzir incidentes sem afogar a equipe em cerimônia. Estas regras focam o esforço onde a análise estática previne bugs reais de produção.

Como Usar Esta Lista

• Aplique a todos os novos módulos e código tocado em revisão.
• Emparelhe com CI de mypy/pyright em pacotes tipados.
• Revise quando a contagem de Any crescer ou substituições estritas se multiplicarem.
• Integre juniores com Noções Básicas de Dicas de Tipo e depois com esta lista de verificação.

A - Onde Digitar

• Digite todas as assinaturas de função públicas em código de aplicação. Auxiliares privados quando não óbvios.
• Digite limites HTTP/CLI/configuração primeiro. Modelos Pydantic 2 para payloads FastAPI/Django REST.
• Use Protocolos para dependências injetadas (armazenamento, relógio, notificador). Duplas de teste sem herança.
• Anote conteúdos de contêineres: list[str], não list nu. Genéricos nus derrotam a verificação.
• Pare em loops internos quentes, a menos que bugs sejam comprovados. Perfure antes de digitar kernels numpy exaustivamente.

B - Sintaxe e Estilo

• Use a sintaxe de união X | Y no Python 3.10+. Consistente com a base de código 3.14.
• Use tipos collections.abc em parâmetros (Sequence, Mapping). Aceite entradas mais amplas somente leitura.
• Prefira TypedDict/NamedTuple para linhas JSON; dataclass para objetos de domínio. Corresponda à forma em tempo de execução.
• Use Literal e StrEnum para conjuntos fixos de strings. Previne erros de digitação no momento da verificação.
• Evite Any - use object quando verdadeiramente desconhecido e depois refine. Rastreie Any com regra de lint, se possível.

C - Ferramentas e CI

• Execute mypy ou pyright em CI em pacotes tipados. Bloqueie regressões em módulos mesclados.
• Instale stubs types-* para dependências não tipadas. requests, pyyaml, etc.
• Habilite warn_unused_ignores e warn_return_any. Limpe ignores obsoletos prontamente.
• Use substituições mypy por pacote, não ignore_errors globais. Quarentena com datas de expiração.
• Mantenha ruff 0.9+ separado da verificação de tipo. Formatador/lintador não substitui mypy.

D - Tempo de Execução vs. Estático

• Lembre-se que dicas não são validação em tempo de execução. Use Pydantic/isinstance em limites de confiança.
• Não confie em typing.cast para corrigir a lógica. cast silencia apenas o verificador.
• Use isinstance / match para refinar após verificações opcionais. Padrão if x is not None.
• Valide JSON externo antes de tratá-lo como forma TypedDict. Esquema ou Pydantic primeiro.
• Documente quando type: ignore for inevitável com código de erro e link de ticket.

E - Higiene de Tipagem Gradual

• Digite código novo 100%; legado segue estratégia gradual. Veja o artigo sobre tipagem gradual.
• Reduza módulos legados em quarentena ao longo do tempo. ignore_errors deve ter proprietário e data.
• Prefira genéricos (TypeVar) quando a utilidade preserva os tipos de entrada. Não Any na entrada/saída.
• Use @overload com moderação para dependência real de assinatura. Não para dicas cosméticas.
• Revise a escolha de Protocolo/ABC em documentos de design. Consistência estrutural vs. nominal.

FAQs

Relacionados

• Noções Básicas de Dicas de Tipo - tour de sintaxe
• Estratégia de Tipagem Gradual - implantação em brownfield
• Configuração mypy & pyright - configuração
• Melhores Práticas de Fundamentos Python - hábitos gerais

Versões da Pilha: Esta página foi escrita para Python 3.14.0 (3.14 estável, 3.13 de manutenção), 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+.