object reuse in python doctest

Question

I have a sample doctest like this one.

"""
This is the "iniFileGenerator" module.
>>> hintFile = "./tests/unit_test_files/hint.txt"
>>> f = iniFileGenerator(hintFile)
>>> print f.hintFilePath
./tests/unit_test_files/hint.txt
"""
class iniFileGenerator:
    def __init__(self, hintFilePath):
        self.hintFilePath = hintFilePath
    def hello(self):
        """
        >>> f.hello()
        hello
        """
        print "hello"
if __name__ == "__main__":
    import doctest
    doctest.testmod()

When I execute this code, I got this error.

Failed example:
    f.hello()
Exception raised:
    Traceback (most recent call last):
      File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/doctest.py", line 1254, in __run
        compileflags, 1) in test.globs
      File "<doctest __main__.iniFileGenerator.hello[0]>", line 1, in <module>
        f.hello()
    NameError: name 'f' is not defined

This error is caused by accessing 'f' which was not accessible when testing hello() method.

Is there any way to share the object which is created before? Without it, one need to create object all the time when it's necessary.

def hello(self):
    """
    hintFile = "./tests/unit_test_files/hint.txt"
    >>> f = iniFileGenerator(hintFile)
    >>> f.hello()
    hello
    """
    print "hello"

http://docs.python.org/library/doctest.html#what-s-the-execution-context — Thomas, Oct 28 '12 at 06:02

iMom0 · Accepted Answer · 2012-10-28T06:35:52.540

7

You can use testmod(extraglobs={'f': initFileGenerator('')}) to define a reusable object globally.

As the doctest doc says,

extraglobs gives a dict merged into the globals used to execute examples. This works like dict.update()

But I used to test all methods in __doc__ of class before all methods.

class MyClass(object):
    """MyClass
    >>> m = MyClass()
    >>> m.hello()
    hello
    >>> m.world()
    world
    """

    def hello(self):
        """method hello"""
        print 'hello'

    def world(self):
        """method world"""
        print 'world'

edited Oct 28 '12 at 06:35

answered Oct 28 '12 at 06:08

iMom0

12,493
3
49
61

just beat me to it, yep on extraglobs. Although I don't like the extraglobs approach, I like this answer less - some of the point of doctests are to document the methods, which you lose here. – Thomas Oct 28 '12 at 06:09
@Thomas After I checked the source code of some popular and well-documented projects, I think it is ok, http://nltk.org/_modules/nltk/align.html#Alignment – iMom0 Oct 28 '12 at 06:50
Cool - I just like to see it in the docstrings so I can call help() on the method to see how it works instead of scrolling through the class docs. – Thomas Oct 28 '12 at 15:25
There may be [a more convenient approach](http://stackoverflow.com/a/35242443/1090455). – K3---rnc Feb 06 '16 at 15:00

score 2 · Answer 2 · edited Jun 20 '20 at 09:12

To obtain literate modules with tests that all use a shared execution context (i.e. individual tests that can share and re-use results), one has to look at the relevant part of documentation on the execution context, which says:

... each time doctest finds a docstring to test, it uses a shallow copy of M‘s globals, so that running tests doesn’t change the module’s real globals, and so that one test in M can’t leave behind crumbs that accidentally allow another test to work.

...

You can force use of your own dict as the execution context by passing globs=your_dict to testmod() or testfile() instead.

Given this, I managed to reverse-engineer from doctest module that besides using copies (i.e. the dict's copy() method), it also clears the globals dict (using clear()) after each test.

Thus, one can patch their own globals dictionary with something like:

class Context(dict):
    def clear(self):
        pass
    def copy(self):
        return self

and then use it as:

import doctest
from importlib import import_module

module = import_module('some.module')
doctest.testmod(module,
                # Make a copy of globals so tests in this
                # module don't affect the tests in another
                glob=Context(module.__dict__.copy()))

score 1 · Answer 3 · answered May 10 '19 at 11:09

For anyone like me that finds this, here's an easy hack that solves this problem.

In your module documentation, attach the "global" values as a property of the builtins module, e.g.

"""
My module documentation

>>> import builtins
>>> builtins.sample_value = "Here is a long value"
>>> builtins.sample_func = lambda x: x.lower()
"""

The builtins module is automatically imported into every scope, and so its properties will be available in your functions, including doctest functions

def first_char_func(s: str) -> str:
   """
   Returns the first char of a function

   >>> first_char_func(sample_func(sample_value))
   h
   """  
   return s[0] if len(s) > 0 else None

Arguably however, once you've gotten to this stage, you're better off just writing a unit test.

object reuse in python doctest

3 Answers3

Linked