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 Any o API pública sin tipificar
• Hito de tipificación gradual en un servicio brownfield
• Preparación de una biblioteca para consumidores de PyPI

Entradas

Salidas

• Funciones públicas y atributos de clase anotados
• pyproject.toml [tool.mypy] o [tool.pyright]
• Importaciones TYPE_CHECKING para dependencias circulares
• Auditoría de # type: ignore solo con referencias de tickets cuando sea inevitable
• uv run mypy src/package limpio en el ámbito definido

Barreras de Protección

1. API pública completamente tipificada antes que los ayudantes internos.
2. No hay definiciones sin tipificar en código nuevo - def foo(x: int) -> str.
3. Preferir Protocol sobre ABC para tipificación estructural.
4. No silenciar con ignore genérico - reducir con type: ignore[arg-type] + comentario.
5. Ejecutar el verificador en CI en rutas de diferencia - expandir el ámbito a lo largo de los sprints.
6. 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 -q

Ejemplo 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

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+.