This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author kernc
Recipients docs@python, kernc
Date 2016-02-06.15:54:20
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1454774062.04.0.526927951264.issue26303@psf.upfronthosting.co.za>
In-reply-to
Content
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!


[0]: https://docs.python.org/3/library/doctest.html#what-s-the-execution-context
History
Date User Action Args
2016-02-06 15:54:22kerncsetrecipients: + kernc, docs@python
2016-02-06 15:54:22kerncsetmessageid: <1454774062.04.0.526927951264.issue26303@psf.upfronthosting.co.za>
2016-02-06 15:54:21kernclinkissue26303 messages
2016-02-06 15:54:20kernccreate