Repolode
Submit
PyCQA

PyCQA/docformatter

A Python command-line tool that automatically reformats docstrings to follow PEP 257 conventions.

View on GitHubWebsite
Stars
600
Forks
99
Open issues
22
Last commit
4 days ago

What is it?

docformatter is a command-line tool for Python that rewrites docstrings so they follow a subset of the PEP 257 conventions. It normalizes quote style, moves the closing quotes onto their own line for multi-line docstrings, separates the summary from the description with a blank line, and removes stray indentation and trailing whitespace.

It can be run in place on individual files or across a project, and it supports a black-compatible mode via the --black option. It also formats field lists written in Epytext or Sphinx styles. Configuration can be read from pyproject.toml, which uses the standard library tomllib on Python 3.11 and later.

Developers who want consistent docstrings across a codebase without editing each one by hand will find it useful, especially when it runs as part of a lint or pre-commit step.

Key features

  • 01Reformats docstrings to follow PEP 257 quoting and layout rules.
  • 02Supports black-compatible output via the --black option.
  • 03Formats Epytext and Sphinx style field lists.
  • 04Can edit files in place with --in-place.
  • 05Reads settings from pyproject.toml.

Use cases

  • Standardizing docstring formatting across a Python project.
  • Enforcing consistent docstrings automatically in a pre-commit hook or CI check.
  • Cleaning up legacy code with inconsistent docstring quotes and indentation.

Quick start

  1. 1

    Install docformatter from PyPI with pip

    pip install --upgrade docformatter
  2. 2

    Format a file's docstrings in place

    docformatter --in-place example.py

In collections

Code linters & formatters

Topics

#python#docstring#formatter#pep-257#code-style#linting#autoformat

FAQ

What is docformatter?
A Python command-line tool that automatically reformats docstrings to follow PEP 257 conventions. docformatter is a command-line tool for Python that rewrites docstrings so they follow a subset of the PEP 257 conventions. It normalizes quote style, moves the closing quotes onto their own line for multi-line docstrings, separates the summary from the description with a blank line, and removes stray indentation and trailing whitespace.
Is docformatter free to use? What license does it have?
docformatter is open source under the MIT license. Check the license terms before using it in commercial products.
Is docformatter still maintained?
Actively maintained. The last commit to docformatter was on Nov 3, 2026.
What can I use docformatter for?
Standardizing docstring formatting across a Python project. Enforcing consistent docstrings automatically in a pre-commit hook or CI check. Cleaning up legacy code with inconsistent docstring quotes and indentation.
How do I install docformatter?
Install docformatter from PyPI with pip: pip install --upgrade docformatter Format a file's docstrings in place: docformatter --in-place example.py
Where can I get docformatter?
The source code and installation instructions are on GitHub: https://github.com/PyCQA/docformatter

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects