docformatter

1.7.7 · active · verified Sat Apr 11

docformatter is a Python tool that automatically formats docstrings to adhere to PEP 257 conventions, ensuring consistent and readable documentation. It handles various aspects like summary line wrapping, blank lines, and multi-line docstring structure. The library is actively maintained, with frequent releases addressing bug fixes and new features, and its current version is 1.7.7.

Warnings

breaking Starting with version 1.7.7, `docformatter` dropped official support for Python versions older than 3.9. Users on older Python environments will need to use a previous version of the library.
Fix: Upgrade to Python 3.9 or newer, or pin `docformatter` to `<1.7.7` in your `requirements.txt`.
gotcha Integrating `docformatter` with complex docstrings, especially those using reStructuredText (reST) or Sphinx-style field lists, can sometimes lead to unexpected formatting or require specific options. The project has had several fixes related to handling Sphinx fields, directives, and wrapping.
Fix: Ensure you are on the latest `docformatter` version. Utilize the `--style` option (e.g., `--style sphinx`) if using a specific docstring style. Consider `--force-wrap` for challenging cases, though it might occasionally produce less-than-ideal output for complex lists. Review the formatted output carefully.
gotcha When used as a `pre-commit` hook, incorrect `rev` or `args` in `.pre-commit-config.yaml` can lead to manifest issues or unexpected behavior. Specifically, older examples might use outdated `rev` values, or miss crucial arguments like `--in-place`.
Fix: Always refer to the latest `docformatter` documentation or its GitHub repository's `.pre-commit-config.yaml` for the recommended `rev` and `args`. Ensure you include `--in-place` if you want the hook to modify files directly, or `--check` if you only want it to report issues without changing files. Run `pre-commit autoupdate` regularly.
gotcha `docformatter`'s `--black` option (introduced in v1.7.0) aims for Black compatibility but may not cover all Black-specific formatting nuances or interactions, as Black primarily focuses on code formatting, not docstrings.
Fix: Upgrade to `docformatter` version 1.7.0 or newer to use the `--black` option for improved compatibility. Always run `docformatter` before `black` in your formatting pipeline if both are used.

Install

pip install docformatter Install stable version
pip install "docformatter[tomli]" Install with tomli (for Python < 3.11 config)

Quickstart

This quickstart demonstrates how to use `docformatter` programmatically via `subprocess` to format a Python file's docstrings. It creates a temporary file, runs `docformatter --in-place` on it, and then prints the formatted content before cleaning up.

import subprocess
import os

# Create a dummy Python file with unformatted docstrings
code_to_format = '''
def my_function(arg1, arg2):
    """This is a very long and unformatted summary line that definitely exceeds the default wrap length of 79 characters.

    This is the description. It also needs to be wrapped. It contains details about arg1 and arg2.
    :param arg1: The first argument.
    :type arg1: int
    :param arg2: The second argument.
    :type arg2: str
    """
    pass

class MyClass:
    """A class with a simple docstring.  It needs to be formatted."""
    def __init__(self):
        pass
'''

file_path = "example_docstrings.py"
with open(file_path, "w") as f:
    f.write(code_to_format)

print(f"Original file '{file_path}':\n---\n{code_to_format}---\n")

# Run docformatter to format the file in-place
try:
    # Using --recursive (or -r) is good practice for multiple files/directories
    # Using --in-place (or -i) makes changes directly to the file
    result = subprocess.run(["docformatter", "--in-place", file_path], check=True, capture_output=True, text=True)
    if result.stdout:
        print(f"docformatter output (stdout):\n{result.stdout}")
    if result.stderr:
        print(f"docformatter errors (stderr):\n{result.stderr}")

    # Read the formatted content
    with open(file_path, "r") as f:
        formatted_code = f.read()
    print(f"Formatted file '{file_path}':\n---\n{formatted_code}---\n")

except subprocess.CalledProcessError as e:
    print(f"Error running docformatter: {e}")
    print(f"stdout: {e.stdout}")
    print(f"stderr: {e.stderr}")
finally:
    # Clean up the dummy file
    if os.path.exists(file_path):
        os.remove(file_path)
        print(f"Cleaned up '{file_path}'.")

view raw JSON →