<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"lib.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"lib.html" title='Python Library Reference'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"doctest-soapbox.html" />
<link rel=
"prev" href=
"doctest-advanced-api.html" />
<link rel=
"parent" href=
"module-doctest.html" />
<link rel=
"next" href=
"doctest-soapbox.html" />
<meta name='aesop' content='information'
/>
<title>5.2.7 Debugging
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"5.2.6.6 OutputChecker objects"
href=
"doctest-OutputChecker.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"5.2 doctest "
href=
"module-doctest.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"5.2.8 Soapbox"
href=
"doctest-soapbox.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"doctest-OutputChecker.html">5.2.6.6 OutputChecker objects
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"module-doctest.html">5.2 doctest
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"doctest-soapbox.html">5.2.8 Soapbox
</A>
<!--End of Navigation Panel-->
<H2><A NAME=
"SECTION007270000000000000000"></A><A NAME=
"doctest-debugging"></A>
Doctest provides several mechanisms for debugging doctest examples:
<LI>Several functions convert doctests to executable Python
programs, which can be run under the Python debugger,
<tt class=
"module"><a href=
"module-pdb.html">pdb
</a></tt>.
<LI>The
<tt class=
"class">DebugRunner
</tt> class is a subclass of
<tt class=
"class">DocTestRunner
</tt> 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
<LI>The
<tt class=
"module"><a href=
"module-unittest.html">unittest
</a></tt> cases generated by
<tt class=
"function">DocTestSuite()
</tt>
support the
<tt class=
"method">debug()
</tt> method defined by
<tt class=
"class"><tt class=
"module"><a href=
"module-unittest.html">unittest
</a></tt>.TestCase
</tt>.
<LI>You can add a call to
<tt class=
"function"><tt class=
"module"><a href=
"module-pdb.html">pdb
</a></tt>.set_trace()
</tt> 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
<span class=
"file">a.py
</span> contains just this
<div class=
"verbatim"><pre>
... import pdb; pdb.set_trace()
Then an interactive Python session may look like this:
<div class=
"verbatim"><pre>
>>> import a, doctest
>>> doctest.testmod(a)
> <doctest a[
1]
>(
3)g()-
>None
-
> import pdb; pdb.set_trace()
3 -
> import pdb; pdb.set_trace()
> <doctest a[
0]
>(
2)f()-
>None
> <doctest a[
2]
>(
1)?()-
>None
<span class=
"versionnote">Changed in version
2.4:
The ability to use
<code><tt class=
"module"><a href=
"module-pdb.html">pdb
</a></tt>.set_trace()
</code>
usefully inside doctests was added.
</span>
Functions that convert doctests to Python code, and possibly run
the synthesized code under the debugger:
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
1110' xml:id='l2h-
1110'
class=
"function">script_from_examples
</tt></b>(
</nobr></td>
<td><var>s
</var>)
</td></tr></table></dt>
Convert text with examples to a script.
Argument
<var>s
</var> is a string containing doctest examples. The string
is converted to a Python script, where doctest examples in
<var>s
</var>
are converted to regular code, and everything else is converted to
Python comments. The generated script is returned as a string.
<div class=
"verbatim"><pre>
print doctest.script_from_examples(r
"""
<div class=
"verbatim"><pre>
# Set x and y to
1 and
2.
This function is used internally by other functions (see below), but
can also be useful when you want to transform an interactive Python
session into a Python script.
<span class=
"versionnote">New in version
2.4.
</span>
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
1111' xml:id='l2h-
1111'
class=
"function">testsource
</tt></b>(
</nobr></td>
<td><var>module, name
</var>)
</td></tr></table></dt>
Convert the doctest for an object to a script.
Argument
<var>module
</var> is a module object, or dotted name of a module,
containing the object whose doctests are of interest. Argument
<var>name
</var> 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
<tt class=
"function">script_from_examples()
</tt> above. For example, if module
<span class=
"file">a.py
</span> contains a top-level function
<tt class=
"function">f()
</tt>, then
<div class=
"verbatim"><pre>
print doctest.testsource(a,
"a.f")
prints a script version of function
<tt class=
"function">f()
</tt>'s docstring,
with doctests converted to code, and the rest placed in comments.
<span class=
"versionnote">New in version
2.3.
</span>
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
1112' xml:id='l2h-
1112'
class=
"function">debug
</tt></b>(
</nobr></td>
<td><var>module, name
</var><big>[
</big><var>, pm
</var><big>]
</big><var></var>)
</td></tr></table></dt>
Debug the doctests for an object.
The
<var>module
</var> and
<var>name
</var> arguments are the same as for function
<tt class=
"function">testsource()
</tt> 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,
<tt class=
"module"><a href=
"module-pdb.html">pdb
</a></tt>.
A shallow copy of
<code><var>module
</var>.__dict__
</code> is used for both local
and global execution context.
Optional argument
<var>pm
</var> controls whether post-mortem debugging is
used. If
<var>pm
</var> 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><tt class=
"module"><a href=
"module-pdb.html">pdb
</a></tt>.post_mortem()
</code>, passing the traceback object
from the unhandled exception. If
<var>pm
</var> is not specified, or is false,
the script is run under the debugger from the start, via passing an
appropriate
<tt class=
"function">execfile()
</tt> call to
<code><tt class=
"module"><a href=
"module-pdb.html">pdb
</a></tt>.run()
</code>.
<span class=
"versionnote">New in version
2.3.
</span>
<span class=
"versionnote">Changed in version
2.4:
The
<var>pm
</var> argument was added.
</span>
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
1113' xml:id='l2h-
1113'
class=
"function">debug_src
</tt></b>(
</nobr></td>
<td><var>src
</var><big>[
</big><var>, pm
</var><big>]
</big><var></var><big>[
</big><var>, globs
</var><big>]
</big><var></var>)
</td></tr></table></dt>
Debug the doctests in a string.
This is like function
<tt class=
"function">debug()
</tt> above, except that
a string containing doctest examples is specified directly, via
the
<var>src
</var> argument.
Optional argument
<var>pm
</var> has the same meaning as in function
<tt class=
"function">debug()
</tt> above.
Optional argument
<var>globs
</var> gives a dictionary to use as both
local and global execution context. If not specified, or
<code>None
</code>,
an empty dictionary is used. If specified, a shallow copy of the
<span class=
"versionnote">New in version
2.4.
</span>
The
<tt class=
"class">DebugRunner
</tt> 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
<tt class=
"class">DebugRunner
</tt>'s
docstring (which is a doctest!) for more details:
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><span class=
"typelabel">class
</span> <tt id='l2h-
1114' xml:id='l2h-
1114'
class=
"class">DebugRunner
</tt></b>(
</nobr></td>
<td><var></var><big>[
</big><var>checker
</var><big>]
</big><var></var><big>[
</big><var>,
verbose
</var><big>]
</big><var></var><big>[
</big><var>, optionflags
</var><big>]
</big><var></var>)
</td></tr></table></dt>
A subclass of
<tt class=
"class">DocTestRunner
</tt> that raises an exception as
soon as a failure is encountered. If an unexpected exception
occurs, an
<tt class=
"exception">UnexpectedException
</tt> exception is raised,
containing the test, the example, and the original exception. If
the output doesn't match, then a
<tt class=
"exception">DocTestFailure
</tt>
exception is raised, containing the test, the example, and the
For information about the constructor parameters and methods, see
the documentation for
<tt class=
"class">DocTestRunner
</tt> in
section
<A href=
"doctest-advanced-api.html#doctest-advanced-api">5.2.6</A>.
There are two exceptions that may be raised by
<tt class=
"class">DebugRunner
</tt>
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><span class=
"typelabel">exception
</span> <tt id='l2h-
1115' xml:id='l2h-
1115'
class=
"exception">DocTestFailure
</tt></b>(
</nobr></td>
<td><var>test, example, got
</var>)
</td></tr></table></dt>
An exception thrown by
<tt class=
"class">DocTestRunner
</tt> to signal that a
doctest example's actual output did not match its expected output.
The constructor arguments are used to initialize the member
variables of the same names.
<tt class=
"exception">DocTestFailure
</tt> defines the following member variables:
<dl><dt><b><tt id='l2h-
1116' xml:id='l2h-
1116'
class=
"member">test
</tt></b></dt>
The
<tt class=
"class">DocTest
</tt> object that was being run when the example failed.
<dl><dt><b><tt id='l2h-
1117' xml:id='l2h-
1117'
class=
"member">example
</tt></b></dt>
The
<tt class=
"class">Example
</tt> that failed.
<dl><dt><b><tt id='l2h-
1118' xml:id='l2h-
1118'
class=
"member">got
</tt></b></dt>
The example's actual output.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><span class=
"typelabel">exception
</span> <tt id='l2h-
1119' xml:id='l2h-
1119'
class=
"exception">UnexpectedException
</tt></b>(
</nobr></td>
<td><var>test, example, exc_info
</var>)
</td></tr></table></dt>
An exception thrown by
<tt class=
"class">DocTestRunner
</tt> to signal that a
doctest example raised an unexpected exception. The constructor
arguments are used to initialize the member variables of the same
<tt class=
"exception">UnexpectedException
</tt> defines the following member variables:
<dl><dt><b><tt id='l2h-
1120' xml:id='l2h-
1120'
class=
"member">test
</tt></b></dt>
The
<tt class=
"class">DocTest
</tt> object that was being run when the example failed.
<dl><dt><b><tt id='l2h-
1121' xml:id='l2h-
1121'
class=
"member">example
</tt></b></dt>
The
<tt class=
"class">Example
</tt> that failed.
<dl><dt><b><tt id='l2h-
1122' xml:id='l2h-
1122'
class=
"member">exc_info
</tt></b></dt>
A tuple containing information about the unexpected exception, as
returned by
<tt class=
"function">sys.exc_info()
</tt>.
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"5.2.6.6 OutputChecker objects"
href=
"doctest-OutputChecker.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"5.2 doctest "
href=
"module-doctest.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"5.2.8 Soapbox"
href=
"doctest-soapbox.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"doctest-OutputChecker.html">5.2.6.6 OutputChecker objects
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"module-doctest.html">5.2 doctest
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"doctest-soapbox.html">5.2.8 Soapbox
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.