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

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)

Source distribution for gawain 0.1.0
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)

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

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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

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

Select from 8 files

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