{"id":3977,"library":"docformatter","title":"docformatter","description":"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.","status":"active","version":"1.7.7","language":"en","source_language":"en","source_url":"https://github.com/PyCQA/docformatter","tags":["formatter","linter","code quality","docstrings","pep257","pre-commit"],"install":[{"cmd":"pip install docformatter","lang":"bash","label":"Install stable version"},{"cmd":"pip install \"docformatter[tomli]\"","lang":"bash","label":"Install with tomli (for Python < 3.11 config)"}],"dependencies":[{"reason":"Required for parsing pyproject.toml configuration on Python versions older than 3.11. For Python 3.11+ `tomllib` from the standard library is used.","package":"tomli","optional":true}],"imports":[],"quickstart":{"code":"import subprocess\nimport os\n\n# Create a dummy Python file with unformatted docstrings\ncode_to_format = '''\ndef my_function(arg1, arg2):\n    \"\"\"This is a very long and unformatted summary line that definitely exceeds the default wrap length of 79 characters.\n\n    This is the description. It also needs to be wrapped. It contains details about arg1 and arg2.\n    :param arg1: The first argument.\n    :type arg1: int\n    :param arg2: The second argument.\n    :type arg2: str\n    \"\"\"\n    pass\n\nclass MyClass:\n    \"\"\"A class with a simple docstring.  It needs to be formatted.\"\"\"\n    def __init__(self):\n        pass\n'''\n\nfile_path = \"example_docstrings.py\"\nwith open(file_path, \"w\") as f:\n    f.write(code_to_format)\n\nprint(f\"Original file '{file_path}':\\n---\\n{code_to_format}---\\n\")\n\n# Run docformatter to format the file in-place\ntry:\n    # Using --recursive (or -r) is good practice for multiple files/directories\n    # Using --in-place (or -i) makes changes directly to the file\n    result = subprocess.run([\"docformatter\", \"--in-place\", file_path], check=True, capture_output=True, text=True)\n    if result.stdout:\n        print(f\"docformatter output (stdout):\\n{result.stdout}\")\n    if result.stderr:\n        print(f\"docformatter errors (stderr):\\n{result.stderr}\")\n\n    # Read the formatted content\n    with open(file_path, \"r\") as f:\n        formatted_code = f.read()\n    print(f\"Formatted file '{file_path}':\\n---\\n{formatted_code}---\\n\")\n\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error running docformatter: {e}\")\n    print(f\"stdout: {e.stdout}\")\n    print(f\"stderr: {e.stderr}\")\nfinally:\n    # Clean up the dummy file\n    if os.path.exists(file_path):\n        os.remove(file_path)\n        print(f\"Cleaned up '{file_path}'.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to Python 3.9 or newer, or pin `docformatter` to `<1.7.7` in your `requirements.txt`.","message":"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.","severity":"breaking","affected_versions":">=1.7.7"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.7.7"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"<1.7.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}