Buenas Prácticas de Sugerencias de Tipos

Los tipos deben reducir incidentes sin ahogar al equipo en formalidades. Estas reglas enfocan el esfuerzo donde el análisis estático previene errores reales en producción.

Cómo Usar Esta Lista

• Aplica a todos los módulos nuevos y al código modificado en la revisión.
• Combina con mypy/pyright CI en paquetes tipados.
• Revisa cuando el recuento de Any crezca o las anulaciones estrictas se multipliquen.
• Incorpora a los juniors con Fundamentos de Sugerencias de Tipos y luego con esta lista de verificación.

A - Dónde Escribir Tipos

• Tipa todas las firmas de funciones públicas en el código de la aplicación. Ayudantes privados cuando no sean obvios.
• Tipa primero los límites HTTP/CLI/configuración. Modelos Pydantic 2 para payloads de FastAPI/Django REST.
• Usa Protocolos para dependencias inyectadas (almacenamiento, reloj, notificador). Dobles de prueba sin herencia.
• Anota el contenido de los contenedores: list[str], no list sin formato. Los genéricos sin formato anulan la comprobación.
• Detente en bucles internos calientes a menos que se demuestren errores. Perfila antes de tipar exhaustivamente los kernels de numpy.

B - Sintaxis y Estilo

• Usa la sintaxis de unión X | Y en Python 3.10+. Consistente con la base de código 3.14.
• Usa tipos de collections.abc en parámetros (Sequence, Mapping). Acepta entradas de solo lectura más amplias.
• Prefiere TypedDict/NamedTuple para filas JSON; dataclass para objetos de dominio. Coincide con la forma en tiempo de ejecución.
• Usa Literal y StrEnum para conjuntos fijos de cadenas. Previene errores tipográficos en el momento de la comprobación.
• Evita Any - usa object cuando sea verdaderamente desconocido y luego refina. Rastrea Any con una regla de linting cuando sea posible.

C - Herramientas y CI

• Ejecuta mypy o pyright en CI en paquetes tipados. Bloquea regresiones en módulos fusionados.
• Instala stubs types-* para dependencias sin tipar. requests, pyyaml, etc.
• Habilita warn_unused_ignores y warn_return_any. Limpia las ignoraciones obsoletas rápidamente.
• Usa anulaciones de mypy por paquete, no ignore_errors global. Cuarentena con fechas de finalización.
• Mantén ruff 0.9+ separado de la comprobación de tipos. El formateador/linter no reemplaza a mypy.

D - Tiempo de Ejecución vs. Estático

• Recuerda que las sugerencias no son validación en tiempo de ejecución. Usa Pydantic/isinstance en los límites de confianza.
• No confíes en typing.cast para arreglar la lógica. cast solo silencia el verificador.
• Usa el refinamiento isinstance / match después de comprobaciones opcionales. Patrón if x is not None.
• Valida el JSON externo antes de tratarlo como forma TypedDict. Primero esquema o Pydantic.
• Documenta cuándo type: ignore es inevitable con el código de error y el enlace del ticket.

E - Higiene de Tipado Gradual

• Tipa el código nuevo al 100%; el legado sigue la estrategia gradual. Ver artículo sobre tipado gradual.
• Reduce los módulos heredados en cuarentena con el tiempo. ignore_errors debe tener propietario y fecha.
• Prefiere genéricos (TypeVar) cuando la utilidad preserve los tipos de entrada. No Any de entrada/salida.
• Usa @overload con moderación para dependencias de firma reales. No para sugerencias cosméticas.
• Revisa la elección de Protocolo/ABC en los documentos de diseño. Consistencia estructural vs. nominal.

Preguntas Frecuentes

Relacionado

• Fundamentos de Sugerencias de Tipos - recorrido de sintaxis
• Estrategia de Tipado Gradual - implementación en sistemas existentes
• Configuración de mypy y pyright - configuración
• Buenas Prácticas Fundamentales de Python - hábitos generales

Versiones de la pila: Esta página fue escrita para Python 3.14.0 (3.14 estable, 3.13 de mantenimiento), 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+.