[Python-checkins] python/dist/src/Doc/lib libdoctest.tex,1.25,1.26

[tim_one at users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv6538/Doc/lib

Modified Files:
	libdoctest.tex 
Log Message:
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.


Index: libdoctest.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdoctest.tex,v
retrieving revision 1.25
retrieving revision 1.26
diff -C2 -d -r1.25 -r1.26
*** libdoctest.tex	13 Aug 2004 01:49:12 -0000	1.25
--- libdoctest.tex	13 Aug 2004 03:55:05 -0000	1.26
***************
*** 109,113 ****
  Trying: [factorial(long(n)) for n in range(6)]
  Expecting: [1, 1, 2, 6, 24, 120]
! ok\end{verbatim}
  
  And so on, eventually ending with:
--- 109,114 ----
  Trying: [factorial(long(n)) for n in range(6)]
  Expecting: [1, 1, 2, 6, 24, 120]
! ok
! \end{verbatim}
  
  And so on, eventually ending with:
***************
*** 130,139 ****
  
  That's all you need to know to start making productive use of
! \module{doctest}!  Jump in.
  
  \subsection{Simple Usage}
  
! The simplest (not necessarily the best) way to start using doctest is to
! end each module \module{M} with:
  
  \begin{verbatim}
--- 131,142 ----
  
  That's all you need to know to start making productive use of
! \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 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}
***************
*** 147,152 ****
  
  \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()}.
  
  Running the module as a script causes the examples in the docstrings
--- 150,154 ----
  
  \module{doctest} then examines docstrings in the module calling
! \function{testmod()}.
  
  Running the module as a script causes the examples in the docstrings
***************
*** 293,312 ****
  \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
  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.
  
  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.
  
  \subsection{What About Exceptions?}
  
! No problem, as long as the only output generated by the example is the
! traceback itself.  For example:
  
  \begin{verbatim}
--- 295,317 ----
  \subsection{What's the Execution Context?}
  
! 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.
  
  \subsection{What About Exceptions?}
  
! 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}
***************
*** 315,325 ****
    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).
  
  \subsection{Option Flags and Directive Names\label{doctest-options}}
--- 320,387 ----
    File "<stdin>", line 1, in ?
  ValueError: list.remove(x): x not in list
  \end{verbatim}
  
! 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}}