Skip to content
Search

Python:doctest

lastmod 2021-04-18created 2021-04-182 edits

Docstring Tests

A way to read Python documentation and use it as tests. Looking at the example is the quickest way to understand it.

def factorial(n):
    """Return the factorial of n, an exact integer >= 0.
    If the result is small enough to fit in an int, return an int.
    Else return a long.
    >>> [factorial(n) for n in range(6)]
    [1, 1, 2, 6, 24, 120]
    >>> factorial(-1)
    Traceback (most recent call last):
        ...
    ValueError: n must be >= 0
    Factorials of floats are OK, but the float must be an exact integer:
    """

    import math
    if not n >= 0:
        raise ValueError("n must be >= 0")
    if math.floor(n) != n:
        raise ValueError("n must be exact integer")
    if n+1 == n:  # catch a value like 1e300
        raise OverflowError("n too large")
    result = 1
    factor = 2
    while factor <= n:
        result *= factor
        factor += 1
    return result

def _test():
    import doctest
    doctest.testmod()    

if __name__ == "__main__":
    _test()

It reads the >>> part (line 7) of the docstring, runs it, and compares the output with the content below it. Because it does a string comparison with the output, the test fails if even one space differs.

An interesting feature, but I mostly use a unit testing framework, so I'll pass.

See also

author Zer0 sitemap