Mientras que los linters estándar de Python como Ruff y flake8-annotations normalmente solo requieren anotaciones de tipo para los parámetros de las funciones y los tipos de retorno, Gawain impone anotaciones en cada variable, parámetro y atributo de clase dentro de una base de código. Desarrollada para eliminar el uso de tipos genéricos como `dict[str, Any]`, la herramienta identifica las anotaciones faltantes en milisegundos, proporcionando una capa más estricta de seguridad de tipos para los desarrolladores que prefieren declaraciones explícitas sobre la inferencia nativa de Python.

Más allá de las firmas de funciones

La mayoría de los flujos de trabajo de verificación de tipos en Python dependen de herramientas que verifican si las funciones tienen tipos de retorno y anotaciones de parámetros. Gawain extiende este requisito a la lógica interna del código, señalando las variables que carecen de declaraciones de tipo explícitas.

Por ejemplo, Gawain informará un error si una constante como `PORT = 8080` no está anotada como `Final[int]`, o si un atributo de clase se asigna sin una declaración correspondiente en el cuerpo de la clase.

Un listado de código que muestra las anotaciones de tipo de variables y atributos de clase en Python.
Ejemplo de las declaraciones de tipo explícitas que Gawain impone en una base de código.github.com

Esta captura de pantalla ilustra las anotaciones de tipo específicas y las declaraciones de variables que Gawain valida.

Mecanismo e integración

Gawain actúa como un guardián de la integridad de los tipos escaneando primero el código fuente en busca de errores de 'presencia' —anotaciones faltantes—. Solo procede a ejecutar una verificación de tipos completa utilizando un backend como `ty` o `pyrefly` una vez que todas las anotaciones requeridas están presentes.

Los usuarios pueden elegir entre el modo 'obvious', que permite literales sin anotar (por ejemplo, `count = 0`) y literales de contenedores, y el modo 'strict', que requiere una anotación para cada asignación individual.

Rendimiento y compensaciones

La herramienta está construida para el análisis de alto rendimiento, utilizando `ruff_python_parser` para lograr resultados rápidos. En pruebas contra la biblioteca estándar de CPython 3.14, Gawain completó sus comprobaciones en aproximadamente 0.46 segundos en el modo 'obvious'.

Tiempo de comprobación mediano en la biblioteca estándar de CPython 3.14: gawain, obvious mode 0.46 s; gawain, strict mode 0.36 s; ruff --select ANN 0.35 s; flake8-annotations 11.4 s
Tiempo de comprobación mediano en la biblioteca estándar de CPython 3.14github.com

Gráfico elaborado por HN Digest a partir de cifras reportadas por github.com; los valores se muestran como en la fuente.

Una compensación principal de usar Gawain es el aumento de la verbosidad de la base de código. Al requerir anotaciones en cada variable, se aleja de las capacidades de inferencia nativa de Python en favor de definiciones de tipos explícitas y legibles.