pydocstringformatter 0.2.0

A tool to automatically format Python docstrings that tries to follow recommendations from PEP 8 and PEP 257.

Pydocstringformatter

A tool to automatically format Python docstrings that tries to follow recommendations from PEP 8 and PEP 257. See What it does for currently supported auto-formatting.

How to install

pip install pydocstringformatter

Usage

usage: pydocstringformatter [-h] [-w] [-v] [files ...]

positional arguments:
  files

options:
  -h, --help     show this help message and exit
  -w, --write    Write the changes to file instead of printing the files to stdout
  -v, --version  Show version number and exit

Confiuguration

Pydocstringformatter will also read any configuration added to the [tool.pydocstringformatter] section of a pyproject.toml file.

Pre-commit

Pydocstringformatter can also be used as a pre-commit hook. Add the following to your .pre-commit-config.yaml file:

-   repo: https://github.com/DanielNoord/pydocstringformatter
    rev: SPECIFY VERSION HERE
    hooks:
    -   id: pydocstringformatter

What it does

The following examples show what pydocstringformatter will pick up on. All bad examples will be rewritten to follow the good patterns.

PEP 8: Note that most importantly, the """ that ends a multiline docstring should be on a line by itself:

# Bad
"""My
multi-line docstring"""

# Good
"""My
multi-line docstring
"""

PEP 256: The closing quotes are on the same line as the opening quotes

For consistency this rule also gets applied to multi-line docstrings

# Bad
"""
My docstring"""

"""My docstring
"""

"""
My
multi-line docstring
"""

# Good
"""My docstring"""

"""My docstring"""

"""My
multi-line docstring
"""

Development

Use pre-commit install to install the pre-commit hook for the repository.

Testing

To run all the tests:

pytest

To create test for a specific formatting option use the tests/data/format directory. For each .py file create a .py.out file with the expected output after formatting. The test suite will automatically pickup the new tests.

To only run a specific test from that directory, for example tests/data/format/multi_line/class_docstring.py, use:

pytest -k multi_line-class_docstring