Doctest has new traceback gimmicks in 2.4. While trying to document

them (which they are now), I had to rewrite the code to understand
it.  This has got to be the most DWIM part of doctest -- but in context
is really necessary.

1 files changed, 80 insertions, 18 deletions

diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex
index e5b637a..7558309 100644
--- a/Doc/lib/libdoctest.tex
+++ b/Doc/lib/libdoctest.tex
@@ -108,7 +108,8 @@ Expecting: [1, 1, 2, 6, 24, 120]
 ok
 Trying: [factorial(long(n)) for n in range(6)]
 Expecting: [1, 1, 2, 6, 24, 120]
-ok\end{verbatim}
+ok
+\end{verbatim}
 
 And so on, eventually ending with:
 
@@ -129,12 +130,14 @@ $
 \end{verbatim}
 
 That's all you need to know to start making productive use of
-\module{doctest}!  Jump in.
+\module{doctest}!  Jump in.  The following sections provide full
+details.  Note that there are many examples of doctests in
+the standard Python test suite and libraries.
 
 \subsection{Simple Usage}
 
-The simplest (not necessarily the best) way to start using doctest is to
-end each module \module{M} with:
+The simplest way to start using doctest (but not necessarily the way
+you'll continue to do it) is to end each module \module{M} with:
 
 \begin{verbatim}
 def _test():
@@ -146,8 +149,7 @@ if __name__ == "__main__":
 \end{verbatim}
 
 \module{doctest} then examines docstrings in the module calling
-\function{testmod()}.  If you want to test a different module, you can
-pass that module object to \function{testmod()}.
+\function{testmod()}.
 
 Running the module as a script causes the examples in the docstrings
 to get executed and verified:
@@ -292,35 +294,95 @@ their contained methods and nested classes.
 
 \subsection{What's the Execution Context?}
 
-By default, each time \function{testmod()} finds a docstring to test, it uses
-a \emph{copy} of \module{M}'s globals, so that running tests on a module
+By default, each time \function{testmod()} finds a docstring to test, it
+uses a \emph{shallow copy} of \module{M}'s globals, so that running tests
 doesn't change the module's real globals, and so that one test in
 \module{M} can't leave behind crumbs that accidentally allow another test
 to work.  This means examples can freely use any names defined at top-level
 in \module{M}, and names defined earlier in the docstring being run.
+Examples cannot see names defined in other docstrings.
 
 You can force use of your own dict as the execution context by passing
-\code{globs=your_dict} to \function{testmod()} instead.  Presumably this
-would be a copy of \code{M.__dict__} merged with the globals from other
-imported modules.
+\code{globs=your_dict} to \function{testmod()} instead.
 
 \subsection{What About Exceptions?}
 
-No problem, as long as the only output generated by the example is the
-traceback itself.  For example:
+No problem:  just paste in the expected traceback.  Since
+tracebacks contain details that are likely to change
+rapidly (for example, exact file paths and line numbers), this is one
+case where doctest works hard to be flexible in what it accepts.
+This makes the full story involved, but you really don't have
+to remember much.  Simple 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
->>>
 \end{verbatim}
 
-Note that only the exception type and value are compared (specifically,
-only the last line in the traceback).  The various ``File'' lines in
-between can be left out (unless they add significantly to the documentation
-value of the example).
+That doctest succeeds if, and only if, \exception{ValueError} is raised,
+with the \samp{list.remove(x): x not in list} detail as shown.
+
+The expected output for an exception is divided into four parts.
+First, an example may produce some normal output before an exception
+is raised, although that's unusual.  The "normal output" is taken to
+be everything until the first "Traceback" line, and is usually an
+empty string.  Next, the traceback line must be one of these two, and
+indented the same as the first line in the example:
+
+\begin{verbatim}
+Traceback (most recent call last):
+Traceback (innermost last):
+\end{verbatim}
+
+The most interesting part is the last part:  the line(s) starting with the
+exception type and detail.  This is usually the last line of a traceback,
+but can extend across any number of lines.  After the "Traceback" line,
+doctest simply ignores everything until the first line indented the same as
+the first line of the example, \emph{and} starting with an alphanumeric
+character.  This example illustrates the complexities that are possible:
+
+\begin{verbatim}
+>>> print 1, 2; raise ValueError('printed 1\nand 2\n  but not 3')
+1 2
+Traceback (most recent call last):
+... indented the same, but doesn't start with an alphanumeric
+  not indented the same, so ignored too
+  File "/Python23/lib/doctest.py", line 442, in _run_examples_inner
+    compileflags, 1) in globs
+  File "<string>", line 1, in ?   # and all these are ignored
+ValueError: printed 1
+and 2
+  but not 3
+\end{verbatim}
+
+The first (\samp{1 2}) and last three (starting with
+\exception{ValueError}) lines are compared, and the rest are ignored.
+
+Best practice is to omit the ``File'' lines, unless they add
+significant documentation value to the example.  So the example above
+is probably better as:
+
+\begin{verbatim}
+>>> print 1, 2; raise ValueError('printed 1\nand 2\n  but not 3')
+1 2
+Traceback (most recent call last):
+   ...
+ValueError: printed 1
+and 2
+  but not 3
+\end{verbatim}
+
+Note the tracebacks are treated very specially.  In particular, in the
+rewritten example, the use of \samp{...} is independent of doctest's
+\constant{ELLIPSIS} option.  The ellipsis in that example could
+be left out, or could just as well be three (or three hundred) commas.
+
+\versionchanged[The abilities to check both normal output and an
+                exception in a single example, and to have a multi-line
+                exception detail, were added]{2.4}
+
 
 \subsection{Option Flags and Directive Names\label{doctest-options}}