gawain requires type annotations on the variables, parameters, returns and class attributes of Python code, then runs ty to check that the types are correct.
Type checkers such as mypy, Pyright and ty infer the type of a variable that has no annotation. ruff's ANN
rules and flake8-annotations ask for annotations on functions only. gawain also asks for them on variables and
class attributes.
Why
I built gawain only because I hate dict[str, Any] and wanted to do something about it. If your answer to
this is "but Python already infers that" or "but my IDE infers it for me", then don't use it, little padawan.
What it reports
Given shop.py:
PORT = 8080
retries = 3
total = compute()
def send(to, body):
...
class Order:
def __init__(self, items: list[str]) -> None:
self.items = items
gawain check shop.py prints:
[presence]
shop.py:1:1 GW001 variable 'PORT' has no type annotation
shop.py:3:1 GW001 variable 'total' has no type annotation
shop.py:6:5 GW003 function 'send' has no return type annotation
shop.py:6:10 GW002 parameter 'to' of function 'send' has no type annotation
shop.py:6:14 GW002 parameter 'body' of function 'send' has no type annotation
shop.py:12:14 GW004 attribute 'items' is not declared in the body of class 'Order'
6 errors (presence). Type check skipped until presence errors are fixed.
retries = 3 passes, because a literal has an obvious type. PORT is a constant, so it needs Final[int].
When every annotation is in place, gawain runs ty on the same files and prints what ty reports. For
prices.py:
def total(prices: list[int]) -> int:
return "0"
[types]
prices.py:2:12 ty[invalid-return-type] Return type does not match returned value: expected `int`, found `Literal["0"]`
1 error (types).
Install
uv tool install gawain
# or
pip install gawain
The package installs the gawain command and ty, pinned to 0.0.100.
Usage
gawain check src/ # annotations, then types
gawain check src/ --no-types # annotations only
gawain check src/ --mode strict # an annotation on every assignment
gawain check src/ --format json # one JSON object, for tools
gawain exits with 0 when nothing is reported, 1 when it reports an error, and 2 on a usage error or
when ty cannot run. ty's warnings are printed but do not fail the check.
Rules
| Code | Reports |
|---|---|
| GW001 | A variable assigned with no annotation. |
| GW002 | A parameter with no annotation. |
| GW003 | A function with no return annotation. |
| GW004 | A class attribute with no annotation, or a self.x that the class body does not declare. |
| GW010 | A constant that is not annotated Final[T]. |
| GW011 | A bare Final, with no type. |
| GW020 | Any in an annotation. |
GW000 marks a file gawain cannot read, and GW900 and GW901 mark a broken or unused suppression. To silence a line, name the code:
value = load() # gawain: ignore[GW001]
docs/rules.md has the full rules, the exemptions and the suppression syntax.
Modes
The default mode is obvious. A name may go without an annotation when its value has an obvious type and the
name is never assigned again: a literal (count = 0), a container of literals (ids = [1, 2, 3]) or a
constructor call (user = User("ada")). strict asks for an annotation on every assignment:
[tool.gawain]
mode = "strict"
docs/rules.md has the exact rules of each mode.
pre-commit
repos:
- repo: https://github.com/matheuzgomes/gawain
rev: v0.1.0
hooks:
- id: gawain
pre-commit installs the hook from this repository's source, so building it needs Rust 1.97 or newer.
docs/configuration.md covers [tool.gawain], paths and the hook in detail.
Performance
On the CPython 3.14 standard library (1,847 files, 974,586 lines), median of 30 runs (5 for flake8-annotations):
| Tool | Checks | Median |
|---|---|---|
| gawain, obvious mode | variables, parameters, returns, attributes | 0.46 s |
| gawain, strict mode | variables, parameters, returns, attributes | 0.36 s |
ruff --select ANN |
parameters, returns | 0.35 s |
| flake8-annotations | parameters, returns | 11.4 s |
gawain ran with --no-types. This is one benchmark on one machine (AMD Ryzen 7 3700X, WSL2).
docs/benchmarks.md has the versions and the commands to run it again.
Documentation
- docs/rules.md: rules, modes, exemptions and suppression.
- docs/configuration.md: paths, output, exit codes,
[tool.gawain]and pre-commit. - docs/benchmarks.md: how the numbers above were measured.
Acknowledgements
gawain reads Python with ruff_python_parser and checks types with ty, both by Astral.
Name
I don't know, I just like the Arthurian tales. Gawain is a knight of the Round Table, and the mascot is the Green Knight's axe with the green girdle from Sir Gawain and the Green Knight.
License
MIT. See LICENSE.
Metadata
Release files for gawain 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gawain-0.1.0.tar.gz | 123.3 kB | With provenance | Details for gawain-0.1.0.tar.gz |
Built distributions (wheels)
Total release size: 16.0 MB
Release files / gawain-0.1.0.tar.gz
| Download URL | gawain-0.1.0.tar.gz |
|---|---|
| Size | 123.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7f3726df0373f5cd62ef2d8b742e742d993249afc02eac1262bd00d448c6d8ff
|
|
BLAKE2b-256 checksum How to use checksums |
65e26322be76da463688145dae7e438f65e1020f054fcb2c79b74bcb49d728b3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / gawain-0.1.0-py3-none-win_amd64.whl
| Download URL | gawain-0.1.0-py3-none-win_amd64.whl |
|---|---|
| Size | 2.1 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
225661ba43e21cd2c70da40e99914456509163c16e972b9879e96b9e91e34349
|
|
BLAKE2b-256 checksum How to use checksums |
b9688d58bebcad2fce220c46b27f9ec5c7d2b66cdf96050d4610494e97f05728
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / gawain-0.1.0-py3-none-musllinux_1_2_x86_64.whl
| Download URL | gawain-0.1.0-py3-none-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 2.4 MB |
| Tags | Linux musl 1.2+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
677b8112ff8d93c92420fb0dee992982ccf6ead219ffa381cc6172ef6aaae1a3
|
|
BLAKE2b-256 checksum How to use checksums |
8eb94252fb7d277f7e54f87beade196b68be93181f5905fdd1816c089a39556a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / gawain-0.1.0-py3-none-musllinux_1_2_aarch64.whl
| Download URL | gawain-0.1.0-py3-none-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 2.3 MB |
| Tags | Linux musl 1.2+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
76f5da7331139fb35180a41387a9bcf1da0e4ef6a2b65b843408742c3179b0b2
|
|
BLAKE2b-256 checksum How to use checksums |
b6c31e17832a6bdb650be68769d6cb6cbb2d5d66e9f7503a024f2b261bdf290d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / gawain-0.1.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
| Download URL | gawain-0.1.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl |
|---|---|
| Size | 2.3 MB |
| Tags | Linux glibc 2.17+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
e0a609b503d31e81e881794a4f90680b43d4c78a32446ad36c36417b0f161def
|
|
BLAKE2b-256 checksum How to use checksums |
f830b0e29e83e6480f7475fd8598f44d354ede81f9ba73bfc4349be55ce0a180
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / gawain-0.1.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
| Download URL | gawain-0.1.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl |
|---|---|
| Size | 2.3 MB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
e8ce4be1db7cfb2b9213443d5880ca19b39ef4ee7e4be5508f2c4a0be975f9c6
|
|
BLAKE2b-256 checksum How to use checksums |
91e9d5f9a910672dd9a38683f11e76246cc077f8c5004f0c5d63ca65d9356a0a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / gawain-0.1.0-py3-none-macosx_11_0_arm64.whl
| Download URL | gawain-0.1.0-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 2.2 MB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
2e31813362a9ff55b682d7b3e2557fa2ef45705204f488e0d1247ce70b796c36
|
|
BLAKE2b-256 checksum How to use checksums |
ac557dc89582972845e3e81bd7bdc13249d8bbeb05fc86bb72ecd2f872fc4fad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / gawain-0.1.0-py3-none-macosx_10_12_x86_64.whl
| Download URL | gawain-0.1.0-py3-none-macosx_10_12_x86_64.whl |
|---|---|
| Size | 2.2 MB |
| Tags | Python 3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
4687b7feda55306ae9ffc5d9927ee9dec4addf9cb8bd582bbc2a24cca3e78cc3
|
|
BLAKE2b-256 checksum How to use checksums |
d6a92447aee4440498665254a56e95d15fb286885909ea905adec7fddc8c76ce
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logSecurity for gawain 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 8 files in this release have been uploaded with provenance metadata.
Attestation for gawain-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.