docformatter Documentation

The primary goal of docformatter is to act as an autoformatting tool that produces PEP 257 compliant docstrings.

It focuses on two main categories of requirements derived from PEP 257:

1. Convention Requirements: These are the structural rules (the "shall" requirements) that ensure docstrings can be properly processed by tools like Docutils or pydocstyle. docformatter aims to satisfy all absolute convention requirements.
2. Methodology Requirements: These relate to the actual content of the docstring. While harder to automate, docformatter aims to support these and provides arguments to allow users to toggle specific methodology requirements on or off.

By following these conventions, docformatter ensures your docstrings are structurally sound for the Python ecosystem.

docformatter applies specific interpretations and exceptions to PEP 257 to improve usability and maintain consistency with common styles:

• Punctuation: One-line and summary lines can end with any of [. ! ?]. This is an exception to PEP 257 to remain consistent with Google style.
• Capitalization: docformatter automatically capitalizes the first word of one-line and summary lines.
  • Exception: It preserves the case of the first word if it is a variable or filename.
  • Exception: It preserves the case of user-specified words (e.g., proper nouns like docformatter) via a user option.
• Closing Quotes: For wrapped one-liners, docformatter can be configured to place closing quotes on a line by themselves, interpreting the PEP 257 requirement for multi-line docstrings as applicable to wrapped one-liners.

docformatter supports formatting for several common docstring styles. When a specific style is selected, the tool will ignore docstrings written in other styles to avoid incorrect formatting.

Supported styles include:

• NumPy style
• Google style
• Sphinx style: Includes logic to ensure one blank space between a field name and field body, while respecting special cases like links or empty field bodies.
• Epytext style
• Black compatible mode: Wraps summaries and descriptions at 88 characters by default and handles specific quoting behaviors to match black formatting.

docformatter is designed to automate PEP 257 compliance. It implements most core PEP 257 conventions, including the use of triple double quotes ("""), raw strings for backslashes (r"""), and unicode strings (u""").

It also handles specific PEP 257 requirements for:

• One-line docstrings: Ensuring they fit on a single line, use triple quotes, and have closing quotes on the same line.
• Multi-line docstrings: Managing summary lines, blank lines, and indentation.

Note that some PEP 257 methodology requirements (like specific content for class, module, or function docstrings) are not enforced by docformatter, as these are semantic/content-based rather than purely stylistic.

To ensure docformatter recognizes and correctly formats complex text patterns (like lists, parameter descriptions, and reStructuredText sections), your docstrings must strictly follow established specifications.

If docstrings do not follow these patterns, docformatter may treat them as simple text, leading to incorrect indentation or wrapping. Supported specifications include:

• PEP 257: Docstring Conventions
• reStructuredText (reST): Markup Specification
• Sphinx: Documentation Style
• Epydoc: Documentation Style

You can install the latest released version of docformatter using pip.

$ pip install --upgrade docformatter

You can install docformatter via pip.

If you intend to use pyproject.toml for configuration and are using a Python version older than 3.11, you must install the [tomli] extra to provide TOML parsing support. For Python 3.11 and later, tomllib is included in the standard library and no extra is needed.

You can also install specific release candidates or tags directly from GitHub.

# Standard installation
$ pip install --upgrade docformatter

# Installation with tomli support (required for Python < 3.11 when using pyproject.toml)
$ pip install --upgrade docformatter[tomli]

# Install a specific release candidate or tag from GitHub
$ pip install git+https://github.com/PyCQA/docformatter.git@<RC_TAG>

To integrate docformatter into your pre-commit workflow, add the following to your .pre-commit-config.yaml.

Note that if you use --in-place, the commit will fail because pre-commit detects that the hook modified the files. If you use --check, the commit will fail because docformatter returns a non-zero exit code when formatting is required.

If you are using pyproject.toml for configuration, you must include tomli in additional_dependencies.

- repo: https://github.com/PyCQA/docformatter
  rev: v1.7.5
  hooks:
    - id: docformatter
      additional_dependencies: [tomli]
      args: [--in-place, --config, ./pyproject.toml]

To install an unreleased version or a specific version from GitHub, use pip with the git URL. You can specify a tag or a commit SHA.

$ python -m pip install git+https://github.com/PyCQA/docformatter.git@v1.5.0-rc1

If you intend to use pyproject.toml for configuration, you must install the [tomli] extra if you are using a Python version older than 3.11. For Python 3.11 and later, docformatter uses the standard library's tomllib, so no extra installation is required.

$ pip install --upgrade docformatter[tomli]