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

Navigation

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for danielnoord from gravatar.com danielnoord

Unverified details

These details have not been verified by PyPI
Meta
  • License: MIT License (MIT)
  • Author: Daniël van Noord
  • Tags python , docstring , format
  • Requires: Python >=3.8
Classifiers
Report project as malware

Project description

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.

Project details

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for danielnoord from gravatar.com danielnoord

Unverified details

These details have not been verified by PyPI
Meta
  • License: MIT License (MIT)
  • Author: Daniël van Noord
  • Tags python , docstring , format
  • Requires: Python >=3.8
Classifiers

Release history Release notifications | RSS feed

This version

0.7.5

0.7.3

0.7.2

0.7.1

0.7.0

0.6.2

0.6.1

0.6.0

0.5.3

0.5.2

0.5.1 yanked

Reason this release was yanked:

Incorrect version numbering

0.5.0

0.4.0

0.3.0

0.2.0

0.1.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pydocstringformatter-0.7.5.tar.gz (30.5 kB view details)

Uploaded Source

Built Distribution

pydocstringformatter-0.7.5-py3-none-any.whl (31.4 kB view details)

Uploaded Python 3

File details

Details for the file pydocstringformatter-0.7.5.tar.gz.

File metadata

  • Download URL: pydocstringformatter-0.7.5.tar.gz
  • Upload date:
  • Size: 30.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for pydocstringformatter-0.7.5.tar.gz
Algorithm Hash digest
SHA256 e9cbd134d6279360fd2bcaad94680cec02aa20a22560375c5ffd495fcfbcf92d
MD5 e1d65da1c153a602ab758fcdae7ddd8c
BLAKE2b-256 b037f6d5ff68893c8b4ae194d6dd9df31be2cceacfae5256c840b9e216fd20de

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydocstringformatter-0.7.5.tar.gz:

Publisher: publish.yaml on DanielNoord/pydocstringformatter

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pydocstringformatter-0.7.5-py3-none-any.whl.

File metadata

File hashes

Hashes for pydocstringformatter-0.7.5-py3-none-any.whl
Algorithm Hash digest
SHA256 7daed355f11244f64571d119e49e7328365ea9b545f88256a47b550f213d23eb
MD5 bdaa729a94937dae2f782679717f7016
BLAKE2b-256 81ede70e413b537b7809badcd275a5f050301dafbe54efd1ae9d392ed2943c40

See more details on using hashes here.

Provenance

The following attestation bundles were made for pydocstringformatter-0.7.5-py3-none-any.whl:

Publisher: publish.yaml on DanielNoord/pydocstringformatter

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page