pydocstringformatter 0.5.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

Click here for a full Usage overview.

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

positional arguments:
  files                 The directory or files to format.

options:
  -h, --help            show this help message and exit
  -w, --write           Write the changes to file instead of printing the diffs to stdout.
  --quiet               Do not print any logging or status messages to stdout.
  -v, --version         Show version number and exit.

configuration:
  --exclude EXCLUDE     A comma separated list of glob patterns of file path names not to be formatted.

Configuration

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

For example:

[tool.pydocstringformatter]
write = True
exclude = "**/my_dir/**,**/my_other_dir/**"
# Or:
exclude = ["**/my_dir/**", "**/my_other_dir/**"]

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 257: The closing quotes are on the same line as the opening quotes

This can be enforced on multi-line docstrings with the --summary-quotes-same-line option. This behaviour is turned off by default.

# Bad
"""
My docstring"""

"""My docstring
"""

"""
My
multi-line docstring
"""

# With --summary-quotes-same-line
"""
My
multi-line docstring
"""

# Good
"""My docstring"""

"""My docstring"""

"""
My
multi-line docstring
"""

# With --summary-quotes-same-line
"""My
multi-line docstring
"""

PEP 257: The docstring is a phrase ending in a period & Multi-line docstrings consist of a summary line just like a one-line docstring

Since the first line should be a phrase or summary the first character gets capitalized.

When the second line is one recurring character we consider the summary line to be a title as used in many Sphinx documentation schemes and do not add a period.

# Bad
"""my docstring"""

"""
summary

my docstring
"""


# Good
"""My docstring."""

"""
Summary.

my docstring
"""

"""My title
===========

My docstring
"""

PEP 257: Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description.

When the second line is one recurring character we consider the summary line to be a title as used in many Sphinx documentation schemes and do not add a white line.

# Bad
"""Summary. Body."""

"""Summary.
Body.
"""

# Good
"""Summary.

Body.
"""

"""My title
===========

My docstring
"""

PEP 257: For consistency, always use """triple double quotes""" around docstrings.

# Bad
"My docstring"

'My docstring'

'''My docstring'''

'''Summary.

Body.
'''

# Good
"""My docstring"""

"""My docstring"""

"""My docstring"""

"""Summary.

Body.
"""

Trailing or leading whitespaces get removed as well.

# Bad
"""  My docstring.  """

"""  Summary.

Body
  """

"""  My docstring.

    My indented section
"""

# Good
"""My docstring."""

"""  Summary.

Body
"""

"""My docstring.

    My indented section
"""

Development

For development and contributing guidelines please see Development.