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:
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 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.6-py3-none-win_amd64.whl (2.0 MB view details)

Uploaded Python 3Windows x86-64

gruff-0.0.6-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.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.0 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

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

Uploaded Python 3macOS 11.0+ ARM64

gruff-0.0.6-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.6-py3-none-win_amd64.whl.

File metadata

  • Download URL: gruff-0.0.6-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.6-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 1cee0319fc3ce22e23cadb9483fe93515551b4856d4a1ae94d8745329e88d33d
MD5 7fb49e36b2682e5261cb0bb7dcf74363
BLAKE2b-256 c7c3fbf10396f2043a097e65a5fa723371dc5b2e1613f6284185aba1043cd78e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gruff-0.0.6-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 51e9ac387ddac9fb3b6c487a62afce556c05b4012f4e04863c664dec602ab1de
MD5 5b11a2a7b21df3a7b5a837f77e0f2d07
BLAKE2b-256 5d38d2eb584c4d905f3ad08ec0881b0af0ec358cd7dcbedc01f3cfef644835cb

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gruff-0.0.6-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 28b1ecf709668088af42d3098be5786b608835ccbae17f9e4ac0c4aa434f0e44
MD5 3fd75cd0fbff579293e16427db7e23be
BLAKE2b-256 e5a6d15878075937223819b41627164de9b39588497cda8e5d7a354aca084c7a

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: gruff-0.0.6-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.6-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 d884fb3b934c577d246de24d9c978be78d90f67dfed02c17e43eb1d1745aee36
MD5 428c8e988afaf93ad61aa5784f03770d
BLAKE2b-256 ff973a550fe81f2ab03836e1a8fd986904b170d8173aee858dd2bbfb018f29fd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for gruff-0.0.6-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 ba23fe2c1ca1bf4b0033325c3c9c12d778757b5ccc3f991f6942b716d9b45557
MD5 59b3ba1fcbb1d98cbe24d26e6982d0df
BLAKE2b-256 59a70d517a09090571daa8bf19928a8a9481e1b0c5a1a79366febc23162f7d07

See more details on using hashes here.

Provenance

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

This release

0.0.6 This release

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