Whole document tree

Python Library Reference

Previous: 5.1.5 Advanced Usage Up: 5.1 doctest Next: 5.1.7 Warnings

---

5.1.6 How are Docstring Examples Recognized?

In most cases a copy-and-paste of an interactive console session works fine -- just make sure the leading whitespace is rigidly consistent (you can mix tabs and spaces if you're too lazy to do it right, but doctest is not in the business of guessing what you think a tab means).

>>> # comments are ignored
>>> x = 12
>>> x
12
>>> if x == 13:
...     print "yes"
... else:
...     print "no"
...     print "NO"
...     print "NO!!!"
...
no
NO
NO!!!
>>>

Any expected output must immediately follow the final '>>> ' or '... ' line containing the code, and the expected output (if any) extends to the next '>>> ' or all-whitespace line.

The fine print:

• Expected output cannot contain an all-whitespace line, since such a line is taken to signal the end of expected output.

• Output to stdout is captured, but not output to stderr (exception tracebacks are captured via a different means).

• If you continue a line via backslashing in an interactive session, or for any other reason use a backslash, you need to double the backslash in the docstring version. This is simply because you're in a string, and so the backslash must be escaped for it to survive intact. Like:

  >>> if "yes" == \\
  ...     "y" +   \\
  ...     "es":
  ...     print 'yes'
  yes
  

• The starting column doesn't matter:

    >>> assert "Easy!"
          >>> import math
              >>> math.floor(1.9)
              1.0
  

  and as many leading whitespace characters are stripped from the expected output as appeared in the initial '>>> ' line that triggered it.

---

Python Library Reference

Previous: 5.1.5 Advanced Usage Up: 5.1 doctest Next: 5.1.7 Warnings

---

Release 2.1.3, documentation updated on April 8, 2002.