Show HN: Gawain – Require type hints on all Python variables

gawain is a Python tool that requires type hints on all variables, parameters, returns, and class attributes. It then runs a type checker (ty or pyrefly) to verify that the types are correct. Type checkers like mypy, Pyright, ty, and pyrefly infer variable types when no annotation is present. Unlike ruff's ANN rules and flake8-annotations, which only ask for annotations on functions, gawain requests them on variables and class attributes as well.

The developer built gawain to avoid using dict[str, Any] and prefers explicit type annotations. If you don't agree with this approach, gawain might not be suitable for you.

gawain exits with 0 for no errors, 1 for errors, and 2 for usage errors. It marks files it cannot read (GW000), broken or unused suppressions (GW900 and GW901), and provides a suppression syntax to silence lines. The default mode is straightforward, but there are strict and other modes available in the documentation.

To install gawain, use pip with the desired type checker extra (ty is the default, with version 0.0.100). For pyrefly, install the pyrefly extra instead. Choose the checker with the 'checker' option in [tool.gawain] or using --checker. The gawain command requires a type checker on PATH, or you can use --no-types to run only the annotation checks.

When you use gawain, it reads Python code with ruff_python_parser and checks types with either ty (by Astral) or pyrefly (by Meta). The tool was benchmarked on the CPython 3.14 standard library, which consists of 1,847 files and 974,586 lines. In this benchmark, gawain ran with --no-types, taking the median of 30 runs (5 runs for flake8-annotations).