GNU Info

(python2.1-lib.info)How are Docstring Examples Recognized?

---

Next: Warnings Prev: Advanced Usage Up: doctest

---

Enter node , (file) or (file)node

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.