Gawain, a 41-Star Python Linter, Wants a Type Annotation on Every Variable
Software / news
Gawain, a 41-Star Python Linter, Wants a Type Annotation on Every Variable
Ruff's ANN rules stop at function signatures; Gawain's GW001 does not, and its speed figure excludes the type checker.
Gawain, a Python linter at version 0.3.1, flags any variable that lacks a type annotation, a check that ruff's flake8-annotations rules do not make. The repository showed 41 stars, no forks and one watcher when it surfaced as a Show HN post.
It is MIT-licensed and published by the GitHub user matheuzgomes. The README gives the author's motive in one line: "I built gawain only because I hate dict[str, Any]." Its tagline is "Every Python type declared, every covenant kept."
What it checks
Ruff's ANN rules cover function arguments and return types. Ruff's documentation lists ANN001 through ANN401, marks every active one as pedantic, enables none by default and has no rule for local variables. Gawain's rules start where those stop.
| Code | What it flags |
|---|---|
| GW001 | Variable with no annotation |
| GW002 | Parameter with no annotation |
| GW003 | Function with no return annotation |
| GW004 | Class attribute not declared in the class body |
| GW010 | Constant not annotated Final[T] |
| GW020 | Any in an annotation |
The default obvious mode lets literals, literal containers and constructor calls go unannotated if the name is never reassigned. strict mode requires an annotation on every assignment. Output looks like shop.py:1:1 GW001 variable 'PORT' has no type annotation.
The friction
After the annotation check, Gawain runs a type checker over the annotated code, ty by default or pyrefly. Installing with uv tool install "gawain[ty]" pins ty 0.0.100, and the pyrefly extra pins pyrefly 1.4.1. A plain pip install gawain installs no checker, so the tool needs one on the path or the --no-types flag.
Two details cost setup time. The pre-commit hook builds from source and needs Rust 1.97 or newer on the machine. And the README itself says ty is in beta, so diagnostics may change between versions, and it suggests pyrefly or --no-types for anyone worried about that.
Exit codes are 0 for clean, 1 for errors and 2 for a usage error or an unavailable checker. Checker warnings print but do not fail the run, which matters for a pre-commit hook: a ty warning will not block a commit, but a missing GW001 annotation will.
The speed claim
The README reports 0.46 seconds in obvious mode on the CPython 3.14 standard library. That figure is the author's own, from one machine, an AMD Ryzen 7 3700X under WSL2, and the benchmarks ran with --no-types. It measures the annotation scan, not the type checker that follows it.
Who would want it
A team that already enforces ANN rules and still finds dict[str, Any] leaking through untyped locals is the target. For everyone else, strict mode asks for an annotation on every assignment, which is a large diff on an existing codebase, and the type-checking half depends on a beta tool.
With 41 stars, there is no adoption record yet. The next version number and any move of ty out of beta will decide whether the pinned versions in the extras need to change. Python's other tooling is moving on its own schedule: PyPI's new security tab now grades releases by attestation, and Agweb shows how small Show HN tools are being built around coding agents.
Sources
More in Software
- 01Levien's Next-100 Rust GUIs Post Counts About 20 New Toolkits and Bets Against egui's Immediate ModeThe Linebender author credits AI rewrites for the surge; egui's own README concedes the trade-off he is pressing on.
- 02C++26 Is Reopened: The 13–9–12 Ballot, the Enforced Label That Answers It, and What Is Still OpenSutter's Búzios report says the committee kept contracts, added one paper, and will send C++26 to a second ballot with no published date.
- 03OpenAI Says Codex Cannot Run in Docker for iOS Builds, and Docker Launches It With Codex's Sandbox OffBolin's November 18 post lists Seatbelt, Bubblewrap and MXC as Codex's three sandboxes; Docker's page defaults to --dangerously-bypass-approvals-and-sandbox.
- 04CLI-Anything Has 62,119 Stars and a README With Three Different Test TotalsThe HKUDS project turns desktop software into agent-callable CLIs; its own per-harness lines sum to 158 more tests than it reports.