docstrfmt

What it is and what it does

docstrfmt is a command-line tool that automatically formats reStructuredText markup and Python docstrings to a consistent, opinionated style. It draws inspiration from Black and rstfmt, aiming to reduce style discussions and manual formatting work by enforcing a single reasonable format. The tool reads Python files or raw reStructuredText and rewrites docstrings and markup according to its rules, with configurable line length that defaults to Black's 88 characters or can be read from pyproject.toml.

The package depends on Black, libcst, docutils, Sphinx, and related utilities to parse and reformat the text. It runs as a command-line tool or optionally as an HTTP daemon (docstrfmtd) to avoid repeated startup costs. Currently in beta, it covers most common reStructuredText constructs but acknowledges gaps in coverage for less common syntax.

Use it for:

• Enforce consistent docstring formatting across a Python project's codebase automatically.
• Integrate docstring formatting into pre-commit hooks to catch style issues before commit.
• Format standalone reStructuredText files (e.g., documentation, README files) to match project conventions.
• Run as a daemon service to format docstrings on-demand via HTTP in editor plugins or CI pipelines.
• Migrate existing docstrings to a standardized format without manual editing.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Automatically formats reStructuredText in files and Python docstrings to a consistent style, similar to how Black formats Python code.

Yes, if you work with reStructuredText or Sphinx-style docstrings and want automated, opinionated formatting. The low install friction, active maintenance, permissive license, and zero known vulnerabilities make it a safe choice. The beta status and acknowledged gaps in construct coverage are worth noting if you rely on advanced reStructuredText features, but for typical docstrings and markup it is stable and ready to use.

Install

docstrfmt on PyPI

pip install docstrfmt

uv add docstrfmt

poetry add docstrfmt

Installing docstrfmt

Before you install

Low friction: pure Python wheel with no compiled dependencies. Active maintenance, last commit 2026-08-10, and the project is in beta but described as mostly stable.

License in practice

Permissive license (MIT) means you can use, modify, and distribute this package freely in commercial and private projects without significant restrictions.

Quickstart

pip install docstrfmt

docstrfmt myfile.py
# or read from stdin and write to stdout:
cat myfile.py | docstrfmt

Requires Python 3.10 or later.

Verify before relying

• Coverage of less common reStructuredText constructs beyond the most common ones mentioned as currently supported.
• Performance characteristics when formatting large files or many files in batch.
• Stability guarantees or breaking-change policy given the beta status.

Package facts

Evidence: docstrfmt-2.2.0-py3-none-any.whl

Keywords: black, docutils, autoformatter, formatter, lint, restructuredtext, rst, sphinx

Tags

More Utilities packages