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.

A code listing showing Python variable and class attribute type annotations.
Example of the explicit type declarations Gawain enforces across a codebase.github.com

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.

Median Check Time on CPython 3.14 Standard Library: gawain, obvious mode 0.46 s; gawain, strict mode 0.36 s; ruff --select ANN 0.35 s; flake8-annotations 11.4 s
Median Check Time on CPython 3.14 Standard Librarygithub.com

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.