Shared execution context between doctests in a module

[kernc]

BPO	26303
Nosy	@kernc, @Mariatta, @tonybaloney

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/Mariatta'
closed_at = None
created_at = <Date 2016-02-06.15:54:21.991>
labels = ['type-feature', 'docs']
title = 'Shared execution context between doctests in a module'
updated_at = <Date 2019-05-06.18:27:22.668>
user = 'https://github.com/kernc'

bugs.python.org fields:

activity = <Date 2019-05-06.18:27:22.668>
actor = 'anthonypjshaw'
assignee = 'Mariatta'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2016-02-06.15:54:21.991>
creator = 'kernc'
dependencies = []
files = []
hgrepos = []
issue_num = 26303
keywords = []
message_count = 3.0
messages = ['259731', '259732', '341585']
nosy_count = 4.0
nosy_names = ['docs@python', 'kernc', 'Mariatta', 'anthonypjshaw']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue26303'
versions = ['Python 3.6']

[kernc]

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!

[kernc]

The use case is not unpopular 1 and with unambiguous examples like

    >>> arr = np.arange(5)
    >>> my_sum(arr)
    10

(i.e., without importing numpy as np everywhere), it also makes a lot of sense.

[tonybaloney]

this issue would be good for pycon sprints