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 the baseline rules in pyproject.toml:

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

Then check the current directory:

gruff check .

All rules are opt-in. Each rule belongs to a tier that states what adopting it costs. Start with the baseline rules, then add opinionated rules one code at a time. GR:baseline, GR:opinionated, and GR:api-shaping select a whole tier. GR enables every Gruff rule, including the API-shaping tier. 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.

Baseline

Few projects disagree with these rules. A fix usually stays inside one module, but GR004 can rename a constant that other code imports, and a GR014 fix renames a name across modules.

Opinionated

These rules take a style position that some projects reject. A fix usually stays inside the project, but GR012's getter-only property fix stops outside code from assigning the attribute.

API-shaping

Fixing a finding changes a public signature, which can break callers outside the project. On a published library, adopt these rules with a major release.

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 and its tier 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.