Issue 26303: Shared execution context between doctests in a module (original) (raw)

The doctest execution context documentation 0 says the tests get shallow copies of module's globals, so one test can't mingle with results of another. This makes it impossible to make literate modules such as:

"""
This module is about reusable doctests context.

Examples
--------
Let's prepare something the later examples can work with:

>>> import foo
>>> result = foo.Something()
2

"""
class Bar:
    """
    Class about something.

    >>> bar = Bar(foo)
    >>> bar.uses(foo)
    True
    
    """
    def baz(self):
        """
        Returns 3.

        >>> result + bar.baz()
        5
        
        """
        return 3

I.e. one has to instantiate everything in every single test. The documentation says one can pass their own globals as glob=your_dict, but it doesn't mention the dict is cleared after the test run.

Please acknowledge the use case of doctests in a module sharing their environment and results sometimes legitimately exists, and to make it future-compatible, please amend the final paragraph of the relevant part of documentation 0 like so:

You can force use of your own dict as the execution context by 
passing `globs=your_dict` to `testmod()` or `testfile()` instead, 
e.g., to have all doctests in a module use the _same_ execution
context (sharing variables), define a context like so:

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

and use it, optionally prepopulated with `M`'s globals:

    doctest.testmod(module,
                    glob=Context(module.__dict__.copy()))

Thank you!