Metadata-Version: 2.4
Name: prose-formatter
Version: 0.11.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Quality Assurance
Summary: A Python typesetter for the reader.
Keywords: alignment,code-quality,developer-tools,formatter,linter,python,rust,static-analysis,typesetting
Author: Jybbs
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: changelog, https://github.com/Jybbs/prose/releases
Project-URL: homepage, https://prose.fyi
Project-URL: issues, https://github.com/Jybbs/prose/issues
Project-URL: source, https://github.com/Jybbs/prose

<div align="center">
<img src="https://github.com/Jybbs/prose/raw/main/site/public/title-with-tagline.svg" alt="Prose, a Python typesetter for the reader." width="800">

[![Rust](https://github.com/Jybbs/prose/raw/main/site/public/badges/rust.svg)![1.99+](https://img.shields.io/badge/1.99+-8a80cb?style=for-the-badge)](https://www.rust-lang.org/)
[![Python](https://github.com/Jybbs/prose/raw/main/site/public/badges/python.svg)![3.10+](https://img.shields.io/badge/3.10+-8a80cb?style=for-the-badge)](https://www.python.org/)
[![Coverage](https://github.com/Jybbs/prose/raw/main/site/public/badges/coverage.svg)![percent](https://img.shields.io/codecov/c/github/Jybbs/prose?style=for-the-badge&label=&color=8a80cb)](https://codecov.io/gh/Jybbs/prose)
[![Documentation](https://github.com/Jybbs/prose/raw/main/site/public/badges/docs.svg)![Docs](https://img.shields.io/badge/Docs-8a80cb?style=for-the-badge)](https://prose.fyi/)

</div>

---

## 🪻 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, calls, and signatures, alphabetizes methods and fields within their groups, removes padding that lines up with nothing, 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, and a reader's eye moves down a page and across adjacent lines looking for parallels, patterns, and **shape**. The [landing page](https://prose.fyi/) sets out how ***Prose*** restores that shape.

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

```bash
uv tool install prose-formatter
```

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

```bash
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](https://prose.fyi/):

- The [**interactive sandbox**](https://prose.fyi/sandbox/) formats Python live in the browser, so a reader can watch a snippet settle into shape without installing anything.
- The [**rule catalog**](https://prose.fyi/rules/) walks every rule with before/after fixtures and per-facet configuration.
- The [**configuration reference**](https://prose.fyi/reference/configuration) covers the `prose.toml`, `.config/prose.toml`, and `pyproject.toml` config files, the top-level and `[imports]` keys, and the `[rules]` facets.
- The [**cache reference**](https://prose.fyi/reference/cache) covers the cache directory, `--no-cache`, the `[cache]` table, and the `prose cache` subcommands.
- The [**exit-code matrix**](https://prose.fyi/reference/exit-codes) is the contract a CI gate or a pre-commit hook reads.
- [**Suppression directives**](https://prose.fyi/reference/suppression-directives) cover `# prose: off`, `# prose: skip`, and the rest of the directive surface.
- The [**Ruff integration**](https://prose.fyi/integrations/ruff) covers running *Prose* in a project that already runs Ruff.
- [**Editor, pre-commit, and CI integrations**](https://prose.fyi/integrations/) wire *Prose* into the development loop.

---

## 🗜️ Development

*Prose* is a Rust crate that ships as a Python wheel through [**maturin**](https://www.maturin.rs/), with [**mise**](https://mise.jdx.dev) managing the Rust toolchain, Python interpreter, and every supporting CLI through a single mise config. After installing mise and [**activating it in your shell**](https://mise.jdx.dev/installing-mise.html), 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:

```bash
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**](https://prose.fyi/architecture/) 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**](https://prose.fyi/reference/pipeline-order) sets out the fixed order the rules run in and why each rule sits where it does.

