{"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":"python","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,"search_vec":"'1.7.7':57 '257':15 'activ':41 'address':46 'adher':12 'aspect':25 'automat':8 'blank':30 'bug':47 'code':60 'commit':66 'consist':18 'convent':16 'current':54 'docformatt':1,2 'docstr':10,36,62 'document':21 'ensur':17 'featur':51 'fix':48 'format':9 'formatt':58 'frequent':44 'handl':23 'librari':39 'like':26 'line':28,31,35 'linter':59 'maintain':42 'multi':34 'multi-lin':33 'new':50 'pep':14 'pep257':63 'pre':65 'pre-commit':64 'python':5 'qualiti':61 'readabl':20 'releas':45 'structur':37 'summari':27 'tool':6 'various':24 'version':55 'wrap':29","created_at":"2026-04-12T03:35:44.951344+00:00","updated_at":"2026-04-16T14:38:31.170199+00:00","problems":[{"fix":"Upgrade docformatter to a version compatible with your Python interpreter, or ensure that Python version is compatible with docformatter's dependencies. For Python 3.14 and untokenize, a docformatter release that drops or vendors 'untokenize' is needed.","cause":"Installation of docformatter fails on newer Python versions (e.g., 3.14) due to incompatible dependencies like 'untokenize' or 'lib2to3'.","error":"CalledProcessError: command: ('/path/to/python', '-mpip', 'install', '.') return code: 1"},{"fix":"Update the integrating code or script to use the current docformatter API, such as invoking it via its command-line interface or using the updated programmatic API if available. This function was removed in docformatter version 1.5.","cause":"This error occurs when older code or an integration attempts to call a deprecated or removed API function 'format_code' from docformatter.","error":"AttributeError: module 'docformatter' has no attribute 'format_code'"},{"fix":"Explicitly pass the `--config` argument to docformatter in your `.pre-commit-config.yaml` and add `tomli` to `additional_dependencies` for Python < 3.11. Example: `args: [--in-place, --config, pyproject.toml]`","cause":"When run as a pre-commit hook, docformatter might not automatically load configurations from `pyproject.toml`, especially in older versions or without specifying 'tomli' as an additional dependency for Python versions prior to 3.11.","error":"docformatter seems to ignore the configuration in pyproject.toml and uses its default settings instead"},{"fix":"Upgrade docformatter to a version where this bug has been addressed and fixed (e.g., versions released after the fix for issue #277, which was closed in #304).","cause":"This bug occurs when docformatter's internal file encoding detection (using `from_path(filename).best()`) returns `None` for certain files, leading to an AttributeError when it tries to access the 'encoding' attribute.","error":"AttributeError: 'NoneType' object has no attribute 'encoding' (from_path(filename).best().encoding)"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"docformatter","cli_version":"docformatter 1.7.8","type":"library","homepage":null,"github":"https://github.com/PyCQA/docformatter","docs":"https://docformatter.readthedocs.io/en/latest/","changelog":null,"pypi":"https://pypi.org/project/docformatter/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-04-11","next_check":"2026-07-10","install_tag":null}}