Présentation

Gawain est un utilitaire en ligne de commande qui vérifie la présence d’annotations de type sur les variables, paramètres, valeurs de retour et attributs de classe dans du code Python. Après cette première passe, il lance un vérificateur de type – ty par défaut, ou pyrefly lorsqu’il est sélectionné – afin de confirmer la cohérence des types déclarés.

Fonctionnement et modes

Le processus s’appuie sur le parseur ruff_python_parser pour analyser le code source, puis transmet les informations au vérificateur choisi. Deux modes sont disponibles : le mode default, qui autorise les variables dont la valeur est un littéral ou une construction évidente (ex. count = 0), et le mode strict, qui exige une annotation sur chaque assignation. Les règles détaillées, ainsi que les exemptions, sont décrites dans docs/rules.md.

shop.py:1:1    GW001 variable 'PORT' has no type annotation
shop.py:3:1    GW001 variable 'total' has no type annotation
shop.py:6:5    GW003 function 'send' has no return type annotation
shop.py:6:10   GW002 parameter 'to' of function 'send' has no type annotation
shop.py:6:14   GW002 parameter 'body' of function 'send' has no type annotation
shop.py:12:14  GW004 attribute 'items' is not declared in the body of class 'Order'
6 errors (presence)

Intégration et performances

L’installation se fait via pip install "gawain[ty]" pour le vérificateur ty, ou pip install "gawain[pyrefly]" pour pyrefly. Le projet propose également un hook pre‑commit ; son activation nécessite Rust ≥ 1.97 pour compiler le binaire. Un benchmark réalisé sur la bibliothèque standard CPython 3.14 (1 847 fichiers, 974 586 lignes) montre que, en mode --no-types, la médiane de 30 exécutions sur une AMD Ryzen 7 3700X sous WSL2 reste stable, ce qui indique un impact raisonnable sur les pipelines CI.

Limites et considérations

Le vérificateur ty est en version bêta ; ses diagnostics peuvent évoluer entre les releases, ce qui peut entraîner des ruptures de compatibilité. En cas de besoin de stabilité, l’option pyrefly ou le mode --no-types permet de restreindre l’analyse aux seules vérifications d’annotations. Gawain renvoie le code de sortie 0 lorsqu’aucun problème n’est détecté, 1 en présence d’erreurs, et 2 pour les erreurs d’usage ou d’exécution du vérificateur, facilitant l’intégration dans des scripts automatisés.