prose-formatter 0.10.2

🪻 About

Prose formats Python source to be legible at a glance. It aligns equals signs and colons vertically across consecutive lines, places one entry per line in dictionaries and lists, alphabetizes methods and fields within their groups, applies a singleton rule for colon padding, and treats code like prose rather than minified text.

🗞️ Philosophy

Code is read far more often than it is written. A reader's eye moves down a page and across adjacent lines looking for parallels, patterns, and shape. When every = sits at a different column and every collection is compressed onto one line, that shape disappears, forcing the eye to slow down. Prose restores it, with aligned columns letting the eye skim, one-per-line collections making each entry a unit, and alphabetized groupings giving every reader the same landmarks.

The trade-offs minimalist formatters were built to avoid (wider diffs, more vertical scrolling, occasional re-alignment churn) no longer dominate the equation. Agentic assistants do much of the typing, and every modern code host offers whitespace-ignoring diffs. What remains is the daily experience of reading code.

🪄 Install & Usage

uv tool install prose-formatter

The binary exposes format, check, rules, server, cache, completions, and schema:

prose format path/             # rewrite files in place
prose check path/              # exit non-zero on violations
prose format --diff path/      # show the diff without writing
prose check --stdin < file.py  # read from stdin
prose format - < file.py       # `-` reads from stdin too
prose rules                    # list the rules in pipeline order
prose schema                   # print the config's JSON Schema
prose server                   # language server over stdio

📰 Further Reading

The full edition lives at prose.fyi:

• The interactive sandbox formats Python live in the browser, so a reader can watch a snippet settle into shape without installing anything.
• The rule catalog walks every rule with before/after fixtures and per-facet configuration.
• The configuration reference covers the prose.toml, .config/prose.toml, and pyproject.toml config files, every key, and the [rules] toggles.
• The cache reference covers the cache directory, --no-cache, the [cache] table, and the prose cache subcommands.
• The exit-code matrix is the contract CI gates and pre-commit hooks compile against.
• Suppression directives cover # prose: off, # prose: skip, and the rest of the directive surface.
• Composition with Ruff pairs the token-level formatter with prose format.
• Editor, pre-commit, and CI integrations wire Prose into the development loop.

🗜️ Development

Prose is a Rust crate that ships as a Python wheel through maturin, with mise managing the Rust toolchain, Python interpreter, and every supporting CLI through a single mise config. After installing mise and activating it in your shell, the rest provisions from a clone. mise doctor project then reports anything a build still needs beyond the tools, each beside the command that supplies it:

git clone https://github.com/Jybbs/prose.git
mise trust prose
mise -C prose install
cd prose
mise doctor project

Once mise's shell hook has put .mise/bin on the path, a bare prose inside the checkout runs the checkout's own build rather than an installed release.

mise tasks lists every available task, and mise ci runs the full local sweep that mirrors GitHub Actions. The contributor guide at .github/CONTRIBUTING.md walks a change from setting up a clone and filing or picking up an issue, through the fixture case a fix is reviewed against and the commit, to the pull request and the checks that run on it.

For the architecture, the architecture section walks the types and modules Prose is built from, setting the public Source, Pipeline, and RuleId beside the shared pieces every rule is composed from, and the pipeline order explains how each rule reads a settled AST between reparses.