Formats docstrings to follow PEP 257.
Project description
Formats docstrings to follow PEP 257.
Features
docformatter currently automatically formats docstrings to follow a subset of the PEP 257 conventions. Below are the relevant items quoted from PEP 257.
- For consistency, always use triple double quotes around docstrings.
- Triple quotes are used even though the string fits on one line.
- 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.
- Unless the entire docstring fits on a line, place the closing quotes on a line by themselves.
docformatter also handles some of the PEP 8 conventions.
- Don’t write string literals that rely on significant trailing whitespace. Such trailing whitespace is visually indistinguishable and some editors (or more recently, reindent.py) will trim them.
Installation
From pip:
$ pip install --upgrade docformatter
Example
After running:
$ docformatter --in-place example.py
this code
""" Here are some examples. This module docstring should be dedented.""" def launch_rocket(): """Launch the rocket. Go colonize space.""" def factorial(x): ''' Return x factorial. This uses math.factorial. ''' import math return math.factorial(x) def print_factorial(x): """Print x factorial""" print(factorial(x)) def main(): """Main function""" print_factorial(5) if factorial(10): launch_rocket()
gets formatted into this
"""Here are some examples. This module docstring should be dedented. """ def launch_rocket(): """Launch the rocket. Go colonize space. """ def factorial(x): """Return x factorial. This uses math.factorial. """ import math return math.factorial(x) def print_factorial(x): """Print x factorial.""" print(factorial(x)) def main(): """Main function.""" print_factorial(5) if factorial(10): launch_rocket()
Options
Below is the help output:
usage: docformatter [-h] [-i | -c] [-r] [--wrap-summaries length] [--wrap-descriptions length] [--blank] [--pre-summary-newline] [--make-summary-multi-line] [--force-wrap] [--range line line] [--version] files [files ...] Formats docstrings to follow PEP 257. positional arguments: files files to format or '-' for standard in optional arguments: -h, --help show this help message and exit -i, --in-place make changes to files instead of printing diffs -c, --check only check and report incorrectly formatted files -r, --recursive drill down directories recursively -e, --exclude exclude directories and files by names --wrap-summaries length wrap long summary lines at this length; set to 0 to disable wrapping (default: 79) --wrap-descriptions length wrap descriptions at this length; set to 0 to disable wrapping (default: 72) --blank add blank line after description --pre-summary-newline add a newline before the summary of a multi-line docstring --make-summary-multi-line add a newline before and after the summary of a one- line docstring --force-wrap force descriptions to be wrapped even if it may result in a mess --range line line apply docformatter to docstrings between these lines; line numbers are indexed at 1 --version show program's version number and exit
Possible exit codes:
- 1 - if any error encountered
- 3 - if any file needs to be formatted (in --check mode)
Wrapping descriptions
docformatter will wrap descriptions, but only in simple cases. If there is text that seems like a bulleted/numbered list, docformatter will leave the description as is:
- Item one. - Item two. - Item three.
This prevents the risk of the wrapping turning things into a mess. To force even these instances to get wrapped use --force-wrap.
Integration
Git Hook
docformatter is configured for pre-commit and can be set up as a hook with the following .pre-commit-config.yaml configuration:
- repo: https://github.com/myint/docformatter rev: v1.3.1 hooks: - id: docformatter args: [--in-place]
You will need to install pre-commit and run pre-commit install.
You may alternatively use args: [--check] if you prefer the commit to fail instead of letting docformatter format docstrings automatically.
PyCharm
docformatter can be configured as a PyCharm file watcher to automatically format docstrings on saving python files.
Head over to Preferences > Tools > File Watchers, click the + icon and configure docformatter as shown below:
Issues
Bugs and patches can be reported on the GitHub page.
Links
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.