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 nine 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, and a branch is easier to verify when its condition states the positive form.

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.

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 1, 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:
Newer release available (0.0.7)

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 1, 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.5-py3-none-win_amd64.whl (2.0 MB view details)

Uploaded Python 3Windows x86-64

gruff-0.0.5-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.5-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.9 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

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

Uploaded Python 3macOS 11.0+ ARM64

gruff-0.0.5-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.5-py3-none-win_amd64.whl.

File metadata

  • Download URL: gruff-0.0.5-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.5-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 df0f012ea4090c2c44ccb4261241dcf608112dfae1c40471e57edfe8cf09be68
MD5 8a00b9874601dbda69fe25797a2cefac
BLAKE2b-256 a891fc069b049a6cc958597b277c148232e15096e033d8cc24c1095950cb24de

See more details on using hashes here.

Provenance

The following attestation bundles were made for gruff-0.0.5-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.5-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for gruff-0.0.5-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 728ae005c8505f3ff3a5d71de2c4013ae64fd1a6ee1f057ebaf309600b3d7b61
MD5 763b322bf0eef1be0c16d3d463a85bc0
BLAKE2b-256 6172b5b48628f6305709aaa9d4bf4ef5ad19cc08a4f309f0995fe7c2ae2b481e

See more details on using hashes here.

Provenance

The following attestation bundles were made for gruff-0.0.5-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.5-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for gruff-0.0.5-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 e240efbea06923d2880e7028f46240f481b9cbbfa9587b00872a6e4a60cb0e71
MD5 8e515ad00a6830d2a6a2a2c9ddb72fb9
BLAKE2b-256 4ff7f78caabea24456e5af4b272d99c349cf8ed9d7893f9a94d2daa3ec5b7ed1

See more details on using hashes here.

Provenance

The following attestation bundles were made for gruff-0.0.5-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.5-py3-none-macosx_11_0_arm64.whl.

File metadata

  • Download URL: gruff-0.0.5-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.5-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f078a6737c5a36a5a9497586875410e01a3d77002688ac5a00f9f33f577db6c3
MD5 ff228e2b0885877030054ec8352981db
BLAKE2b-256 d83a56990ab23561e9464e9dae2e87f2e438758c90e66e29cbe8e6f609b9b76d

See more details on using hashes here.

Provenance

The following attestation bundles were made for gruff-0.0.5-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.5-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for gruff-0.0.5-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 662c389fc1c090bade52c8ab991a9a63b41f3cec7108007e81479ade0b8a8043
MD5 30267c89dc9524a00d438d68317f06bb
BLAKE2b-256 9e4c7f19aad3e7b621e73a13822e854c13195ca29366bd4952d0fd03df51981a

See more details on using hashes here.

Provenance

The following attestation bundles were made for gruff-0.0.5-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

0.0.7

5 files

0.0.6

5 files

This release

0.0.5 This release

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