pydocstringformatter

0.7.5 · active · verified Thu Apr 16

pydocstringformatter is a tool that automatically formats Python docstrings, aiming to align them with recommendations from PEP 8 and PEP 257. It is currently at version 0.7.5 and maintains an active release cadence, with minor releases addressing bug fixes and improvements appearing every few weeks to months.

Common errors

```
IndexError: string index out of range
```
cause This error often occurs when processing almost empty docstrings or docstrings with specific problematic structures, particularly with single-line summaries.

fix Upgrade to version 0.7.3 or higher. Versions 0.7.2 and 0.7.3 specifically addressed crashes with almost empty docstrings and empty summaries.
```
Error: No such option: --style
```
cause You are attempting to use the `--style` option, but your installed version of pydocstringformatter is too old.

fix Upgrade to pydocstringformatter version 0.7.0 or newer: `pip install --upgrade pydocstringformatter`.
```
Configuration specified in pyproject.toml is not being applied
```
cause Older versions of pydocstringformatter had bugs in parsing `pyproject.toml` configuration, leading to settings being ignored.

fix Upgrade to pydocstringformatter version 0.7.0 or newer. Also, verify that your `pyproject.toml` adheres to the TOML specification and the tool's expected configuration structure (e.g., `[tool.pydocstringformatter]`).

Warnings

gotcha Version 0.7.4 was never released on PyPI. Users attempting to install or pin to this specific version will encounter a 'No matching distribution found' error.
Fix: Install the latest available version (0.7.5 or higher) or a previous stable release (e.g., 0.7.3).
breaking The `--style` option, which allows selecting a specific docstring style (e.g., `numpydoc`), was introduced in v0.7.0. Older versions do not support this argument.
Fix: Upgrade to version 0.7.0 or higher to utilize the `--style` option: `pip install --upgrade pydocstringformatter`.
gotcha Prior to version 0.7.0 and 0.6.2, there were several fixes related to incorrect parsing of values in `pyproject.toml`. This could lead to configuration not being applied as expected.
Fix: Ensure you are using pydocstringformatter version 0.7.0 or newer for more robust `pyproject.toml` parsing and configuration application. If issues persist, double-check TOML syntax.
gotcha Specific formatting rules for styles like numpydoc (e.g., section ordering, name/type spacing) were added in v0.7.0. Older versions will not apply these specific rules.
Fix: Upgrade to pydocstringformatter v0.7.0 or later to benefit from enhanced numpydoc style formatting features.

Install

pip install pydocstringformatter Install stable version

Quickstart

Run pydocstringformatter on a Python file to automatically format its docstrings. Use `--diff` to see changes without applying them, or run without to apply changes directly.

echo "def example_function():\n    ''' A docstring. '''\n    pass" > temp_module.py
pydocstringformatter temp_module.py --diff
pydocstringformatter temp_module.py
cat temp_module.py
rm temp_module.py

view raw JSON →