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

code-quality comments docstrings duplicate-prose linter prose python python-linter static-analysis

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.3.tar.gz (472.7 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.3-py3-none-win_amd64.whl (1.7 MB view details)

Uploaded Python 3Windows x86-64

tooprolix-0.5.3-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.3-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.3.tar.gz.

File metadata

  • Download URL: tooprolix-0.5.3.tar.gz
  • Upload date:
  • Size: 472.7 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.3.tar.gz
Algorithm Hash digest
SHA256 5d5d1c96d5d328696d6d0c88ee59ad40ae8a51f9946a6db20cf40b45df7d8b21
MD5 dd63e304dcc20f543b108aad6f7d126a
BLAKE2b-256 bf21e4b807d6b0a8676a4adea8a2b43bf7f30ccdabd79ccaa1887cef077a041a

See more details on using hashes here.

Provenance

The following attestation bundles were made for tooprolix-0.5.3.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.3-py3-none-win_amd64.whl.

File metadata

  • Download URL: tooprolix-0.5.3-py3-none-win_amd64.whl
  • Upload date:
  • Size: 1.7 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.3-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 7dac5fd2c66f38dc2e23e1049c02d1ed431fab7da59e146515b29e63047c657b
MD5 1170438c61e016185442d0e7722806ab
BLAKE2b-256 f76a4a89484ad342280a4fd86935549e8d1198d6ebceee407a7c054349052287

See more details on using hashes here.

Provenance

The following attestation bundles were made for tooprolix-0.5.3-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.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for tooprolix-0.5.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 9e20a301b1594b51794d1224dd00cc530d8e2ec6fa38ba334b6ae0b88c5465ec
MD5 f09690f9cacf5a0fd241270c7a94f43f
BLAKE2b-256 24dfc22d16fd714e98504a6f3298a91c8392755770fe6818304635e3b9db7ad3

See more details on using hashes here.

Provenance

The following attestation bundles were made for tooprolix-0.5.3-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.3-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for tooprolix-0.5.3-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ed94df4efdf9137449e5253ece92062ff03fab0c87c9668a6114b3b770d9bcdf
MD5 4f4c8f9cab964d94cb310c6c47bd5586
BLAKE2b-256 36e765658dd160a0215069b38230d9251d15f504eaff66cce9da40407f3072a0

See more details on using hashes here.

Provenance

The following attestation bundles were made for tooprolix-0.5.3-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