pydocstringformatter 0.7.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 to follow recommendations from PEP 8 and PEP 257.

See What it does for currently supported auto-formatting.

Rationale

This project is heavily inspired by docformatter.

When this project was started docformatter did not meet all of the requirements the pylint project had for its docstring formatter and sadly docformatter is now also no longer fully supported. Therefore, some contributors of pylint got together and started working on our own formatter to fulfill our needs.

When asked we defined the objective of the tool as:

"A docstring formatter that follows PEP8 and PEP257 but makes some of the more 'controversial' elements of the PEPs optional"

See the original answer.

As such, the biggest difference between the two is that pydocstringformatter fixes some of the open issues we found in docformatter. In general, the output of both formatters (and any other docstring formatter) should be relatively similar.

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.
  --max-line-length     The maximum docstring line length. Default set to 88.

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.