ty será el mejor, junto con ruff, el poder de rust y python
Recursos
Resumen
MyPy es la herramienta estándar de la industria para la validación estática de tipos en Python, y aprender a usarla te permite detectar errores antes de ejecutar el código. Si trabajas en proyectos que necesitan ser robustos y mantenibles, dominar este análisis de tipos marca la diferencia entre un código frágil y uno confiable.
Esta guía es para desarrolladores de Python que quieren mejorar la calidad de su código y entender cómo leer, interpretar y corregir errores de tipado reales.
Cómo instalo y ejecuto MyPy en mi proyecto
Lo primero es sumar MyPy como dependencia de desarrollo. En el proyecto de Platzi News se instala con uv add --dev, que agrega la herramienta solo a la lista de desarrollo sin contaminar las dependencias de producción.
Una vez instalado, lo ejecutas apuntando a tu carpeta de código:
bash mypy src
Ese comando recorre todos los archivos y te devuelve los errores de tipos que encuentra. En el proyecto de ejemplo se agregaron errores a propósito para ver cómo responde la herramienta.
¿Qué es MyPy en Python? Es una herramienta de validación estática de tipos que analiza tu código sin ejecutarlo y te avisa cuando usas un tipo incorrecto, como pasar un diccionario donde esperas una lista.
Un truco útil: con Alt+click o Command+click sobre el error en la terminal abres directamente el archivo señalado.
Cómo leo e interpreto los errores de tipado
Aquí viene lo interesante, porque la habilidad real no es memorizar errores, sino aprender a leerlos. Los errores pueden cambiar entre versiones del software, así que lo valioso es entender su estructura y resolverlos.
El formato típico es sencillo:
- Primero aparece el nombre del archivo.
- Luego, separado por dos puntos, el número de la línea.
- Después, la descripción del problema.
Algo muy común es que una misma línea tenga varios errores a la vez. Por eso conviene abrir el archivo, limpiar la terminal y atacar un problema por vez.
Qué hago cuando el tipo nunca va a coincidir
El primer caso del proyecto es un dict que nunca se cumplirá, porque la variable article es una lista de artículos definida con un data class en los modelos. Como un data class jamás será un diccionario, la solución es eliminar las líneas que no se usan (URL, desc, title) junto con el if que dependía de ellas. Al volver a correr mypy src, esos errores desaparecen.
Cómo arreglo la librería stubs que no está instalada
Otro error frecuente avisa que la librería stubs no está instalada. Esto pasa porque algunas librerías, como requests, no incluyen su tipado. La solución es instalar un paquete extra que sí trae los tipos:
bash uv add --dev types-requests
¿Qué son los stubs en Python? Son archivos que contienen solo las definiciones de tipos de una librería. Cuando una librería no está tipada, instalas un paquete de stubs como
types-requestspara que MyPy pueda validarla.
Cómo soluciono una incompatibilidad de tipos con Union
Tras instalar los stubs aparece un error nuevo: el argumento params del método get no es compatible con el tipo que espera requests. Al revisar params, la query es un str compatible, pero api_key llega como None, y ahí nace el conflicto.
La solución es tipar la variable de forma explícita como un diccionario cuyas llaves sean str y sus valores sean un str o un int. En la versión clásica se importa la unión:
python from typing import Union
params: dict[str, Union[str, int]] = {...}
Al exigir que los valores solo sean str o entero, el valor que antes era ambiguo se convierte automáticamente en str y el error desaparece.
Por qué Python moderno usa el pipe en vez de Union
En versiones recientes de Python puedes olvidarte de importar Union y usar el pipe directamente, lo que resulta mucho más legible:
python params: dict[str, str | int] = {...}
La lectura es clara: el primer str tipa las llaves, y str | int tipa los valores. Si quitas el int y guardas, MyPy marca de inmediato un error porque max_articles es un entero y ya no sería asignable. Esa es la prueba de que ambos tipos eran necesarios.
Cuándo debo ignorar un error de tipado
No todos los errores se corrigen cambiando el código; algunos se ignoran a propósito. En el archivo de configuración, la línea 34 valida que ciertos parámetros existan en el .env al ejecutar la aplicación, por lo que el error de tipado ahí no aplica.
Para ignorar un error en una línea específica se usa un comentario con type: ignore seguido del nombre del error entre corchetes, en este caso call-arg:
python settings() # type: ignore[call-arg]
¿Cómo ignoro un error de MyPy en una línea? Agregas el comentario
# type: ignore[nombre_del_error]al final de la línea. MyPy comprueba que el error coincida y omite imprimirlo.
Esto funciona porque MyPy no ejecuta el código, solo lo valida contra sus reglas. Aun así, usa estas ignoraciones con cuidado: solo cuando estés completamente seguro de lo que haces.
Por qué conviene corregir en vez de ignorar
Un caso parecido es el error missing_keys, que podrías ignorar pero es mejor resolver. El mensaje indica que join solo acepta str y le estás pasando una lista que puede contener enteros. La solución es convertir cada elemento a str:
python ", ".join(str(key) for key in missing_keys)
Así el valor siempre será un string, incluso si venía como número, y join recibe la lista de strings que espera. Al ejecutar mypy src aparece el mensaje deseado: éxito, sin issues en los 16 archivos analizados.
Cómo genero un reporte HTML de tipado
Aunque el tipado no es obligatorio, es muy útil durante el desarrollo, y puedes compartir con tu equipo qué archivos están tipados mediante un reporte visual. Primero instalas la dependencia necesaria:
bash uv add --dev lxml
Luego generas el reporte indicando la carpeta de salida:
bash mypy src --html-report mypy_report
Esto crea una carpeta con un índice que puedes abrir en el navegador para ver cada archivo, su precisión y las líneas donde se aplica el tipado.
Qué alternativas tengo además de MyPy
MyPy no es la única opción, y elegir la herramienta correcta depende de tu flujo de trabajo y del tamaño de tu proyecto. Estas son las alternativas mencionadas:
- Pyright de Microsoft: se integra mucho mejor con Visual Studio Code y es la que aparece cuando pasas el mouse sobre los errores en el editor.
- Ty de Astral: promete ser aún más rápido, pero sigue en prealfa, no es apto para producción y le falta cerca de un año para estar listo.
Como reto, intenta configurar MyPy con tus propias reglas, igual que se hizo con Ruff. ¿Qué configuración de tipado te resulta más útil en tus proyectos? Cuéntalo en los comentarios.
