---

🪻 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.

Note

Prose is still pre-1.0. The rule catalog and configuration facets continue to grow across release lines.

---

🗞️ 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:

git clone https://github.com/Jybbs/prose.git
cd prose
mise install
mise x -- uv venv crate/.venv

mise tasks lists every available task, and mise ci runs the full local sweep that mirrors GitHub Actions. CONTRIBUTING.md at the repository root walks from a bug report to the fixture case a fix is reviewed against, and covers the branch and pull-request flow.

For the architecture, the primitive surface walks every public type (Source, Pipeline, BindingAnalysis, SuppressionMap, RuleId, Edit), and the pipeline order explains how each rule reads a settled AST between reparses.