Skip to main content

gawain: the green axe with the green girdle, above the name in blackletter

gawain requires type annotations on the variables, parameters, returns and class attributes of Python code, then runs a type checker, ty or pyrefly, to check that the types are correct.

Type checkers such as mypy, Pyright, ty and pyrefly 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):
    print(f"to {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 the type checker on the same files and prints what it reports. With ty, the default, 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

Install gawain with the extra of the type checker you want. ty is the default checker, and the ty extra pins it to 0.0.100:

uv tool install "gawain[ty]"
# or
pip install "gawain[ty]"

To use pyrefly instead, install the pyrefly extra, which pins pyrefly 1.4.1 and does not install ty:

uv tool install "gawain[pyrefly]"
# or
pip install "gawain[pyrefly]"

Then choose it with checker = "pyrefly" in [tool.gawain], or with --checker pyrefly. docs/configuration.md explains the switch.

pip install gawain without an extra installs only the gawain command. It then needs a checker on PATH, or --no-types to run the annotation checks only.

Usage

gawain check src/                  # annotations, then types
gawain check src/ --no-types       # annotations only
gawain check src/ --checker pyrefly  # pyrefly instead of ty
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 the type checker cannot run. The type checker'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.3.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

Acknowledgements

gawain reads Python with ruff_python_parser and checks types with ty, both by Astral, or with pyrefly, by Meta.

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.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gawain 0.3.0
File Size Uploaded Provenance Actions
gawain-0.3.0.tar.gz 127.6 kB With provenance Details for gawain-0.3.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for gawain 0.3.0
File Actions
gawain-0.3.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for gawain-0.3.0-py3-none-win_amd64.whl
gawain-0.3.0-py3-none-musllinux_1_2_x86_64.whl Python 3 none Linux musl 1.2+ x86-64 Details for gawain-0.3.0-py3-none-musllinux_1_2_x86_64.whl
gawain-0.3.0-py3-none-musllinux_1_2_aarch64.whl Python 3 none Linux musl 1.2+ ARM64 Details for gawain-0.3.0-py3-none-musllinux_1_2_aarch64.whl
gawain-0.3.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl Python 3 none Linux glibc 2.17+ x86-64 Details for gawain-0.3.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
gawain-0.3.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64 Details for gawain-0.3.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
gawain-0.3.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for gawain-0.3.0-py3-none-macosx_11_0_arm64.whl
gawain-0.3.0-py3-none-macosx_10_12_x86_64.whl Python 3 none macOS 10.12+ x86-64 Details for gawain-0.3.0-py3-none-macosx_10_12_x86_64.whl

Total release size: 16.2 MB

Release files / gawain-0.3.0.tar.gz

Download URL gawain-0.3.0.tar.gz
Size 127.6 kB
Tags Source
SHA-256 checksum
How to use checksums
0954e8aff7f913df4c521102b06ab05b0ec0e9c16b043882795097fbe08f26a3
BLAKE2b-256 checksum
How to use checksums
69f87adeb5fe666883fd2488cfc1b67817031afc255ac8343ca7b5b11ed1a423
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 13, 2026.

Transparency log

Release files / gawain-0.3.0-py3-none-win_amd64.whl

Download URL gawain-0.3.0-py3-none-win_amd64.whl
Size 2.1 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
68fa79eb4033d589f75c7aada10e7823e2f2b6ed618a18ce846ffceaf55cc453
BLAKE2b-256 checksum
How to use checksums
7413b85bfdff64d15b07e2451c7e9b625d4dc058ce1157be540cdaa7cf006e0e
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 13, 2026.

Transparency log

Release files / gawain-0.3.0-py3-none-musllinux_1_2_x86_64.whl

Download URL gawain-0.3.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
733854881bf265ed885fe2250417c8fa145c99d6b8f5984e329abf33e5990d61
BLAKE2b-256 checksum
How to use checksums
2985411e42dcfed0e999b70c2a9c040414795cdbe71558bbab24e476cf1b7605
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 13, 2026.

Transparency log

Release files / gawain-0.3.0-py3-none-musllinux_1_2_aarch64.whl

Download URL gawain-0.3.0-py3-none-musllinux_1_2_aarch64.whl
Size 2.4 MB
Tags Linux musl 1.2+ ARM64 Python 3
SHA-256 checksum
How to use checksums
284706a2bd2973a0b19b8783bd73781431fbe64e1de5ee77a6e4df7af4bf91be
BLAKE2b-256 checksum
How to use checksums
b2f2f33b2767c919cc46dbb57ced5f381a9637fca6f161d653a5909066137544
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 13, 2026.

Transparency log

Release files / gawain-0.3.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL gawain-0.3.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 2.4 MB
Tags Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
f5351f206859152ef8530058ff031eae111ec46b96cb2a460f648fd207342196
BLAKE2b-256 checksum
How to use checksums
618d9b0ef24cf002ccd2471a8df729d8d60c6858e58c800af44f99921f020db1
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 13, 2026.

Transparency log

Release files / gawain-0.3.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL gawain-0.3.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
91c1d38147ca5c18c5bca6dec66e2cba2d950c6aa0d4afc53440033015812f0e
BLAKE2b-256 checksum
How to use checksums
a594aa668b63d28da12e6e2f24f08135e936cd0779302d6e4ab974177192c522
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 13, 2026.

Transparency log

Release files / gawain-0.3.0-py3-none-macosx_11_0_arm64.whl

Download URL gawain-0.3.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
a1bc62dde6ec195ba72ca7de1e1e7c1992697bf45086c797a67215de444d76d5
BLAKE2b-256 checksum
How to use checksums
d588d341c0c1cdc1ceec16f5f43278839e2c341b10d79a0707172d339497daab
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 13, 2026.

Transparency log

Release files / gawain-0.3.0-py3-none-macosx_10_12_x86_64.whl

Download URL gawain-0.3.0-py3-none-macosx_10_12_x86_64.whl
Size 2.3 MB
Tags Python 3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
757072a8b68a32ca44cb9436c5290b973163a876acb456dc2e17cbabfaabfbca
BLAKE2b-256 checksum
How to use checksums
9f8d775f00359f300ed8652b1bfc0abd544c6dea877a22bfd3cd131ccea75a03
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 13, 2026.

Transparency log

Security for gawain 0.3.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.

Select from 8 files

Attestation for gawain-0.3.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 13, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page