Prose

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
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, full_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-trace-id": "abc-123"}
        base_url = "https://example.com"
        return {"url": f"{base_url}/{full_endpoint_url}"}

The Idea

Code, made legible.

The Surfaces

5 rule families. 22 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

align-colons

— 02

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

alphabetize

— 03

Formatting

Dictionaries, lists, and sets expand to one entry per line. Multi-line collections drop their trailing comma, blank lines snap to canonical counts, and singletons collapse to their natural form.

01 02 03 04 05 06 07 08

blank-lines

— 04

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

— 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

bare-imports

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, 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