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
"""
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
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.4.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7791eb7094c84a490a5fa3b8f2bdd3b761ac5c2c1bb44f394bd913158a9f682d |
|
MD5 | 26e9aca57c5e6e666b08626724007708 |
|
BLAKE2b-256 | e25c9120e2ec90a04fab0c7adb31063b54c2af357d194e9a1914af56e3c96d4e |
Hashes for pydocstringformatter-0.4.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bdeb767465fa2a0367655f9fdea1da6f42f259801bad4fee4afd9b99b42f4708 |
|
MD5 | 3e5d0ac0ec4361d3cecabcdca994249b |
|
BLAKE2b-256 | 84d6b2ab5789cc3a4dde3eb5f847804665fb04157251cab29be35bfd1cce34cd |