Gawain flags unannotated variables and functions, displaying error codes like GW001 and GW003.
*Gawain, a new open‑source utility, scans Python code for missing type annotations on variables, parameters, returns and class attributes. It forces developers to annotate beyond function signatures, aiming to eliminate ambiguous `dict[str, Any]` patterns.*
A new Python linting tool called Gawain has hit the open‑source scene, promising to close a long‑standing gap in static analysis. Unlike existing linters that only demand type hints on functions, Gawain scans every variable, parameter, return and class attribute for missing annotations. The project, hosted on GitHub, targets developers who are tired of ambiguous `dict[str, Any]` patterns and want a single command that both flags omissions and runs a type checker. Its creator, who openly despises the generic construct, built the utility to force explicit contracts across codebases, arguing that IDE inference is insufficient for production‑grade safety.
Gawain parses a Python project, flags any variable, parameter, return or class attribute lacking an explicit type hint, then runs a type checker—either ty (default) or pyrefly—to verify correctness. It emits error codes such as GW001 for unannotated variables, GW002 for parameters, GW003 for missing return types, and GW004 for class attributes not declared in the class body. The tool can operate in "obvious" mode, where literals like `count = 0` are exempt, or in strict mode, which demands an annotation on every assignment. Users invoke it via `gawain check src/` and can request JSON output, switch checkers, or limit the run to annotation checks only with `--no-types`. The command exits with 0 when clean, 1 on errors, and 2 on usage failures, making it script‑friendly for CI pipelines.
The author built Gawain out of frustration with generic `dict[str, Any]` constructs that hide data contracts. While existing linters like ruff's ANN rules and flake8-annotations only target functions, Gawain extends the mandate to every assignment and class attribute. This prevents silent type drift and forces developers to declare constants with `Final[T]`, as shown by the example where `PORT = 8080` triggers GW001 until annotated as `Final[int]`. By catching ambiguous types early, the tool reduces reliance on IDE inference and encourages stricter static analysis across codebases.
Benchmarking on the CPython 3.14 standard library (1,847 files, 974,586 lines) shows Gawain completing an "obvious" mode run in a median of 0.46 seconds over 30 runs. In strict mode the median drops to 0.36 seconds. By contrast, ruff's ANN selector for parameters and returns records 0.35 seconds, while flake8-annotations takes 11.4 seconds for the same checks. The test ran on an AMD Ryzen 7 3700X under WSL2. These figures demonstrate that Gawain adds minimal overhead while delivering broader coverage than the compared tools.
Installation is straightforward: `uv tool install "gawain[ty]"` or `pip install "gawain[ty]"` for the default checker, and `uv tool install "gawain[pyrefly]"` for the alternative. The configuration file lets users select the checker with `checker = "pyrefly"` or switch to annotation‑only mode with `--no-types`. The repository warns that ty is in beta and its diagnostics may change, recommending pyrefly or `--no-types` for stable projects. Gawain also provides a pre‑commit hook, requiring Rust 1.97 or newer to build. Suppression syntax (`# gawain: ignore[GW001]`) lets teams silence false positives while preserving overall enforcement.
Gawain prints error codes such as GW001 for variables, GW002 for parameters, GW003 for missing return annotations, and GW004 for class attributes not declared in the class body.
The default checker is ty (pinned to 0.0.100); users can switch to pyrefly (pinned to 1.4.1) by installing the pyrefly extra and setting `checker = "pyrefly"`.
On the CPython 3.14 standard library, Gawain runs in a median of 0.46 s (obvious mode) while flake8-annotations takes 11.4 s for parameters and returns.
Gawain arrives at a moment when Python projects increasingly rely on static typing to maintain reliability. By extending enforcement to variables and class attributes, it raises the bar for code clarity without imposing prohibitive runtimes. Teams that adopt it can expect tighter contracts, earlier detection of type mismatches, and a smoother CI experience. The tool's open‑source nature and flexible checker options make it a viable addition to any Python developer's arsenal, provided they heed the beta warning on the default ty checker.
Sources: Hacker News post linking to GitHub repository https://github.com/matheuzgomes/gawain