sam-t2/devtools/v9/html/python/lib/doctest-debugging.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<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>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<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>
</tr></table>
<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>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION007270000000000000000"></A><A NAME="doctest-debugging"></A>
<BR>
5.2.7 Debugging
</H2>

<P>
Doctest provides several mechanisms for debugging doctest examples:

<P>

<UL>
<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>
<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
      the example.
</LI>
<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>
<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
      module docstring:

<P>
<div class="verbatim"><pre>
"""
&gt;&gt;&gt; def f(x):
...     g(x*2)
&gt;&gt;&gt; def g(x):
...     print x+3
...     import pdb; pdb.set_trace()
&gt;&gt;&gt; f(3)
9
"""
</pre></div>

<P>
Then an interactive Python session may look like this:

<P>
<div class="verbatim"><pre>
&gt;&gt;&gt; import a, doctest
&gt;&gt;&gt; doctest.testmod(a)
--Return--
&gt; &lt;doctest a[1]&gt;(3)g()-&gt;None
-&gt; import pdb; pdb.set_trace()
(Pdb) list
  1     def g(x):
  2         print x+3
  3  -&gt;     import pdb; pdb.set_trace()
[EOF]
(Pdb) print x
6
(Pdb) step
--Return--
&gt; &lt;doctest a[0]&gt;(2)f()-&gt;None
-&gt; g(x*2)
(Pdb) list
  1     def f(x):
  2  -&gt;     g(x*2)
[EOF]
(Pdb) print x
3
(Pdb) step
--Return--
&gt; &lt;doctest a[2]&gt;(1)?()-&gt;None
-&gt; f(3)
(Pdb) cont
(0, 3)
&gt;&gt;&gt;
</pre></div>

<P>

<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>

</LI>
</UL>

<P>
Functions that convert doctests to Python code, and possibly run
the synthesized code under the debugger:

<P>
<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>
<dd>
  Convert text with examples to a script.

<P>
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.
  For example,

<P>
<div class="verbatim"><pre>
    import doctest
    print doctest.script_from_examples(r"""
        Set x and y to 1 and 2.
        &gt;&gt;&gt; x, y = 1, 2

        Print their sum:
        &gt;&gt;&gt; print x+y
        3
    """)
</pre></div>

<P>
displays:

<P>
<div class="verbatim"><pre>
    # Set x and y to 1 and 2.
    x, y = 1, 2
    #
    # Print their sum:
    print x+y
    # Expected:
    ## 3
</pre></div>

<P>
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.

<P>

<span class="versionnote">New in version 2.4.</span>

</dl>

<P>
<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>
<dd>
   Convert the doctest for an object to a script.

<P>
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

<P>
<div class="verbatim"><pre>
import a, doctest
print doctest.testsource(a, "a.f")
</pre></div>

<P>
prints a script version of function <tt class="function">f()</tt>'s docstring,
  with doctests converted to code, and the rest placed in comments.

<P>

<span class="versionnote">New in version 2.3.</span>

</dl>

<P>
<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>
<dd>
  Debug the doctests for an object.

<P>
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>.

<P>
A shallow copy of <code><var>module</var>.__dict__</code> is used for both local
  and global execution context.

<P>
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>.

<P>

<span class="versionnote">New in version 2.3.</span>

<P>

<span class="versionnote">Changed in version 2.4:
The <var>pm</var> argument was added.</span>

</dl>

<P>
<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>
<dd>
  Debug the doctests in a string.

<P>
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.

<P>
Optional argument <var>pm</var> has the same meaning as in function
  <tt class="function">debug()</tt> above.

<P>
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
  dictionary is used.

<P>

<span class="versionnote">New in version 2.4.</span>

</dl>

<P>
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:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<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>
<dd>

<P>
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
    actual output.

<P>
For information about the constructor parameters and methods, see
    the documentation for <tt class="class">DocTestRunner</tt> in
    section&nbsp;<A href="doctest-advanced-api.html#doctest-advanced-api">5.2.6</A>.
</dl>

<P>
There are two exceptions that may be raised by <tt class="class">DebugRunner</tt>
instances:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">exception</span>&nbsp;<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>
<dd>
    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.
</dl>
<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>
<dd>
    The <tt class="class">DocTest</tt> object that was being run when the example failed.
</dl>
<dl><dt><b><tt id='l2h-1117' xml:id='l2h-1117' class="member">example</tt></b></dt>
<dd>
    The <tt class="class">Example</tt> that failed.
</dl>
<dl><dt><b><tt id='l2h-1118' xml:id='l2h-1118' class="member">got</tt></b></dt>
<dd>
    The example's actual output.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">exception</span>&nbsp;<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>
<dd>
    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
    names.
</dl>
<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>
<dd>
    The <tt class="class">DocTest</tt> object that was being run when the example failed.
</dl>
<dl><dt><b><tt id='l2h-1121' xml:id='l2h-1121' class="member">example</tt></b></dt>
<dd>
    The <tt class="class">Example</tt> that failed.
</dl>
<dl><dt><b><tt id='l2h-1122' xml:id='l2h-1122' class="member">exc_info</tt></b></dt>
<dd>
    A tuple containing information about the unexpected exception, as
    returned by <tt class="function">sys.exc_info()</tt>.
</dl>

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<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>
</tr></table>
<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>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>