[OpenSPARC-T2-SAM] / 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>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="lib.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="lib.html" title='Python Library Reference' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="next" href="doctest-soapbox.html" />
	13	<link rel="prev" href="doctest-advanced-api.html" />
	14	<link rel="parent" href="module-doctest.html" />
	15	<link rel="next" href="doctest-soapbox.html" />
	16	<meta name='aesop' content='information' />
	17	<title>5.2.7 Debugging</title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="5.2.6.6 OutputChecker objects"
	25	href="doctest-OutputChecker.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="5.2 doctest "
	28	href="module-doctest.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="5.2.8 Soapbox"
	31	href="doctest-soapbox.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Python Library Reference</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	38	border='0' height='32' alt='Module Index' width='32' /></a></td>
	39	<td class='online-navigation'><a rel="index" title="Index"
	40	href="genindex.html"><img src='../icons/index.png'
	41	border='0' height='32' alt='Index' width='32' /></A></td>
	42	</tr></table>
	43	<div class='online-navigation'>
	44	<b class="navlabel">Previous:</b>
	45	<a class="sectref" rel="prev" href="doctest-OutputChecker.html">5.2.6.6 OutputChecker objects</A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="module-doctest.html">5.2 doctest </A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="doctest-soapbox.html">5.2.8 Soapbox</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H2><A NAME="SECTION007270000000000000000"></A><A NAME="doctest-debugging"></A>
	56	<BR>
	57	5.2.7 Debugging
	58	</H2>
	59
	60	<P>
	61	Doctest provides several mechanisms for debugging doctest examples:
	62
	63	<P>
	64
65	<UL>
66	<LI>Several functions convert doctests to executable Python
67	programs, which can be run under the Python debugger, <tt class="module"><a href="module-pdb.html">pdb</a></tt>.
68	</LI>
69	<LI>The <tt class="class">DebugRunner</tt> class is a subclass of
70	<tt class="class">DocTestRunner</tt> that raises an exception for the first
71	failing example, containing information about that example.
72	This information can be used to perform post-mortem debugging on
73	the example.
74	</LI>
75	<LI>The <tt class="module"><a href="module-unittest.html">unittest</a></tt> cases generated by <tt class="function">DocTestSuite()</tt>
76	support the <tt class="method">debug()</tt> method defined by
77	<tt class="class"><tt class="module"><a href="module-unittest.html">unittest</a></tt>.TestCase</tt>.
78	</LI>
79	<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
80	doctest example, and you'll drop into the Python debugger when that
81	line is executed. Then you can inspect current values of variables,
82	and so on. For example, suppose <span class="file">a.py</span> contains just this
83	module docstring:
84
85	<P>
86	<div class="verbatim"><pre>
87	"""
88	>>> def f(x):
89	... g(x*2)
90	>>> def g(x):
91	... print x+3
92	... import pdb; pdb.set_trace()
93	>>> f(3)
94	9
95	"""
96	</pre></div>
97
98	<P>
99	Then an interactive Python session may look like this:
100
101	<P>
102	<div class="verbatim"><pre>
103	>>> import a, doctest
104	>>> doctest.testmod(a)
105	--Return--
106	> <doctest a[1]>(3)g()->None
107	-> import pdb; pdb.set_trace()
108	(Pdb) list
109	1 def g(x):
110	2 print x+3
111	3 -> import pdb; pdb.set_trace()
112	[EOF]
113	(Pdb) print x
114	6
115	(Pdb) step
116	--Return--
117	> <doctest a[0]>(2)f()->None
118	-> g(x*2)
119	(Pdb) list
120	1 def f(x):
121	2 -> g(x*2)
122	[EOF]
123	(Pdb) print x
124	3
125	(Pdb) step
126	--Return--
127	> <doctest a[2]>(1)?()->None
128	-> f(3)
129	(Pdb) cont
130	(0, 3)
131	>>>
132	</pre></div>
133
134	<P>
135
136	<span class="versionnote">Changed in version 2.4:
137	The ability to use <code><tt class="module"><a href="module-pdb.html">pdb</a></tt>.set_trace()</code>
138	usefully inside doctests was added.</span>
139
140	</LI>
141	</UL>
142
143	<P>
144	Functions that convert doctests to Python code, and possibly run
145	the synthesized code under the debugger:
146
147	<P>
148	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
149	<td><nobr><b><tt id='l2h-1110' xml:id='l2h-1110' class="function">script_from_examples</tt></b>(</nobr></td>
150	<td><var>s</var>)</td></tr></table></dt>
151	<dd>
152	Convert text with examples to a script.
153
154	<P>
155	Argument <var>s</var> is a string containing doctest examples. The string
156	is converted to a Python script, where doctest examples in <var>s</var>
157	are converted to regular code, and everything else is converted to
158	Python comments. The generated script is returned as a string.
159	For example,
160
161	<P>
162	<div class="verbatim"><pre>
163	import doctest
164	print doctest.script_from_examples(r"""
165	Set x and y to 1 and 2.
166	>>> x, y = 1, 2
167
168	Print their sum:
169	>>> print x+y
170	3
171	""")
172	</pre></div>
173
174	<P>
175	displays:
176
177	<P>
178	<div class="verbatim"><pre>
179	# Set x and y to 1 and 2.
180	x, y = 1, 2
181	#
182	# Print their sum:
183	print x+y
184	# Expected:
185	## 3
186	</pre></div>
187
188	<P>
189	This function is used internally by other functions (see below), but
190	can also be useful when you want to transform an interactive Python
191	session into a Python script.
192
193	<P>
194
195	<span class="versionnote">New in version 2.4.</span>
196
197	</dl>
198
199	<P>
200	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
201	<td><nobr><b><tt id='l2h-1111' xml:id='l2h-1111' class="function">testsource</tt></b>(</nobr></td>
202	<td><var>module, name</var>)</td></tr></table></dt>
203	<dd>
204	Convert the doctest for an object to a script.
205
206	<P>
207	Argument <var>module</var> is a module object, or dotted name of a module,
208	containing the object whose doctests are of interest. Argument
209	<var>name</var> is the name (within the module) of the object with the
210	doctests of interest. The result is a string, containing the
211	object's docstring converted to a Python script, as described for
212	<tt class="function">script_from_examples()</tt> above. For example, if module
213	<span class="file">a.py</span> contains a top-level function <tt class="function">f()</tt>, then
214
215	<P>
216	<div class="verbatim"><pre>
217	import a, doctest
218	print doctest.testsource(a, "a.f")
219	</pre></div>
220
221	<P>
222	prints a script version of function <tt class="function">f()</tt>'s docstring,
223	with doctests converted to code, and the rest placed in comments.
224
225	<P>
226
227	<span class="versionnote">New in version 2.3.</span>
228
229	</dl>
230
231	<P>
232	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
233	<td><nobr><b><tt id='l2h-1112' xml:id='l2h-1112' class="function">debug</tt></b>(</nobr></td>
234	<td><var>module, name</var><big>[</big><var>, pm</var><big>]</big><var></var>)</td></tr></table></dt>
235	<dd>
236	Debug the doctests for an object.
237
238	<P>
239	The <var>module</var> and <var>name</var> arguments are the same as for function
240	<tt class="function">testsource()</tt> above. The synthesized Python script for the
241	named object's docstring is written to a temporary file, and then that
242	file is run under the control of the Python debugger, <tt class="module"><a href="module-pdb.html">pdb</a></tt>.
243
244	<P>
245	A shallow copy of <code><var>module</var>.__dict__</code> is used for both local
246	and global execution context.
247
248	<P>
249	Optional argument <var>pm</var> controls whether post-mortem debugging is
250	used. If <var>pm</var> has a true value, the script file is run directly, and
251	the debugger gets involved only if the script terminates via raising an
252	unhandled exception. If it does, then post-mortem debugging is invoked,
253	via <code><tt class="module"><a href="module-pdb.html">pdb</a></tt>.post_mortem()</code>, passing the traceback object
254	from the unhandled exception. If <var>pm</var> is not specified, or is false,
255	the script is run under the debugger from the start, via passing an
256	appropriate <tt class="function">execfile()</tt> call to <code><tt class="module"><a href="module-pdb.html">pdb</a></tt>.run()</code>.
257
258	<P>
259
260	<span class="versionnote">New in version 2.3.</span>
261
262	<P>
263
264	<span class="versionnote">Changed in version 2.4:
265	The <var>pm</var> argument was added.</span>
266
267	</dl>
268
269	<P>
270	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
271	<td><nobr><b><tt id='l2h-1113' xml:id='l2h-1113' class="function">debug_src</tt></b>(</nobr></td>
272	<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>
273	<dd>
274	Debug the doctests in a string.
275
276	<P>
277	This is like function <tt class="function">debug()</tt> above, except that
278	a string containing doctest examples is specified directly, via
279	the <var>src</var> argument.
280
281	<P>
282	Optional argument <var>pm</var> has the same meaning as in function
283	<tt class="function">debug()</tt> above.
284
285	<P>
286	Optional argument <var>globs</var> gives a dictionary to use as both
287	local and global execution context. If not specified, or <code>None</code>,
288	an empty dictionary is used. If specified, a shallow copy of the
289	dictionary is used.
290
291	<P>
292
293	<span class="versionnote">New in version 2.4.</span>
294
295	</dl>
296
297	<P>
298	The <tt class="class">DebugRunner</tt> class, and the special exceptions it may raise,
299	are of most interest to testing framework authors, and will only be
300	sketched here. See the source code, and especially <tt class="class">DebugRunner</tt>'s
301	docstring (which is a doctest!) for more details:
302
303	<P>
304	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
305	<td><nobr><b><span class="typelabel">class</span> <tt id='l2h-1114' xml:id='l2h-1114' class="class">DebugRunner</tt></b>(</nobr></td>
306	<td><var></var><big>[</big><var>checker</var><big>]</big><var></var><big>[</big><var>,
307	verbose</var><big>]</big><var></var><big>[</big><var>, optionflags</var><big>]</big><var></var>)</td></tr></table></dt>
308	<dd>
309
310	<P>
311	A subclass of <tt class="class">DocTestRunner</tt> that raises an exception as
312	soon as a failure is encountered. If an unexpected exception
313	occurs, an <tt class="exception">UnexpectedException</tt> exception is raised,
314	containing the test, the example, and the original exception. If
315	the output doesn't match, then a <tt class="exception">DocTestFailure</tt>
316	exception is raised, containing the test, the example, and the
317	actual output.
318
319	<P>
320	For information about the constructor parameters and methods, see
321	the documentation for <tt class="class">DocTestRunner</tt> in
322	section <A href="doctest-advanced-api.html#doctest-advanced-api">5.2.6</A>.
323	</dl>
324
325	<P>
326	There are two exceptions that may be raised by <tt class="class">DebugRunner</tt>
327	instances:
328
329	<P>
330	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
331	<td><nobr><b><span class="typelabel">exception</span> <tt id='l2h-1115' xml:id='l2h-1115' class="exception">DocTestFailure</tt></b>(</nobr></td>
332	<td><var>test, example, got</var>)</td></tr></table></dt>
333	<dd>
334	An exception thrown by <tt class="class">DocTestRunner</tt> to signal that a
335	doctest example's actual output did not match its expected output.
336	The constructor arguments are used to initialize the member
337	variables of the same names.
338	</dl>
339	<tt class="exception">DocTestFailure</tt> defines the following member variables:
340	<dl><dt><b><tt id='l2h-1116' xml:id='l2h-1116' class="member">test</tt></b></dt>
341	<dd>
342	The <tt class="class">DocTest</tt> object that was being run when the example failed.
343	</dl>
344	<dl><dt><b><tt id='l2h-1117' xml:id='l2h-1117' class="member">example</tt></b></dt>
345	<dd>
346	The <tt class="class">Example</tt> that failed.
347	</dl>
348	<dl><dt><b><tt id='l2h-1118' xml:id='l2h-1118' class="member">got</tt></b></dt>
349	<dd>
350	The example's actual output.
351	</dl>
352
353	<P>
354	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
355	<td><nobr><b><span class="typelabel">exception</span> <tt id='l2h-1119' xml:id='l2h-1119' class="exception">UnexpectedException</tt></b>(</nobr></td>
356	<td><var>test, example, exc_info</var>)</td></tr></table></dt>
357	<dd>
358	An exception thrown by <tt class="class">DocTestRunner</tt> to signal that a
359	doctest example raised an unexpected exception. The constructor
360	arguments are used to initialize the member variables of the same
361	names.
362	</dl>
363	<tt class="exception">UnexpectedException</tt> defines the following member variables:
364	<dl><dt><b><tt id='l2h-1120' xml:id='l2h-1120' class="member">test</tt></b></dt>
365	<dd>
366	The <tt class="class">DocTest</tt> object that was being run when the example failed.
367	</dl>
368	<dl><dt><b><tt id='l2h-1121' xml:id='l2h-1121' class="member">example</tt></b></dt>
369	<dd>
370	The <tt class="class">Example</tt> that failed.
371	</dl>
372	<dl><dt><b><tt id='l2h-1122' xml:id='l2h-1122' class="member">exc_info</tt></b></dt>
373	<dd>
374	A tuple containing information about the unexpected exception, as
375	returned by <tt class="function">sys.exc_info()</tt>.
376	</dl>
377
378	<P>
379
380	<DIV CLASS="navigation">
381	<div class='online-navigation'>
382	<p></p><hr />
383	<table align="center" width="100%" cellpadding="0" cellspacing="2">
384	<tr>
385	<td class='online-navigation'><a rel="prev" title="5.2.6.6 OutputChecker objects"
386	href="doctest-OutputChecker.html"><img src='../icons/previous.png'
387	border='0' height='32' alt='Previous Page' width='32' /></A></td>
388	<td class='online-navigation'><a rel="parent" title="5.2 doctest "
389	href="module-doctest.html"><img src='../icons/up.png'
390	border='0' height='32' alt='Up One Level' width='32' /></A></td>
391	<td class='online-navigation'><a rel="next" title="5.2.8 Soapbox"
392	href="doctest-soapbox.html"><img src='../icons/next.png'
393	border='0' height='32' alt='Next Page' width='32' /></A></td>
394	<td align="center" width="100%">Python Library Reference</td>
395	<td class='online-navigation'><a rel="contents" title="Table of Contents"
396	href="contents.html"><img src='../icons/contents.png'
397	border='0' height='32' alt='Contents' width='32' /></A></td>
398	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
399	border='0' height='32' alt='Module Index' width='32' /></a></td>
400	<td class='online-navigation'><a rel="index" title="Index"
401	href="genindex.html"><img src='../icons/index.png'
402	border='0' height='32' alt='Index' width='32' /></A></td>
403	</tr></table>
404	<div class='online-navigation'>
405	<b class="navlabel">Previous:</b>
406	<a class="sectref" rel="prev" href="doctest-OutputChecker.html">5.2.6.6 OutputChecker objects</A>
407	<b class="navlabel">Up:</b>
408	<a class="sectref" rel="parent" href="module-doctest.html">5.2 doctest </A>
409	<b class="navlabel">Next:</b>
410	<a class="sectref" rel="next" href="doctest-soapbox.html">5.2.8 Soapbox</A>
411	</div>
412	</div>
413	<hr />
414	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
415	</DIV>
416	<!--End of Navigation Panel-->
417	<ADDRESS>
418	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
419	</ADDRESS>
420	</BODY>
421	</HTML>