diff options
| -rw-r--r-- | Doc/lib/libdoctest.tex | 94 |
1 files changed, 48 insertions, 46 deletions
diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex index bc8ad8b..8adbc9d 100644 --- a/Doc/lib/libdoctest.tex +++ b/Doc/lib/libdoctest.tex @@ -226,11 +226,11 @@ No problem, as long as the only output generated by the example is the traceback itself. For example: \begin{verbatim} - >>> [1, 2, 3].remove(42) - Traceback (most recent call last): - File "<stdin>", line 1, in ? - ValueError: list.remove(x): x not in list - >>> +>>> [1, 2, 3].remove(42) +Traceback (most recent call last): + File "<stdin>", line 1, in ? +ValueError: list.remove(x): x not in list +>>> \end{verbatim} Note that only the exception type and value are compared (specifically, @@ -257,26 +257,27 @@ 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). \begin{verbatim} - >>> # comments are ignored - >>> x = 12 - >>> x - 12 - >>> if x == 13: - ... print "yes" - ... else: - ... print "no" - ... print "NO" - ... print "NO!!!" - ... - no - NO - NO!!! - >>> +>>> # comments are ignored +>>> x = 12 +>>> x +12 +>>> if x == 13: +... print "yes" +... else: +... print "no" +... print "NO" +... print "NO!!!" +... +no +NO +NO!!! +>>> \end{verbatim} -Any expected output must immediately follow the final \code{">>>"} or -\code{"..."} line containing the code, and the expected output (if any) -extends to the next \code{">>>"} or all-whitespace line. +Any expected output must immediately follow the final +\code{'>\code{>}>~'} or \code{'...~'} line containing the code, and +the expected output (if any) extends to the next \code{'>\code{>}>~'} +or all-whitespace line. The fine print: @@ -310,8 +311,9 @@ yes 1.0 \end{verbatim} -and as many leading whitespace characters are stripped from the expected -output as appeared in the initial ">>>" line that triggered it. +and as many leading whitespace characters are stripped from the +expected output as appeared in the initial \code{'>\code{>}>~'} line +that triggered it. \end{itemize} \subsection{Warnings} @@ -349,26 +351,26 @@ testmod skips it by default. Other approaches are described in % Hey! What happened to Monty Python examples? % Tim: ask Guido -- it's his example! \begin{verbatim} - >>> foo() - {"Hermione": "hippogryph", "Harry": "broomstick"} - >>> +>>> foo() +{"Hermione": "hippogryph", "Harry": "broomstick"} +>>> \end{verbatim} is vulnerable! One workaround is to do \begin{verbatim} - >>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"} - 1 - >>> +>>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"} +1 +>>> \end{verbatim} instead. Another is to do \begin{verbatim} - >>> d = foo().items() - >>> d.sort() - >>> d - [('Harry', 'broomstick'), ('Hermione', 'hippogryph')] +>>> d = foo().items() +>>> d.sort() +>>> d +[('Harry', 'broomstick'), ('Hermione', 'hippogryph')] \end{verbatim} There are others, but you get the idea. @@ -376,9 +378,9 @@ There are others, but you get the idea. Another bad idea is to print things that embed an object address, like \begin{verbatim} - >>> id(1.0) # certain to fail some of the time - 7948648 - >>> +>>> id(1.0) # certain to fail some of the time +7948648 +>>> \end{verbatim} Floating-point numbers are also subject to small output variations across @@ -386,20 +388,20 @@ platforms, because Python defers to the platform C library for float formatting, and C libraries vary widely in quality here. \begin{verbatim} - >>> 1./7 # risky - 0.14285714285714285 - >>> print 1./7 # safer - 0.142857142857 - >>> print round(1./7, 6) # much safer - 0.142857 +>>> 1./7 # risky +0.14285714285714285 +>>> print 1./7 # safer +0.142857142857 +>>> print round(1./7, 6) # much safer +0.142857 \end{verbatim} Numbers of the form \code{I/2.**J} are safe across all platforms, and I often contrive doctest examples to produce numbers of that form: \begin{verbatim} - >>> 3./4 # utterly safe - 0.75 +>>> 3./4 # utterly safe +0.75 \end{verbatim} Simple fractions are also easier for people to understand, and that makes |