Gruff

Gruff is an opinionated, deterministic maintainability linter for Python. It complements Ruff with project policies that make agent-assisted code easier to understand and review; it does not infer who or what wrote the code.

Installation

Requires Python 3.10 or later.

pip install gruff

Or with uv:

uv tool install gruff

Verify it works:

gruff --version

[!TIP] To try the latest development version (the head of main on GitHub) before it is published:

uv tool install git+https://github.com/wkentaro/gruff

Quick start

Enable every Gruff rule in pyproject.toml:

[tool.gruff.lint]
select = ["GR"]

Then check the current directory:

gruff check .

All rules are opt-in. Use an exact code such as GR001 to adopt rules individually; GR enables every Gruff rule. A check with no enabled rules succeeds but warns that it performed no policy analysis.

Rules at a glance

The first release tests ten theses: inputs are easier to trace when definitions declare how callers pass them, non-public behavior is easier to review when callers supply every value, package initializer manifests are easier to review when every public import path defines __all__, constants are easier to review when uppercase names and Final annotations always appear together, non-public definitions are easier to understand when their names carry their purpose, comments are worth reading when they state more than the code beneath them, tests are worth running when an exception can still fail them, a body is easier to follow when its trailing condition inverts into a guard, a branch is easier to verify when its condition states the positive form, and a non-public module binding is easier to find when it lives in the one definition that reads it.

Code Rule Policy
GR001 explicit-non-public-input-conventions Every fixed input to a non-public callable has an explicit calling convention.
GR002 required-non-public-inputs Callers supply every fixed input to non-public callables.
GR003 package-dunder-all Every public package import path defines __all__.
GR004 final-constants Uppercase names and Final annotations appear together.
GR005 explicit-public-input-conventions Every fixed input to a public callable has an explicit calling convention.
GR006 no-non-public-docstrings Non-public definitions carry their purpose in their names instead of docstrings.
GR007 no-subsumed-comments One-line comments state something beyond the statements they annotate.
GR008 no-exception-swallowing-tests Tests let exceptions propagate instead of swallowing them.
GR009 no-guarded-tails Trailing conditions invert into guards instead of nesting the rest of the body.
GR010 positive-branch-conditions Branch conditions state the positive form instead of negating around an else.
GR011 no-single-consumer-module-bindings Non-public module bindings live in the one definition that reads them.

Each rule links to its rule doc, which states what the rule flags, why, an example, and when to suppress. gruff rule GR004 prints the same document in the terminal, and gruff rule --all --output-format json emits every rule for tooling.

Documentation

The documentation site carries the rule docs, and its configuration page covers pyproject.toml, the command-line reference, suppressing findings, and the recommended Ruff pairing.

Distribution

Gruff releases use PyPI wheels for Linux x86_64 and aarch64, macOS x86_64 and arm64, and Windows x86_64. Gruff is not published to crates.io.

Project links

Data verified by PyPI on Sep 2, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for wkentaro from gravatar.com wkentaro

GitHub Statistics

Data verified by PyPI on Sep 2, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

gruff-0.0.7-py3-none-win_amd64.whl (2.0 MB view details)

Uploaded Python 3Windows x86-64

gruff-0.0.7-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.1 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

gruff-0.0.7-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.0 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

gruff-0.0.7-py3-none-macosx_11_0_arm64.whl (1.9 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

gruff-0.0.7-py3-none-macosx_10_12_x86_64.whl (2.0 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file gruff-0.0.7-py3-none-win_amd64.whl.

File metadata

  • Download URL: gruff-0.0.7-py3-none-win_amd64.whl
  • Upload date:
  • Size: 2.0 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for gruff-0.0.7-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 8e8aa556a4277461ba9232a2c0eeea4387eeac98d3dbab267e096551e454bb69
MD5 112365a6ecaab97ef29c91d425cd522a
BLAKE2b-256 00d640554223d112cc3417986f895790673099829afc620da7d13edf51a3a420

See more details on using hashes here.

Provenance

The following attestation bundles were made for gruff-0.0.7-py3-none-win_amd64.whl:

Publisher: release.yml on wkentaro/gruff

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gruff-0.0.7-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for gruff-0.0.7-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 253d54729a702cfedb9fcfd1605e58c0178adb2929fb7c10098fa4b3085455f9
MD5 636e4a2a3644dd7bc52287dab3b63acd
BLAKE2b-256 d89a17b21c1ea7d5f1b92cd80afe16289262575f81b6e5d1167d5d049a654740

See more details on using hashes here.

Provenance

The following attestation bundles were made for gruff-0.0.7-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on wkentaro/gruff

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gruff-0.0.7-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for gruff-0.0.7-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 51ec716bf630aae9ee79f5f91f70c61eaf96aa331818041b62b00208d3d2b5ee
MD5 8a1f24e35debffdf768cb8c3528248b8
BLAKE2b-256 ca99013e4a13814aa3517eb2626179e05fd65854aca7e1924ebc7853b1e2dc46

See more details on using hashes here.

Provenance

The following attestation bundles were made for gruff-0.0.7-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on wkentaro/gruff

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gruff-0.0.7-py3-none-macosx_11_0_arm64.whl.

File metadata

  • Download URL: gruff-0.0.7-py3-none-macosx_11_0_arm64.whl
  • Upload date:
  • Size: 1.9 MB
  • Tags: Python 3, macOS 11.0+ ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for gruff-0.0.7-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 fcceddadade866026d6ebc68abde9d074993bb43492fdbadc0e9bb4b1406fef6
MD5 e405de7adf70440c0fdb841b5d77cefb
BLAKE2b-256 eb8ef269bdf9d540b802fc17924cbb1dbf100f6aa6c30a7956a5d462f958d409

See more details on using hashes here.

Provenance

The following attestation bundles were made for gruff-0.0.7-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on wkentaro/gruff

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gruff-0.0.7-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for gruff-0.0.7-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 33637f8fdd049d956dc731bcc7294958e1fda976abe160e1ecaf9fe7c4e2dd03
MD5 3eed400dca10cc2d4fb5fd79ed507eeb
BLAKE2b-256 6c0b10ca786ddfe9a953cf9ad7cef5a7988339a71fa53417298ed17f815329de

See more details on using hashes here.

Provenance

The following attestation bundles were made for gruff-0.0.7-py3-none-macosx_10_12_x86_64.whl:

Publisher: release.yml on wkentaro/gruff

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.0.7 This release

5 files

0.0.6

5 files

0.0.5

5 files

0.0.4

5 files

0.0.3

5 files

0.0.2

5 files

0.0.1

5 files

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