Skill de Type Hinting
Adicionando e aprimorando anotações de tipo - uma Skill de Agente para tipagem estática em Python 3.14.
O Que Esta Skill Faz
Revisa módulos e adiciona tipos: assinaturas de função, TypedDict, Protocol, limites de TypeVar, estreitamento de assert isinstance, corrige vazamento de Any, configura mypy ou pyright em pyproject.toml e habilita um gate de CI nos caminhos alterados.
Quando Invocar
- Novo pacote antes do primeiro lançamento
- PR introduzindo
Anyou API pública sem tipo - Marco de tipagem gradual em serviço brownfield
- Preparando biblioteca para consumidores do PyPI
Entradas
| Entrada | Por quê |
|---|---|
| Verificador | mypy vs padrão da equipe pyright |
| Rigor | strict por módulo vs repositório inteiro |
| Superfície da API pública | __all__ e nomes exportados primeiro |
| Stubs de terceiros | pacotes types-* necessários |
| Django/FastAPI | diferenças de configuração de plugin |
Saídas
- Funções públicas e atributos de classe anotados
pyproject.toml[tool.mypy]ou[tool.pyright]- Importações
TYPE_CHECKINGpara dependências circulares - Auditoria de
# type: ignorecom referências de ticket apenas quando inevitável uv run mypy src/packagelimpo no escopo
Guardrails
- API pública totalmente tipada antes de auxiliares internos.
- Sem definições sem tipo em código novo -
def foo(x: int) -> str. - Preferir Protocol sobre ABC para tipagem estrutural.
- Não silenciar com ignore nu - estreitar com
type: ignore[arg-type]+ comentário. - Executar verificador em CI em caminhos alterados - expandir escopo ao longo de sprints.
- Corresponder à validação em tempo de execução - modelos Pydantic alinhados com TypedDict onde compartilhado.
Receita
uv sync --extra dev
uv run mypy src/myservice
uv run pyright src/myservice # se pyright for o padrão
uv run pytest -qExemplo de Trabalho
from collections.abc import Sequence
from typing import Protocol
class SupportsClose(Protocol):
def close(self) -> None: ...
def shutdown_all(resources: Sequence[SupportsClose]) -> None:
for r in resources:
r.close()FAQs
mypy ou pyright?
pyright é mais rápido em editores; mypy tem um ecossistema de plugins maduro - escolha um por repositório.
Modelos Django tipados?
Use django-stubs em plugins mypy - a skill documenta dependências extras.
Relacionados
- Noções Básicas de Type Hints - fundamentos
- Configuração de mypy e pyright - configuração
- Estratégia de Tipagem Gradual - rollout
- Protocolos e Tipagem Estrutural - padrões
Versões de Stack: Esta página foi escrita para Python 3.14.0 (stable 3.14, maintenance 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+.