Habilidad de Sugerencias de Tipo
Añadir y refinar anotaciones de tipo: una Habilidad de Agente para la tipificación estática de Python 3.14.
Qué Hace Esta Habilidad
Revisa módulos y añade tipos: firmas de funciones, TypedDict, Protocol, límites de TypeVar, reducción con assert isinstance, corrige fugas de Any, configura mypy o pyright en pyproject.toml, y habilita una puerta de control de CI en las rutas modificadas.
Cuándo Invocar
- Nuevo paquete antes del primer lanzamiento
- PR que introduce
Anyo API pública sin tipificar - Hito de tipificación gradual en un servicio brownfield
- Preparación de una biblioteca para consumidores de PyPI
Entradas
| Entrada | Por qué |
|---|---|
| Checker | Estándar del equipo mypy vs pyright |
| Estrictez | strict por módulo vs repositorio completo |
| Superficie de API pública | __all__ y nombres exportados primero |
| Stubs de terceros | paquetes types-* necesarios |
| Django/FastAPI | diferencias de configuración de plugins |
Salidas
- Funciones públicas y atributos de clase anotados
pyproject.toml[tool.mypy]o[tool.pyright]- Importaciones
TYPE_CHECKINGpara dependencias circulares - Auditoría de
# type: ignoresolo con referencias de tickets cuando sea inevitable uv run mypy src/packagelimpio en el ámbito definido
Barreras de Protección
- API pública completamente tipificada antes que los ayudantes internos.
- No hay definiciones sin tipificar en código nuevo -
def foo(x: int) -> str. - Preferir Protocol sobre ABC para tipificación estructural.
- No silenciar con ignore genérico - reducir con
type: ignore[arg-type]+ comentario. - Ejecutar el verificador en CI en rutas de diferencia - expandir el ámbito a lo largo de los sprints.
- Coincidir con la validación en tiempo de ejecución - los modelos Pydantic se alinean con TypedDict donde se comparten.
Receta
uv sync --extra dev
uv run mypy src/myservice
uv run pyright src/myservice # si pyright es el estándar
uv run pytest -qEjemplo de Trabajo
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()Preguntas Frecuentes
¿mypy o pyright?
pyright es más rápido en editores; mypy tiene un ecosistema de plugins maduro - elige uno por repositorio.
¿Modelos Django tipificados?
Usa django-stubs en plugins de mypy - la habilidad documenta dependencias adicionales.
Relacionado
- Conceptos Básicos de Type Hints - fundamentos
- Configuración de mypy y pyright - configuración
- Estrategia de Tipificación Gradual - implementación
- Protocolos y Tipificación Estructural - patrones
Versiones de Stack: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 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+, y uv 0.6+.