Testing Python Docstrings with doctest and pydocstyle

README.md

Testing Python Docstrings with doctest and pydocstyle

Setup

Like any good project, we'll create a virtual environment for this example. You can use your virtual environment tool of choice, but I'm just going to show with Python's venv (and some help from venv-activate)

cd
mkdir venvs
cd venvs
python3 -m venv doctest-example
cd ~/<project>
venv-activate doctest-example
pip install --upgrade pip setuptools wheel

and now as this is a project and not a library we can install our dependences with pip and requirements.txt

pip install -r requirements.txt

Examples

Passing

Running

python3 passing.py

gives

The 1's square of length 4 is:

[[1. 1. 1. 1.]
 [1. 1. 1. 1.]
 [1. 1. 1. 1.]
 [1. 1. 1. 1.]]

and then running doctest over it

python3 -m doctest -v passing.py

gives

Trying:
    ones(2)
Expecting:
    array([[1., 1.],
           [1., 1.]])
ok
Trying:
    ones(4)
Expecting:
    array([[1., 1., 1., 1.],
           [1., 1., 1., 1.],
           [1., 1., 1., 1.],
           [1., 1., 1., 1.]])
ok
1 items had no tests:
    passing
1 items passed all tests:
   2 tests in passing.ones
2 tests in 2 items.
2 passed and 0 failed.
Test passed.

and running

pydocstyle --select D1 passing.py

yields nothing meaning that the docstrings for the module and function passed pydocstyle.

Failing doctest

Running doctest on failing.py

python3 -m doctest failing.py

gives

**********************************************************************
File "<PATH>/failing.py", line 14, in failing.ones
Failed example:
    ones(4)
Expected:
    [[1. 1. 1. 1.]
     [1. 1. 1. 1.]
     [1. 1. 1. 1.]
     [1. 1. 1. 1.]]
Got:
    array([[1., 1., 1., 1.],
           [1., 1., 1., 1.],
           [1., 1., 1., 1.],
           [1., 1., 1., 1.]])
**********************************************************************
1 items had failures:
   1 of   2 in failing.ones
***Test Failed*** 1 failures.

as the output in the example didn't match the output upon execution.

Failing pydocstyle

Running pydocstyle on no_docs.py

pydocstyle --select D1 no_docs.py

gives

no_docs.py:1 at module level:
        D100: Missing docstring in public module
no_docs.py:5 in public function `ones`:
        D103: Missing docstring in public function

as the file is missing all of its docstrings.

Testing Integrations

• pytest has intergrations for doctest

failing.py

#!/usr/bin/env python3
"""A failing example"""
import numpy as np


def ones(length):
    """
    Create a square numpy array of ones with shape (length, length).

    Example:
        >>> ones(2)
        array([[1., 1.],
               [1., 1.]])
        >>> ones(4)
        [[1. 1. 1. 1.]
         [1. 1. 1. 1.]
         [1. 1. 1. 1.]
         [1. 1. 1. 1.]]

    Args:
        length (`int`): The length of a side of the 1's square

    Returns:
        NumPy Array: Array of ones that has shape (length, length)
    """
    return np.ones((length, length))


if __name__ == "__main__":
    side = 4
    print(f"The 1's square of length {side} is: \n\n{ones(side)}")

no_docs.py

#!/usr/bin/env python3
import numpy as np


def ones(length):
    return np.ones((length, length))


if __name__ == "__main__":
    side = 4
    print(f"The 1's square of length {side} is: \n\n{ones(side)}")

passing.py

#!/usr/bin/env python3
"""A passing example"""
import numpy as np


def ones(length):
    """
    Create a square numpy array of ones with shape (length, length).

    Example:
        >>> ones(2)
        array([[1., 1.],
               [1., 1.]])
        >>> ones(4)
        array([[1., 1., 1., 1.],
               [1., 1., 1., 1.],
               [1., 1., 1., 1.],
               [1., 1., 1., 1.]])

    Args:
        length (`int`): The length of a side of the 1's square

    Returns:
        NumPy Array: Array of ones that has shape (length, length)
    """
    return np.ones((length, length))


if __name__ == "__main__":
    side = 4
    print(f"The 1's square of length {side} is: \n\n{ones(side)}")

requirements.txt

pytest~=5.2
pydocstyle~=4.0
numpy~=1.17
black