#TPX

tooprolix

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

PyPI Powered by Rust Python

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

Install tooprolix with uv:

$ uv add tooprolix

Then:

$ 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
src/client.py:14-31: TPX003 same explanation in 3 places: src/poller.py:38-52, src/worker.py:91-104 (weakest src/client.py:14-31 ~ src/worker.py:91-104, similarity 0.812)

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

And when the whole tree came back clean:

$ 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.1.tar.gz (467.2 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.1-py3-none-win_amd64.whl (1.6 MB view details)

Uploaded Python 3Windows x86-64

tooprolix-0.5.1-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.1-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.1.tar.gz.

File metadata

  • Download URL: tooprolix-0.5.1.tar.gz
  • Upload date:
  • Size: 467.2 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.1.tar.gz
Algorithm Hash digest
SHA256 544fe1141cbe72c94c70b2450effcfcb29250c27fd9866c829009310ebf5f5c0
MD5 e5278d4df4b93685da19378e2673e0e6
BLAKE2b-256 7f3c6186e540e8317a2f737969806bff4b4f4fdd33d3b9c5e192862a590fe3e2

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: tooprolix-0.5.1-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.1-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 10327ba43ba7808def173ee67474bdfd8392a068b374d89ea5a574563bae8a30
MD5 85c424ae8625b1723e6cf2297120abed
BLAKE2b-256 93c0711b8e664201dc81ace65b0bca494a61ec3a2b67df4fa93e75b69870afbb

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for tooprolix-0.5.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 a749f471a12ecf1fa2ec9f8935b99b32216c416f2753722c649849f4ccf0bf94
MD5 4298bf4e28a860a89eea29ccb4c1dbd8
BLAKE2b-256 39474b721cd4523818868427cb0becadcbda303adc78676091364734f8bb622f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for tooprolix-0.5.1-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f899bcadf1af7ec9473b56aa873375613ec7425720939ccfdd2cc8286e079b76
MD5 906773b005bca19e1e2901069d4eff9a
BLAKE2b-256 6edb433663d40a37adae8034df58000c5fba1ee01696f6ac798d352c1d54b374

See more details on using hashes here.

Provenance

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