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
signature-layout  = false
alphabetize       = false
docstring-expand  = false
docstring-wrap    = false
blank-lines       = false
collection-layout = 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. 30 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

align-colons

— 02

Docs

Docstrings join the same legibility discipline as code. Wrap to the project line length, keep single-line shapes single-line, multi-line shapes multi-line, and quote style consistent throughout.

01 02 03

docstring-expand

— 03

Formatting

Trailing commas come off, blank lines snap to canonical counts, empty grouping parentheses 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

blank-lines

— 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

call-layout

— 05

Lint

Legacy union syntax, reassigned constants, step-narration comments, bare-import patterns, and single-use bindings surface as diagnostics. The formatter never rewrites these, because the fix belongs to the reader.

01 02 03 04 05 06 07 08 09

bare-imports

— 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

alphabetize

— 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

align-colons

— 02

Docs

Docstrings join the same legibility discipline as code. Wrap to the project line length, keep single-line shapes single-line, multi-line shapes multi-line, and quote style consistent throughout.

01 02 03

docstring-expand

— 03

Formatting

Trailing commas come off, blank lines snap to canonical counts, empty grouping parentheses 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

blank-lines

— 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

call-layout

— 05

Lint

Legacy union syntax, reassigned constants, step-narration comments, bare-import patterns, and single-use bindings surface as diagnostics. The formatter never rewrites these, because the fix belongs to the reader.

01 02 03 04 05 06 07 08 09

bare-imports

— 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

alphabetize

The Workflow

Open with these few lines.

Install

Fetch the wheel and expose the prose binary.

bash

uv tool install prose-formatter

Configure

Drop 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 pair with Ruff for the token-level surface Prose doesn't touch.

bash

ruff format && prose format

The Lineage

Standing on giants.

GitHub ActionsCI RustImplementation uvInstall path miseTool versions RuffParser & AST