[Python-checkins] python/dist/src/Doc/lib libdoctest.tex,1.55,1.56
tim_one at users.sourceforge.net
tim_one at users.sourceforge.net
Sun Sep 26 07:10:03 CEST 2004
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv848/doc/lib
Modified Files:
libdoctest.tex
Log Message:
Added a lot of new stuff to the debugging section.
Index: libdoctest.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdoctest.tex,v
retrieving revision 1.55
retrieving revision 1.56
diff -u -d -r1.55 -r1.56
--- libdoctest.tex 26 Sep 2004 02:38:41 -0000 1.55
+++ libdoctest.tex 26 Sep 2004 05:09:59 -0000 1.56
@@ -1547,34 +1547,174 @@
\subsection{Debugging\label{doctest-debugging}}
-Doctest provides three mechanisms for debugging doctest examples:
+Doctest provides several mechanisms for debugging doctest examples:
-\begin{enumerate}
-\item The \function{debug()} function converts a specified doctest
- to a Python script, and executes that script using \module{pdb}.
+\begin{itemize}
+\item Several functions convert doctests to executable Python
+ programs, which can be run under the Python debugger, \refmodule{pdb}.
\item The \class{DebugRunner} class is a subclass of
\class{DocTestRunner} that raises an exception for the first
failing example, containing information about that example.
This information can be used to perform post-mortem debugging on
the example.
-\item The unittest cases generated by \function{DocTestSuite()}
- support the \method{debug} method defined by
+\item The \module{unittest} cases generated by \function{DocTestSuite()}
+ support the \method{debug()} method defined by
\class{unittest.TestCase}.
-\end{enumerate}
+\item You can add a call to \function{pdb.set_trace()} in a doctest
+ example, and you'll drop into the Python debugger when that
+ line is executed. Then you can inspect current values of variables,
+ and so on. For example, suppose \file{a.py} contains just this
+ module docstring:
-\begin{funcdesc}{debug}{module, name}
- Debug a single doctest docstring.
+\begin{verbatim}
+"""
+>>> def f(x):
+... g(x*2)
+>>> def g(x):
+... print x+3
+... import pdb; pdb.set_trace()
+>>> f(3)
+9
+"""
+\end{verbatim}
- Provide the \var{module} (or dotted name of the module) containing
- the docstring to be debugged and the fully qualified dotted
- \var{name} of the object with the docstring to be debugged.
+ Then an interactive Python session may look like this:
+
+\begin{verbatim}
+>>> import a, doctest
+>>> doctest.testmod(a)
+--Return--
+> <doctest a[1]>(3)g()->None
+-> import pdb; pdb.set_trace()
+(Pdb) list
+ 1 def g(x):
+ 2 print x+3
+ 3 -> import pdb; pdb.set_trace()
+[EOF]
+(Pdb) print x
+6
+(Pdb) step
+--Return--
+> <doctest a[0]>(2)f()->None
+-> g(x*2)
+(Pdb) list
+ 1 def f(x):
+ 2 -> g(x*2)
+[EOF]
+(Pdb) print x
+3
+(Pdb) step
+--Return--
+> <doctest a[2]>(1)?()->None
+-> f(3)
+(Pdb) cont
+(0, 3)
+>>>
+\end{verbatim}
+
+ \versionchanged[The ability to use \code{pdb.set_trace()} usefully
+ inside doctests was added]{2.4}
+\end{itemize}
+
+Functions that convert doctests to Python code, and possibly run
+the synthesized code under the debugger:
+
+\begin{funcdesc}{script_from_examples}{s}
+ Convert text with examples to a script.
+
+ Argument \var{s} is a string containing doctest examples. The string
+ is converted to a Python script, where doctest examples in \var{s}
+ are converted to regular code, and everything else is converted to
+ Python comments. The generated script is returned as a string.
+ For example, given file \file{a.py} as above,
+
+ \begin{verbatim}
+ >>> print doctest.script_from_examples(open("a.py").read())
+ # """
+ def f(x):
+ g(x*2)
+ def g(x):
+ print x+3
+ import pdb; pdb.set_trace()
+ f(3)
+ # Expected:
+ ## 9
+ ## """
+ \end{verbatim}
+
+ \versionadded{2.4}
+\end{funcdesc}
+
+\begin{funcdesc}{testsource}{module, name}
+ Convert the doctest for an object to a script.
+
+ Argument \var{module} is a module object, or dotted name of a module,
+ containing the object whose doctests are of interest. Argument
+ \var{name} is the name (within the module) of the object with the
+ doctests of interest. The result is a string, containing the
+ object's docstring converted to a Python script, as described for
+ \function{script_from_examples()} above. For example, if module
+ \file{a.py} contains a top-level function \function{f()}, then
+
+ \begin{verbatim}
+ import a, doctest
+ print doctest.testsource(a, "a.f")
+ \end{verbatim}
+
+ prints a script version of function \function{f()}'s docstring,
+ with doctests converted to code, and the rest placed in comments.
+
+ \versionadded{2.3}
+\end{funcdesc}
+
+\begin{funcdesc}{debug}{module, name\optional{, pm}}
+ Debug the doctests for an object.
+
+ The \var{module} and \var{name} arguments are the same as for function
+ \function{testsource()} above. The synthesized Python script for the
+ named object's docstring is written to a temporary file, and then that
+ file is run under the control of the Python debugger, \refmodule{pdb}.
+
+ A shallow copy of \code{\var{module}.__dict__} is used for both local
+ and global execution context.
+
+ Optional argument \var{pm} controls whether post-mortem debugging is
+ used. If \var{pm} has a true value, the script file is run directly,
+ and the debugger gets involved only if the script terminates via raising
+ an unhandled exception. If it does, then post-mortem debugging is
+ invoked, via \code{pdb.post_mortem()}, passing the traceback object
+ from the unhandled exception. If \var{pm} is not specified, or is false,
+ the script is run under the debugger from the start, via passing an
+ appropriate \function{execfile()} call to \code{pdb.run()}.
- The doctest examples are extracted (see function \function{testsource()}),
- and written to a temporary file. The Python debugger, \refmodule{pdb},
- is then invoked on that file.
\versionadded{2.3}
+
+ \versionchanged[The \var{pm} argument was added]{2.4}
+\end{funcdesc}
+
+\begin{funcdesc}{debug_src}{src\optional{, pm}\optional{, globs}}
+ Debug the doctests in a string.
+
+ This is like function \function{debug()} above, except that
+ a string containing doctest examples is specified directly, via
+ the \var{src} argument.
+
+ Optional argument \var{pm} has the same meaning as in function
+ \function{debug()} above.
+
+ Optional argument \var{globs} gives a dictionary to use as both
+ local and global execution context. If not specified, or \code{None},
+ an empty dictionary is used. If specified, a shallow copy of the
+ dictionary is used.
+
+ \versionadded{2.4}
\end{funcdesc}
+The \class{DebugRunner} class, and the special exceptions it may raise,
+are of most interest to testing framework authors, and will only be
+sketched here. See the source code, and especially \class{DebugRunner}'s
+docstring (which is a doctest!) for more details:
+
\begin{classdesc}{DebugRunner}{\optional{checker}\optional{,
verbose}\optional{, optionflags}}
@@ -1591,6 +1731,9 @@
section~\ref{doctest-advanced-api}.
\end{classdesc}
+There are two exceptions that may be raised by \class{DebugRunner}
+instances:
+
\begin{excclassdesc}{DocTestFailure}{test, example, got}
An exception thrown by \class{DocTestRunner} to signal that a
doctest example's actual output did not match its expected output.
@@ -1608,20 +1751,7 @@
The example's actual output.
\end{memberdesc}
-\begin{funcdesc}{testsource}{module, name}
- Extract the doctest examples from a docstring.
-
- Provide the \var{module} (or dotted name of the module) containing the
- tests to be extracted and the \var{name} (within the module) of the object
- with the docstring containing the tests to be extracted.
-
- The doctest examples are returned as a string containing Python
- code. The expected output blocks in the examples are converted
- to Python comments.
- \versionadded{2.3}
-\end{funcdesc}
-
-\begin{excclassdesc}{UnexpectedException}{test, example, got}
+\begin{excclassdesc}{UnexpectedException}{test, example, exc_info}
An exception thrown by \class{DocTestRunner} to signal that a
doctest example raised an unexpected exception. The constructor
arguments are used to initialize the member variables of the same
More information about the Python-checkins
mailing list