Gawain: herramienta para detectar faltas de anotaciones de tipos en Python

Fuentes: Gawain: a tool to detect missing type hints in Python code

Gawain es una herramienta de línea de comandos diseñada para identificar y corregir la ausencia de anotaciones de tipos en el código Python, superando las limitaciones de los verificadores de tipos tradicionales. A diferencia de herramientas como ruff o flake8, que se centran principalmente en funciones, Gawain exige anotaciones explícitas en variables, parámetros, retornos y atributos de clases, utilizando el verificador de tipos 'ty' o 'pyrefly' para validar la coherencia de los tipos inferidos.

El proyecto nace de la frustración del desarrollador con el uso excesivo de 'dict[str, Any]' y la falta de verificación exhaustiva en variables y atributos. Gawain opera en dos fases: primero, realiza un análisis de presencia para detectar variables sin anotación, constantes sin etiqueta 'Final' o atributos de clase no declarados; si se encuentran errores, se detiene la verificación de tipos para evitar falsos positivos. Una vez resueltos los errores de presencia, ejecuta el verificador de tipos seleccionado para validar la lógica de los tipos.

La herramienta ofrece configuraciones flexibles, incluyendo un modo 'strict' que exige anotaciones en cada asignación y opciones para silenciar reglas específicas mediante comentarios. Gawain se integra fácilmente en flujos de trabajo existentes mediante pre-commit hooks o configuración en 'pyproject.toml'. En términos de rendimiento, Gawain logra tiempos de verificación medianos de 0,46 segundos en el modo estándar y 0,36 segundos en modo estricto al analizar la biblioteca estándar de Python 3.14, superando significativamente a flake8-annotations (11,4 segundos) y siendo comparable a ruff, aunque con una cobertura más amplia de elementos del código.