pydocstyle

Contents

pydocstyle#

Yet another ingredient to improve the quality of your code is to have a good inline documentation of what each class or function is doing. In particular PEP 257 outlines the best practices around using docstrings. Pydocstyle is a style checker for docstrings. Not only does it help you to get the formatting right, but it also warns of missing docstrings and encourages you to document the key components of your code.

For instance, given the simple function

def square(x):
    """ computes the second power of x """
    return x**2

pydocstyle would complain

D210: No whitespaces allowed surrounding docstring text
D400: First line should end with a period (not 'x')
D401: First line should be in imperative mood (perhaps 'Compute', not 'computes')
D403: First word of the first line should be properly capitalized ('Computes', not 'computes')

and make us change the docstring to

def square(x):
    """Compute the second power of x."""
    return x**2

which is not only more consistent with other libraries but also correctly formatted for IDEs that show square.__doc__ as tooltip.

Usage#

Use the pydocstyle command to check the docstring style of a given file:

$ pydocstyle some_file.py

At the beginning it may help to increase the verbosity of the output by also including a snippet of the source code and a detailed explanation for each error:

$ pydocstyle --source --explain some_file.py

The tool can be nicely integrated into VSCode with the following settings.json snippet:

"python.linting.pydocstyleEnabled": true,
Contents