[New-bugs-announce] [issue29428] Doctest documentation unclear about multi-line fixtures

[Jim DeLaHunt]

New submission from Jim DeLaHunt:

I just had a problem with doctests. It manifested as an error that occurred when I did
>>> import StringIO
in my doctest. 

After some investigation, I realised that my actual problem was that the doctest library documentation https://docs.python.org/3/library/doctest.html left me unclear about three aspects of multi-line doctest fixtures.

1. There is no example of a multiple-line doctest fixture: specifically, a fixture which involves at least one line to set up state, and another line to be the example that tested.  I suggest adding such an example as a new section, "26.3.2. Usage: multi-line tests".  Note that the example in 26.3.3.2 doesn't count: that is a Compound Statement, and I'm talking about a test consisting of multiple interactive statements.

2. Section "26.3.3.2. How are Docstring Examples Recognized?" does not talk about when to use a PS1 prefix (>>>) and when to use a PS2 prefix (...). It should say to use the PS1 at the start of each Python "interactive statement", that is, a statement list ending with a newline, or a Compound Statement. And, to use the PS2 to prefix each continuing line within a Compound Statement. 

3. Section "26.3.3.3. What’s the Execution Context?" is not clear about the crucial difference between state that accumulates within a single docstring from Example to Example, and that is reset from one docstring to another. The phrase "so that one test in M can’t leave behind crumbs that accidentally allow another test to work" can be interpreted as applying within a single docstring. The phrase "names defined earlier in the docstring being run" is easy to miss.

A StackOverflow Question and Answer describing my problem and my insight about what the library documentation didn't tell me is at http://stackoverflow.com/questions/41070547/why-is-importing-a-module-breaking-my-doctest-python-2-7 . A blog post of mine, a source for documentation improvements, is at http://blog.jdlh.com/en/2017/01/31/multi-line-doctests/ .

I actually encountered this problem in a Python 2.7 context, with https://docs.python.org/2/library/doctest.html . But it also applies to Python 3.6 https://docs.python.org/3/library/doctest.html and to the current dev https://docs.python.org/dev/library/doctest.html . In the spirit of fixing the new stuff first, I am filing this issue against Python 3.7. 

Unless someone tells me otherwise, I'll get around to filing similar issues against Python 3.6 and Python 2.7.
Then it's my intention to write improvements to the documentation for Python 3.7, 3.6, and 2.7, and submit each of those. It looks like they will be pretty similar, because the library documentation is pretty similar in each version.

I'm new to Python issue filing and doc fixing, so I would appreciate correction if (when?) I start to blunder.

----------
assignee: docs at python
components: Documentation
messages: 286843
nosy: JDLH, docs at python
priority: normal
severity: normal
status: open
title: Doctest documentation unclear about multi-line fixtures
type: enhancement
versions: Python 3.7

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue29428>
_______________________________________