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):
    ...


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

uv tool install gawain
# or
pip install gawain

The package installs the gawain command and ty, pinned to 0.0.100. ty is the default type checker. To use pyrefly instead, install the pyrefly extra, which pins pyrefly 1.4.1:

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.

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.2.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.2.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.2.0
File Size Uploaded Provenance Actions
gawain-0.2.0.tar.gz 132.3 kB With provenance Details for gawain-0.2.0.tar.gz

Built distributions (wheels)

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

Total release size: 16.2 MB

Release files / gawain-0.2.0.tar.gz

Download URL gawain-0.2.0.tar.gz
Size 132.3 kB
Tags Source
SHA-256 checksum
How to use checksums
594b9176322dd849faa36d6bcb789a481ec32f93bc07b2f7a2d20c1e036f9706
BLAKE2b-256 checksum
How to use checksums
f337c90e583f0443a1cb0d2d731ac86799409f8064df056e614bbd6a529e1331
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.2.0-py3-none-win_amd64.whl

Download URL gawain-0.2.0-py3-none-win_amd64.whl
Size 2.1 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
6ee1d9cd9d5cb8ee6842aab0ae2c7c56c747023e1379b6d7da88c7ff439743ef
BLAKE2b-256 checksum
How to use checksums
f4e821db40e2f6c138a4b6df77b3fe5b3486afc69658b6bfb1cb2eebecfa804e
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.2.0-py3-none-musllinux_1_2_x86_64.whl

Download URL gawain-0.2.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
15234b96a320981c7c0dbe65a82e2f009435c24f0f68e3deee56a005ec556c46
BLAKE2b-256 checksum
How to use checksums
ca40099367b9943911c4b928a88e7bbdb1fbe130101fd7aa8ae88292871e5e52
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.2.0-py3-none-musllinux_1_2_aarch64.whl

Download URL gawain-0.2.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
66f9beb2bc1a5feb45fb9e6627d055dfe0af794f92129c7bf83017054e906291
BLAKE2b-256 checksum
How to use checksums
122b44cb3c78c2b7ceef65f71574089264e2058c04a77a106072e3ec033f83db
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.2.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL gawain-0.2.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
9c4d0f54489928eb11d4e4f843c2dbe4ae310f3f9e3467f72687d06b06420a2a
BLAKE2b-256 checksum
How to use checksums
55b3eba00df76cc9bd943fe7bb7f787c0b16090e80cc856dcfaa87bdd7000aa8
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.2.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL gawain-0.2.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
d6e738ee7e9634eb21733154b5126ef08f6d17da0e792fcbfd3adbaef49a7dd4
BLAKE2b-256 checksum
How to use checksums
761b39514d03d067ab339695d1565af04ba0b48a3f95e51334e0b95406bb3c7b
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.2.0-py3-none-macosx_11_0_arm64.whl

Download URL gawain-0.2.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
de585045bebb7ea7c4dd70082aabb9419e172a3e1c5e9db0c117c59e6307cb9b
BLAKE2b-256 checksum
How to use checksums
2737341d2695e93301ea50d6a7a403402b462dcedc1504ae87be91a6abe5b155
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.2.0-py3-none-macosx_10_12_x86_64.whl

Download URL gawain-0.2.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
d4bb1ac69276efb7f9be5234caf7df4f2dba20a86b56f0238b135e2a5e02f2fb
BLAKE2b-256 checksum
How to use checksums
bdf7e1cb9287604db15c46e08fab1335b5fe45efdac6635f0b886969bb9aa9a5
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.2.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.2.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