tooprolix

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

PyPI Python Powered by Rust

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.

Project links

Data verified by PyPI on
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.5.4)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for sgolyshevskii from gravatar.com sgolyshevskii

GitHub Statistics

Data verified by PyPI on 
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.11

Tags

comments docstrings linter prose python

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 Distribution

tooprolix-0.5.2.tar.gz (468.8 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

tooprolix-0.5.2-py3-none-win_amd64.whl (1.6 MB view details)

Uploaded Python 3Windows x86-64

tooprolix-0.5.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.7 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

tooprolix-0.5.2-py3-none-macosx_11_0_arm64.whl (1.6 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

File details

Details for the file tooprolix-0.5.2.tar.gz.

File metadata

  • Download URL: tooprolix-0.5.2.tar.gz
  • Upload date:
  • Size: 468.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for tooprolix-0.5.2.tar.gz
Algorithm Hash digest
SHA256 b2bb71fb767a52e1ca15e541580a4894aacf9f8cea286c826a25c3ae87c93ff1
MD5 c7a3407ebc62f2a498e3048628d9783f
BLAKE2b-256 353566fe7e921c0331b1d1aead7deb515de072b4b6c89dae568782cf7ec899cf

See more details on using hashes here.

Provenance

The following attestation bundles were made for tooprolix-0.5.2.tar.gz:

Publisher: build-artifacts.yml on golyshevskii/tooprolix

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tooprolix-0.5.2-py3-none-win_amd64.whl.

File metadata

  • Download URL: tooprolix-0.5.2-py3-none-win_amd64.whl
  • Upload date:
  • Size: 1.6 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 tooprolix-0.5.2-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 7018b7d94a38c9269db8558aeea539db29dd4f302c7d5830e9438a8a56600ee0
MD5 da60d1738bcb516a948bc3f42c5f50bb
BLAKE2b-256 ac37f9b3dc473cb899681efea077a268ce37e1328e515dae5d77c8cede40c817

See more details on using hashes here.

Provenance

The following attestation bundles were made for tooprolix-0.5.2-py3-none-win_amd64.whl:

Publisher: build-artifacts.yml on golyshevskii/tooprolix

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tooprolix-0.5.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for tooprolix-0.5.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 15ef287b5bf81ab92e54a467ec0d58730f080a44e8edc0885eb916bb9a4ff7c4
MD5 a222f4d5c844e056948b188c758876b8
BLAKE2b-256 390e9e232e02f5a28b9f524a7a8a7ae61bca8e609e65330fbe78c0695c28c547

See more details on using hashes here.

Provenance

The following attestation bundles were made for tooprolix-0.5.2-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: build-artifacts.yml on golyshevskii/tooprolix

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file tooprolix-0.5.2-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for tooprolix-0.5.2-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 8963da99349ca5d3adbd8236a95ab3fe457e51e6a20e52a1a96d781d4c4e1adf
MD5 ffe4a3c96bc7f698266a7047f992a867
BLAKE2b-256 eaa20cea686a0409ff2cc4c48c2871c585ac1ab1445bb0607a4ab8549865b5ea

See more details on using hashes here.

Provenance

The following attestation bundles were made for tooprolix-0.5.2-py3-none-macosx_11_0_arm64.whl:

Publisher: build-artifacts.yml on golyshevskii/tooprolix

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page