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] [-v] [files ...]
positional arguments:
files
options:
-h, --help show this help message and exit
-w, --write Write the changes to file instead of printing the files to stdout
-v, --version Show version number and exit
Confiuguration
Pydocstringformatter will also read any configuration added to the [tool.pydocstringformatter]
section of a pyproject.toml
file.
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 256: 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
"""
Development
Use pre-commit install
to install the pre-commit hook for the repository.
Testing
To run all the tests:
pytest
To create test for a specific formatting option use the tests/data/format
directory. For each .py
file create a .py.out
file with the expected output after formatting. The test suite will automatically pickup the new tests.
To only run a specific test from that directory, for example tests/data/format/multi_line/class_docstring.py
, use:
pytest -k multi_line-class_docstring
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.2.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | a4407753507c11b91dafa80efb2ed954835af5d83f4fcf4f6238dc6fa38a8fcd |
|
MD5 | eb769e01f7b91fa83d2d8926d65b38c8 |
|
BLAKE2b-256 | 094eb19aa8db65be11e057c533bb08beae302b69902f01404a469ab0b0be5953 |
Hashes for pydocstringformatter-0.2.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8c0aadb92546e24170ec5e211a91e1e392b0091d75176cf7c51f4ff6d70dd208 |
|
MD5 | 99e56c4587025920b4eb8c37aa4bb095 |
|
BLAKE2b-256 | 20312c3cf837ee4580943f384c50a601e1f0813f149f5acdf0fde649d53b5148 |