pydoctest: docstring signature verification

Motivation

Pydoctest helps you verify that your docstrings match your function signatures. As a codebase evolves, you can some times forget to update the docstrings.

Installation

Install pydoctest with pip:

$ python3 -m pip install pydoctest

Usage

Navigate to your project location, and execute pydoctest

$ pydoctest

With no pydoctest.json configuration file, it will by default validate all .py files recursively in the current directory (**/*.py). See the configuration section for options. If you get errors with modules not being found, try placing the pydoctest.json differently or executing inside the package.

Output

Pydoctest supports outputting results either as JSON or Text with different verbosity options. By default, Text is returned. To specify the output, invoke with --reporter argument:

$ pydoctest --reporter [json | text]

For Text-output, --verbosity can be provided with a value of 0 (quiet), 1 (show failed) or 2 (show all).

$ pydoctest --reporter text --verbosity 1

Configuration

Pydoctest can be configured with a config JSON file. By default, it will search for pydoctest.json in the directory pydoctest is executed. A path can also be provided when executing:

$ pydoctest --config /path/to/pydoctest.json

Example pydoctest.json:

{
    "include_paths": [ "server/*.py" ],
    "fail_on_missing_docstring": true,
    "parser": "google",
}

Docstring format can be specified with the --parser argument:

$ pydoctest --parser google

Currently, only google, numpy and sphinx are supported.

Full list of configuration options:

"include_paths": [ List of strings ] # Patterns to search modules with. Defaults to [**/*.py]
"exclude_paths": [ List of strings ] # Patterns to exclude modules with. Defaults to ["**/__init__.py", "**/setup.py"]
"verbosity": [ 0 | 1 | 2 ] # How much to print, 0 = quiet, 1 = show failed, 2 = show all.
"parser": [ "google" (default) | "sphinx" | "numpy" ] # Docstring format to use. Please raise an issue if you need other formats implemented.
"fail_on_missing_docstring": [ true | false (default) ] # Mark a function as failed, if it does not have a docstring.
"fail_on_missing_summary": [ true | false (default) ] # Mark a function as failed, if it does have a docstring, but no summary.
"fail_on_raises_section": [ true (default) | false ] # Mark a function as failed, if docstring doesn't mention raised exceptions correctly.
"exclude_classes": [ List of strings ] # Patterns to exclude classes with, e.g. ["Test*]"
"exclude_methods": [ List of strings ] # Patterns to exclude class methods with, e.g. for private methods you would use ["__*]"
"exclude_functions": [ List of strings ] # Patterns to exclude functions with, e.g. for private methods you would use ["__*]"

CLI

Printing the help message shows all currently implemented cli options.

pydoctest --help

Example

# example_file.py
def func_type_mismatch(self, a: int) -> int:
    """[summary]

    Args:
        a (float): [description]        <-- float is not int

    Returns:
        int: [description]
    """
    pass

# /example_file.py::func_type_mismatch FAIL | Argument type differ. Argument 'a' was expected (from signature) to have type '<class 'int'>', but has (in docs) type '<class 'float'>'
Tested 1 function(s) across 1 module(s).
Succeeded: 0, Failed: 1, Skipped: 0

Editor support

Currently pydoctest is supported by vscode: https://github.com/jepperaskdk/vscode-pydoctest

License

Pydoctest is licensed under the terms of the MIT License (see the LICENSE file).