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

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 eleven 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, a non-public module binding is easier to find when it lives in the one definition that reads it, and public instance data is easier to review when properties declare its interface.

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.