Python: using doctests for classes

Question

Is it possible to use Python's doctest concept for classes, not just functions?

If so, where shall I put the doctests - at the class' docstring, or at the constructor's docstring?

To clarify, I'm looking for something like:

class Test:
    """
    >>> a=Test(5)
    >>> a.multiply_by_2()
    10
    """
    def __init__(self, number):
        self._number=number

    def multiply_by_2(self):
        return self._number*2

Thanks in advance,

Adam

Answer 1

You're missing the code to actually run the doctests at the bottom of the file:

class Test:
    <snip>

if __name__ == "__main__":
    import doctest
    doctest.testmod()

As for where to put the tests:

• If it's testing the class as a whole, I'd put them in the class' docstring.
• If it's testing the constructor, I'd put them in the constructor's docstring.
• If it's testing a method (as it seems to be in this case), I'd actually put it them in that method's docstring.

Answer 2

I think the doctest module documentation does not explain how to handle this, and it should do better at explaining what to do.

A pattern that I figured out for testing class methods that don't need instance data, but might need access to class data, is to pass in the Class object instead of an instance.

class Test:
    """
    >>> Test.multiply_by_3(Test,2)
    6
    """
    def __init__(self, number):
        self._number=number

    _THREE = 3
    def multiply_by_3(self, x):
        return x*self._THREE

if __name__ == "__main__":
    import doctest
    doctest.testmod()

Answer 3

Instead of instantiating the object in every method, you can use the extraglobs argument:

class Test:
    def multiply_by_2(self):
        """
        >>> t.multiply_by_2()
        10
        """
        return self._number*2

if __name__ == '__main__':
    import doctest
    doctest.testmod(extraglobs={'t': Test()})

Answer 4

The doctest module looks for any docstrings in a file and executes any embedded code in it, so yes it is possible to use doctest for classes.

As for whether it is better to put the doctests in the class's docstring or the constructor, I think that depends on what exactly you are documenting.

If the docstring gives a general overview of the class and how to use it then I think it is better to put it in the class.

If the docstring is specifically about how to create instances of the class then it should go in the __init__ method.

Remember the intent of doctests is primarily to have self-validating example code in documentation, so IMHO the documentation aspect should take priority over the testing aspect.

Edit:

In your example above there is no code to execute the doctest - running python test.py -v will execute the main python code which just defines the class.

You need to add this to the end of the file:

if __name__ == "__main__":
    import doctest
    doctest.testmod()

Alternatively If you are using Python 2.6 or later run it with:

python -m doctest -v test.py