While standard Python linters like Ruff and flake8-annotations typically only require type hints for function parameters and return types, Gawain enforces annotations on every variable, parameter, and class attribute within a codebase. Developed to eliminate the use of generic types like `dict[str, Any]`, the tool identifies missing annotations in milliseconds, providing a stricter layer of type safety for developers who prefer explicit declarations over Python's native inference.
Beyond Function Signatures
Most Python type-checking workflows rely on tools that verify if functions have return types and parameter annotations. Gawain extends this requirement to the internal logic of the code, flagging variables that lack explicit type declarations.
For example, Gawain will report an error if a constant like `PORT = 8080` is not annotated as `Final[int]`, or if a class attribute is assigned without a corresponding declaration in the class body.

This screenshot illustrates the specific type annotations and variable declarations that Gawain validates.
Mechanism and Integration
Gawain acts as a gatekeeper for type integrity by first scanning source code for 'presence' errors—missing annotations. It only proceeds to run a full type check using a backend like `ty` or `pyrefly` once all required hints are present.
Users can choose between 'obvious' mode, which permits unannotated literals (e.g., `count = 0`) and container literals, and 'strict' mode, which requires an annotation for every single assignment.
Performance and Trade-offs
The tool is built for high-performance analysis, utilizing the `ruff_python_parser` to achieve rapid results. In testing against the CPython 3.14 standard library, Gawain completed its checks in roughly 0.46 seconds in 'obvious' mode.
Chart drawn by HN Digest from figures reported by github.com; values are shown as written in the source.
A primary trade-off of using Gawain is the increased verbosity of the codebase. By requiring hints on every variable, it moves away from Python's native inference capabilities in favor of explicit, readable type definitions.