Skip to main content

Formats docstrings to follow PEP 257.

Project description

Formats docstrings to follow PEP 257.

Build status Test coverage status

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.

  • The BDFL recommends inserting a blank line between the last paragraph in a multi-line docstring and its closing quotes, placing 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 example.py

this code

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

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] [-r] [--wrap-summaries length] [--no-blank]
                    [--pre-summary-newline] [--version]
                    files [files ...]

Formats docstrings to follow PEP 257.

positional arguments:
  files                 files to format

optional arguments:
  -h, --help            show this help message and exit
  -i, --in-place        make changes to files instead of printing diffs
  -r, --recursive       drill down directories recursively
  --wrap-summaries length
                        wrap long summary lines at this length (default: 79)
  --no-blank            do not add blank line after description
  --pre-summary-newline
                        add a newline before the summary of a multi-line
                        docstring
  --version             show program's version number and exit

Issues

Bugs and patches can be reported on the GitHub page.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

docformatter-0.5.1.tar.gz (10.4 kB view details)

Uploaded Source

File details

Details for the file docformatter-0.5.1.tar.gz.

File metadata

File hashes

Hashes for docformatter-0.5.1.tar.gz
Algorithm Hash digest
SHA256 3dadcee55a4c5d7dd8a0aa5bb03d0fff0b59938cf5e724ee878bea8a4f7c9652
MD5 27a265859e55d73283c6b363b74a15da
BLAKE2b-256 16227f83f3ff1f23ddd447f20d20350e9bdf27ad28777b0dc06a8cba739ee90a

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page