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

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.1
File Size Uploaded Provenance Actions
gawain-0.3.1.tar.gz 129.5 kB With provenance Details for gawain-0.3.1.tar.gz

Built distributions (wheels)

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

Total release size: 16.2 MB

Release files / gawain-0.3.1.tar.gz

Download URL gawain-0.3.1.tar.gz
Size 129.5 kB
Tags Source
SHA-256 checksum
How to use checksums
dab625e7d5cf2d352319ca3c02f45d66a03b9e3f2fa259d50d94f83e9c2387de
BLAKE2b-256 checksum
How to use checksums
cd50d822181974f5604784c1c4a57520378d1ce82a0d4b173fe11c24bd176108
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 15, 2026.

Transparency log

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

Download URL gawain-0.3.1-py3-none-win_amd64.whl
Size 2.1 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
7cb10918901a75e948c8176aee46c51cacc2a8608aa87c203832285eff18630e
BLAKE2b-256 checksum
How to use checksums
ca14f955c52b4fb2af88ae9b21d6eafedd3c3553674d76fb261217d0026bcb4b
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 15, 2026.

Transparency log

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

Download URL gawain-0.3.1-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
44f01149765e9298ff855454e39adb8b839b82704b80ab1cf2c204e30a432f33
BLAKE2b-256 checksum
How to use checksums
b351a762aa451e3cab19b9013409175ac5cfe76da472da89b0ee96e1ae7983ef
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 15, 2026.

Transparency log

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

Download URL gawain-0.3.1-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
aa9321c2587392e00c45454d0e075f4a2582503d1168b207b5fd0f1a3e0f8373
BLAKE2b-256 checksum
How to use checksums
51536c7323d84329ec8f98a0278344c45fc5454e2cac2e151b21450a1fb10811
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 15, 2026.

Transparency log

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

Download URL gawain-0.3.1-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
d8bcc21828057a67fd0b76fd198b28364a6e39733792fa55137caafc7b557c9b
BLAKE2b-256 checksum
How to use checksums
6041e6e4543faa572e2372a12f2076aabc01d3292d03800d1e74254dd9021e51
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 15, 2026.

Transparency log

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

Download URL gawain-0.3.1-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
12cdef4f48c63dd1f5d6f43a991711f64bd023efd7100e9e5739e12bfff5dc03
BLAKE2b-256 checksum
How to use checksums
092acecbe75f3f60b2d1d9bf40c58b7a201ee4b6f6da933333a401519c11ff4b
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 15, 2026.

Transparency log

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

Download URL gawain-0.3.1-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
005328414c7e99bdef10d995a2a96b6d9457b6b78c02147d35cc83591c697593
BLAKE2b-256 checksum
How to use checksums
22743b646e57d969b9d1f3fd12678d2a2d420401cd6cf94c18e76aa77b9c6f2f
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 15, 2026.

Transparency log

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

Download URL gawain-0.3.1-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
2a30f7b0faca511d33bb6b3e0551caf708010f9ff8012ccfeab9a8bb0f464ad9
BLAKE2b-256 checksum
How to use checksums
f6247d5794117cbba6ff8ef01aaab46f90fedcef5b0086179396eb9aab3d4cad
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 15, 2026.

Transparency log

Security for gawain 0.3.1

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.1.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 15, 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