A tool to automatically format Python docstrings that tries to follow recommendations from PEP 8 and PEP 257.
Project description
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] [--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
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
"""
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
"""
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
Contributing
.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pydocstringformatter-0.3.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 059338ac4822af4e01b2de78225768e539bdf442d356e2287865f5f57897864c |
|
MD5 | 27bf40ab5e6f314bf35b7d9c6c361bad |
|
BLAKE2b-256 | 7e15607c1b775c796069fdd09a11ecf23b780fe329134b733af22a213b783493 |
Hashes for pydocstringformatter-0.3.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 204e7e8b6823f90e72b9700ba7524b2b6a672f24aa89be9038c98d674ca14f0a |
|
MD5 | f1b265bed6ba480d9a8cc2a6ad5eb641 |
|
BLAKE2b-256 | 5995b69fd8d3dde1adeacb9270a32a3d8da4cbeeef25f73eb3c599a600d82673 |