tooprolix 0.5.4

Deterministic linter for overlong and duplicated prose in Python comments and docstrings.

tooprolix

Less narration. More signal.
Deterministic control over comments and docstrings in Python repositories.

Coding agents over-explain. Comments grow into essays, docstrings restate the code, and the same rationale quietly spreads across five files. tooprolix turns that into TPX diagnostics you can act on. It reads only comments and docstrings, never rewrites your why, and leaves the call to you.

Quick start

Run tooprolix without installing it with uv:

$ uvx tooprolix check .
src/config.py:1-26: TPX002 docstring is 243 words long, over the 200-word limit — shorten it, or mark it with `# !TPX002` on the line above it
Found 1 findings (TPX002: 1).

Each finding points to path:start-end, so you know how big the block is before you open it.

For an existing uv project, pin the tool as a development dependency and run it through uv:

$ uv add --dev tooprolix
$ uv run tooprolix check .

And when the whole tree came back clean:

$ uvx tooprolix check .
All checks passed!

Exit codes are the contract: 0 clean, 1 findings, 2 could not start. A tree that was not read whole never exits 0. See the CLI contract.

Rules at a glance

Code	Detects	Status
TPX001	A comment run longer than its word limit	Released
TPX002	A docstring longer than its word limit	Released
TPX003	One explanation repeated across comments and docstrings, reported once with every place it appears	Released
TPX004	Comments that restate the following code	Reserved

tooprolix --rules prints this table; tooprolix --version prints the version and the date of the commit it was built from.

Some prose earns its length. Put a marker on the line directly above the block:

# !TPX003
# The retry contract is restated here on purpose, so this module can be read on
# its own without opening the client it talks to.

Several codes, blanket suppression, and repository-wide config live in rules and configuration.

Validation

Rules are exercised on six pinned real repositories agent frameworks and mature libraries not only synthetic fixtures. Every threshold is read off that corpus rather than chosen by taste, and critical guards are mutation-proved: a test that stays green when its guarantee is broken is deleted, not kept for the count.

Why tooprolix

• Repository-wide. It finds one explanation repeated across otherwise unrelated files.
• Deterministic. The same source produces the same ordered findings, byte for byte.
• Local. No model calls, no network, no probabilistic output.

Documentation

CLI and exit-code contract	Addresses, output channels, colour, exit codes, JSON schema
Rules and configuration	Thresholds, suppression markers, pyproject.toml
corpus/REPORT.md	The corpus, the measurements, the open questions
CONTRIBUTING.md	Toolchain, gates, commit and release conventions

Contributing

Run make help for the task list, and see CONTRIBUTING.md for the toolchain and the gates CI requires.