Latest docstrfmt Version Supported Python Versions PyPI - Downloads - Monthly Coveralls Coverage Github Actions Coverage Contributor Covenant

Strongly inspired by rstfmt and rustfmt.

This is considered to be in beta however it is mostly stable.

Description

docstrfmt is a tool for automatically formatting reStructuredText in files and Python docstrings in a consistent way.

Like Black and rstfmt, the motivation is to provide a format that is reasonable and minimally configurable to prevent teams from wasting time on style discussions (or individuals on manually doing formatting, for that matter).

Currently, docstrfmt is in an early stage of development. The most common reST constructs are covered but there are some that are not. If there is a construct missing and would like to add it, feel free to open a PR to add it or open an issue and I’ll see what I can do.

To get a feel for the output of docstrfmt, see the sample file.

Differences between docstrfmt and rstfmt

The main difference between rstfmt and docstrfmt is the ability to format Python docstrings. I am open to merging this project with rstfmt, however, there as several differences in formatting conventions between the two (hence the separate fork).

Usage

# Install.
pip install docstrfmt

# Install the development version.
pip install https://github.com/LilSpazJoekp/docstrfmt/archive/master.zip

# Read a file from stdin and write the formatted version to stdout.
docstrfmt

# Format the given file(s) in place.
docstrfmt <file>...

# Format the given files, printing all output to stdout.
docstrfmt -o <file>...

# Wrap paragraphs to the given line length where possible (default to whatever is
# set for black).

docstrfmt -l <length>

Like Black’s blackd, there is also a daemon that provides formatting via HTTP requests to avoid the cost of starting and importing everything on every run.

# Install.
pip install "docstrfmt[d]"

# Install the development version.
pip install "https://github.com/LilSpazJoekp/docstrfmt/archive/master.zip#egg=docstrfmt[d]"

# Start the daemon (binds to localhost:5219 by default).
docstrfmtd --bind-host=<host> --bind-port=<port>

# Print the formatted version of a file.
curl http://locahost:5219 --data-binary @<file>

# Specify the line length (default to whatever is set for black).
curl -H 'X-Line-Length: 72' http://locahost:5219 --data-binary @<file>

# Mimic the standalone tool: read from stdin, write to stdout, exit with
# a nonzero status code if there are errors.
curl -fsS http://locahost:5219 --data-binary @/dev/stdin

With Editors

PyCharm

Instructions derived from black documentation

  1. Install.

    pip install "docstrfmt[d]"

  2. Locate where docstrfmt is installed.

    • On macOS / Linux / BSD:

      which docstrfmt
# /usr/local/bin/docstrfmt  # possible location

    • On Windows:

      where docstrfmt
# C:\Program Files\Python39\Scripts\docstrfmt.exe

  1. Open External tools in PyCharm.

    • On macOS:

      PyCharm -> Preferences -> Tools -> External Tools

    • On Windows / Linux / BSD:

      File -> Settings -> Tools -> External Tools

  2. Click the + icon to add a new external tool with the following values:

    • Name: docstrfmt

    • Description:

    • Program: <install_location_from_step_2>

    • Arguments: "$FilePath$"

  3. Format the currently opened file by selecting Tools -> External Tools -> docstrfmt.

    • Alternatively, you can set a keyboard shortcut by navigating to Preferences or Settings -> Keymap -> External Tools -> External Tools - docstrfmt.

  4. Optionally, run docstrfmt on every file save:

    1. Make sure you have the File Watchers plugin installed.

    2. Go to Preferences or Settings -> Tools -> File Watchers and click + to add a new watcher:

      • Name: docstrfmt

      • File type: Python

      • Scope: Project Files

      • Program: <install_location_from_step_2>

      • Arguments: $FilePath$

      • Output paths to refresh: $FilePath$

      • Working directory: $ProjectFileDir$

    3. Uncheck “Auto-save edited files to trigger the watcher” in Advanced Options

With pre-commit

repos:
  - repo: https://github.com/LilSpazJoekp/docstrfmt
    rev: stable # Replace by any tag/version: https://github.com/LilSpazJoekp/docstrfmt/tags
    hooks:
      - id: docstrfmt
        language_version: python3
        types_or: [python, rst, txt] # only needed if you want to include txt files.

Contributing

See CONTRIBUTING.rst for detailed information about setting up a development environment and contributing to the project.

Project links

Data verified by PyPI on Aug 28, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for bboe from gravatar.com bboe Avatar for Lil_SpazJoekp from gravatar.com Lil_SpazJoekp

Credits

Author/Maintainer: Joel Payne

GitHub Statistics

Data verified by PyPI on Aug 28, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License

Requires

Python >=3.10

Provides Extra

d

Tags

black docutils autoformatter formatter lint restructuredtext rst sphinx

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

docstrfmt-2.2.1.tar.gz (43.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

docstrfmt-2.2.1-py3-none-any.whl (43.4 kB view details)

Uploaded Python 3

File details

Details for the file docstrfmt-2.2.1.tar.gz.

File metadata

  • Download URL: docstrfmt-2.2.1.tar.gz
  • Upload date:
  • Size: 43.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for docstrfmt-2.2.1.tar.gz
Algorithm Hash digest
SHA256 9f35b62e746962efe32f7af27b3bf69e104a4e69827a49a9f488da770271bd0e
MD5 1a41b8164a0840123438851569f0f87a
BLAKE2b-256 d183d25208b56d831925ef13534c110ab445a04af01c882805f88c996651d803

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstrfmt-2.2.1.tar.gz:

Publisher: pypi.yml on LilSpazJoekp/docstrfmt

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file docstrfmt-2.2.1-py3-none-any.whl.

File metadata

  • Download URL: docstrfmt-2.2.1-py3-none-any.whl
  • Upload date:
  • Size: 43.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for docstrfmt-2.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 a0a9962dbd64684b9bea2af582c631ae174d06850cd960eb37221dd6a0d6cdc4
MD5 a475ec1dca13cd106e962576883b7e13
BLAKE2b-256 585b4e0bcef7ae9bf9725bf5617b51dc03783eb777b5d35c84252b76012a1726

See more details on using hashes here.

Provenance

The following attestation bundles were made for docstrfmt-2.2.1-py3-none-any.whl:

Publisher: pypi.yml on LilSpazJoekp/docstrfmt

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

2.2.1 This release

2 files

2.2.0

2 files

2.1.1

2 files

2.1.0

2 files

2.0.2

2 files

2.0.1

2 files

2.0.0

2 files

1.11.1

2 files

1.11.0

2 files

1.10.0

2 files

1.9.0

2 files

1.8.0

2 files

1.7.0

2 files

1.6.1

2 files

1.6.0

2 files

1.5.1

2 files

Yanked

1.5.1.dev0

2 files

Yanked reason: Accidental release

1.5.0

2 files

1.4.4

2 files

1.4.3

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.3.0

2 files

1.2.0

2 files

1.1.4

2 files

1.1.3

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.3

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

Pre-release

1.0.0rc0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page