A tool to 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
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
multi-line docstring
"""
# Good
"""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.1.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | f667b44ca4d86e745b210b1a26525677c36e38516138d427c21530b20be639e0 |
|
MD5 | 64708fb08661994372bb6720e3e89ed9 |
|
BLAKE2b-256 | 5aaddd4acce7939613359c5dfdc53a6d2c2de055fba3da333d28b583058bea26 |
Hashes for pydocstringformatter-0.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5745823e07d54c9d1267b006c276e4f171f62713415f60e5024aa549be3301f5 |
|
MD5 | 40e5d8c9c10f6fdcc3003ce4b73fdc81 |
|
BLAKE2b-256 | dca5fe20d5b4c7c0a127feffa54a7d1a02a64c5dd504894a88dc34ff729cb10a |