The Proof

From cramped to composed.

prose.toml

code-line-length      = 88
docstring-line-length = 76
target-version        = "3.13"

# Rules are on by default.
# All 'true' values are just for show.
[rules]
align-equals         = false
align-colons         = false
align-imports        = false
reflow-signatures    = false
alphabetize-siblings = false
expand-docstrings    = false
wrap-docstrings      = false
space-statements     = false
reflow-collections   = false

app.py

from pathlib import Path
from dataclasses import dataclass
@dataclass(kw_only=True)
class Config:
    """Connection knobs read at startup from the project's pyproject.toml, with command-line overrides applied last."""
    timeout: int | None = None
    name: str = "service"
    debug: bool = False
    def build_request(self, db: str, fully_qualified_endpoint_url: str, body: dict, timeout: int = 30, headers: dict | None = None,) -> dict:
        """Build a configured request with per-call overrides."""
        headers_map = {"x-api-key": "secret", "accept": "application/json", "x-request-correlation-id": "abc-123"}
        base_url = "https://example.com"
        return {"url": f"{base_url}/{fully_qualified_endpoint_url}"}

The Idea

Code, made legible.

The Surfaces

6 rule families. 43 rules.

All rules

— 01

Alignment

Equals signs, colons, the import keyword, and match arrows line up across consecutive lines. The eye drops down the column.

01 02 03 04 05 06 07

— 02

Docs

Docstrings follow the same legibility discipline as code. Wrap to the docstring budget, put a one-line docstring's opener, body, and closer on lines of their own, and keep the quote style consistent throughout.

01 02 03

— 03

Formatting

Trailing commas come off, blank lines snap to canonical counts, backslash continuations and redundant -> None annotations fall away, and a stale __future__ import is removed once nothing needs it. The scaffolding clears after the shape is set.

01 02 03 04 05 06 07 08 09 10 11 12 13

— 04

Layout

Calls, signatures, collections, and from-imports that outgrow the line budget explode to one entry per line. Each argument, key, or name lands on its own row, so the eye reads down the column and a later edit touches a single line.

01 02 03 04 05 06 07

— 05

Lint

Missing signature annotations, reassigned constants, step-narration comments, bare imports, and bindings whose value inlines for free are reported as findings. The formatter never rewrites these, because the fix belongs to the reader.

01 02 03 04 05 06 07 08 09 10

— 06

Ordering

Sibling entries sort into a predictable order. Imports, dictionary keys, and set members read top-to-bottom by name, so a reader looking for an entry already knows where it sits.

01 02 03

The Workflow

Open with these few lines.

Install

Install the wheel, which puts the prose binary on PATH.

bash

uv tool install prose-formatter

Configure

Write a prose.toml at the project root, a .config/prose.toml, or a [tool.prose] table in pyproject.toml. The defaults already work.

toml

target-version = "3.13"

Run

Rewrite in place, or check without writing.

bash

prose format path/
prose check path/

Compose

Optionally run Ruff too, for the token-level formatting Prose leaves alone.

bash

ruff format path/ && prose format path/

The Lineage

Standing on giants.

GitHub ActionsCI RustImplementation uvInstall path miseTool versions RuffParser & AST

Read on

Bring Prose to your own pages and make the next save legible.

uv tool install prose-formatter

Quick start