Skip to content

Automatically format your Python docstrings to conform with PEP 8 and PEP 257

License

Notifications You must be signed in to change notification settings

DanielNoord/pydocstringformatter

This branch is up to date with main.

Folders and files

NameName
Last commit message
Last commit date
Jan 31, 2025
Oct 16, 2024
Sep 30, 2024
Sep 2, 2024
Nov 28, 2022
Jun 18, 2022
Feb 26, 2023
Feb 10, 2025
Mar 15, 2022
Feb 12, 2022
Jan 1, 2022
Mar 2, 2023
Jun 13, 2022
Sep 30, 2024
Feb 12, 2025
Dec 2, 2024

Repository files navigation

PyPI pyversions codecov Tests pre-commit.ci status Documentation Status

Pydocstringformatter

A tool to automatically format Python docstrings to follow recommendations from PEP 8 and PEP 257 (or other supported style guides.)

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 was no longer actively maintained (this has changed since then). 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.

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/**"]
strip-whitespaces = true
split-summary-body = false
numpydoc-section-hyphen-length = false

Style

Pydocstringformatter can be configured to use a specific style. The default is pep257 but we support other styles as well. These can also be used at the same time. For example with:

pydocstringformatter --style=pep257 --style=numpydoc myfile.py

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 some of the changes pydocstringformatter will apply. For a full overview of all potential changes you can check out the Usage page which shows an up to date list of all formatters and their description.

# Bad
'''
my docstring'''

"""    my
multi-line docstring      """

"""my title
===========

my docstring
"""


# Good
"""My docstring."""

"""My
multi-line docstring.
"""

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

My docstring
"""

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

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

Development

For development and contributing guidelines please see Development.