[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / html / python / lib / doctest-basic-api.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-unittest-api.html" />
<link rel="prev" href="doctest-how-it-works.html" />
<link rel="parent" href="module-doctest.html" />
<link rel="next" href="doctest-unittest-api.html" />
<meta name='aesop' content='information' />
<title>5.2.4 Basic API</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.3.6 Warnings"
  href="doctest-warnings.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.5 Unittest API"
  href="doctest-unittest-api.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-warnings.html">5.2.3.6 Warnings</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-unittest-api.html">5.2.5 Unittest API</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION007240000000000000000"></A><A NAME="doctest-basic-api"></A>
<BR>
5.2.4 Basic API
</H2>

<P>
The functions <tt class="function">testmod()</tt> and <tt class="function">testfile()</tt> provide a
simple interface to doctest that should be sufficient for most basic
uses.  For a less formal introduction to these two functions, see
sections <A href="doctest-simple-testmod.html#doctest-simple-testmod">5.2.1</A> and
<A href="doctest-simple-testfile.html#doctest-simple-testfile">5.2.2</A>.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1074' xml:id='l2h-1074' class="function">testfile</tt></b>(</nobr></td>
  <td><var>filename</var><big>[</big><var>, module_relative</var><big>]</big><var></var><big>[</big><var>,
                          name</var><big>]</big><var></var><big>[</big><var>, package</var><big>]</big><var></var><big>[</big><var>,
                          globs</var><big>]</big><var></var><big>[</big><var>, verbose</var><big>]</big><var></var><big>[</big><var>,
                          report</var><big>]</big><var></var><big>[</big><var>, optionflags</var><big>]</big><var></var><big>[</big><var>,
                          extraglobs</var><big>]</big><var></var><big>[</big><var>, raise_on_error</var><big>]</big><var></var><big>[</big><var>,
                          parser</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>

<P>
All arguments except <var>filename</var> are optional, and should be
  specified in keyword form.

<P>
Test examples in the file named <var>filename</var>.  Return
  "<tt class="samp">(<var>failure_count</var>, <var>test_count</var>)</tt>".

<P>
Optional argument <var>module_relative</var> specifies how the filename
  should be interpreted:

<P>

<UL>
<LI>If <var>module_relative</var> is <code>True</code> (the default), then
        <var>filename</var> specifies an OS-independent module-relative
        path.  By default, this path is relative to the calling
        module's directory; but if the <var>package</var> argument is
        specified, then it is relative to that package.  To ensure
        OS-independence, <var>filename</var> should use <code>/</code> characters
        to separate path segments, and may not be an absolute path
        (i.e., it may not begin with <code>/</code>).
</LI>
<LI>If <var>module_relative</var> is <code>False</code>, then <var>filename</var>
        specifies an OS-specific path.  The path may be absolute or
        relative; relative paths are resolved with respect to the
        current working directory.
  
</LI>
</UL>

<P>
Optional argument <var>name</var> gives the name of the test; by default,
  or if <code>None</code>, <code>os.path.basename(<var>filename</var>)</code> is used.

<P>
Optional argument <var>package</var> is a Python package or the name of a
  Python package whose directory should be used as the base directory
  for a module-relative filename.  If no package is specified, then
  the calling module's directory is used as the base directory for
  module-relative filenames.  It is an error to specify <var>package</var>
  if <var>module_relative</var> is <code>False</code>.

<P>
Optional argument <var>globs</var> gives a dict to be used as the globals
  when executing examples.  A new shallow copy of this dict is
  created for the doctest, so its examples start with a clean slate.
  By default, or if <code>None</code>, a new empty dict is used.

<P>
Optional argument <var>extraglobs</var> gives a dict merged into the
  globals used to execute examples.  This works like
  <tt class="method">dict.update()</tt>:  if <var>globs</var> and <var>extraglobs</var> have a
  common key, the associated value in <var>extraglobs</var> appears in the
  combined dict.  By default, or if <code>None</code>, no extra globals are
  used.  This is an advanced feature that allows parameterization of
  doctests.  For example, a doctest can be written for a base class, using
  a generic name for the class, then reused to test any number of
  subclasses by passing an <var>extraglobs</var> dict mapping the generic
  name to the subclass to be tested.

<P>
Optional argument <var>verbose</var> prints lots of stuff if true, and prints
  only failures if false; by default, or if <code>None</code>, it's true
  if and only if <code>'-v'</code> is in <code>sys.argv</code>.

<P>
Optional argument <var>report</var> prints a summary at the end when true,
  else prints nothing at the end.  In verbose mode, the summary is
  detailed, else the summary is very brief (in fact, empty if all tests
  passed).

<P>
Optional argument <var>optionflags</var> or's together option flags.  See
  section&nbsp;<A href="doctest-options.html#doctest-options">5.2.3</A>.

<P>
Optional argument <var>raise_on_error</var> defaults to false.  If true,
  an exception is raised upon the first failure or unexpected exception
  in an example.  This allows failures to be post-mortem debugged.
  Default behavior is to continue running examples.

<P>
Optional argument <var>parser</var> specifies a <tt class="class">DocTestParser</tt> (or
  subclass) that should be used to extract tests from the files.  It
  defaults to a normal parser (i.e., <code><tt class="class">DocTestParser</tt>()</code>).

<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-1075' xml:id='l2h-1075' class="function">testmod</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>m</var><big>]</big><var></var><big>[</big><var>, name</var><big>]</big><var></var><big>[</big><var>,
                          globs</var><big>]</big><var></var><big>[</big><var>, verbose</var><big>]</big><var></var><big>[</big><var>,
                          isprivate</var><big>]</big><var></var><big>[</big><var>, report</var><big>]</big><var></var><big>[</big><var>,
                          optionflags</var><big>]</big><var></var><big>[</big><var>, extraglobs</var><big>]</big><var></var><big>[</big><var>,
                          raise_on_error</var><big>]</big><var></var><big>[</big><var>, exclude_empty</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>

<P>
All arguments are optional, and all except for <var>m</var> should be
  specified in keyword form.

<P>
Test examples in docstrings in functions and classes reachable
  from module <var>m</var> (or module <tt class="module">__main__</tt> if <var>m</var> is not
  supplied or is <code>None</code>), starting with <code><var>m</var>.__doc__</code>.

<P>
Also test examples reachable from dict <code><var>m</var>.__test__</code>, if it
  exists and is not <code>None</code>.  <code><var>m</var>.__test__</code> maps
  names (strings) to functions, classes and strings; function and class
  docstrings are searched for examples; strings are searched directly,
  as if they were docstrings.

<P>
Only docstrings attached to objects belonging to module <var>m</var> are
  searched.

<P>
Return "<tt class="samp">(<var>failure_count</var>, <var>test_count</var>)</tt>".

<P>
Optional argument <var>name</var> gives the name of the module; by default,
  or if <code>None</code>, <code><var>m</var>.__name__</code> is used.

<P>
Optional argument <var>exclude_empty</var> defaults to false.  If true,
  objects for which no doctests are found are excluded from consideration.
  The default is a backward compatibility hack, so that code still
  using <tt class="method">doctest.master.summarize()</tt> in conjunction with
  <tt class="function">testmod()</tt> continues to get output for objects with no tests.
  The <var>exclude_empty</var> argument to the newer <tt class="class">DocTestFinder</tt>
  constructor defaults to true.

<P>
Optional arguments <var>extraglobs</var>, <var>verbose</var>, <var>report</var>,
  <var>optionflags</var>, <var>raise_on_error</var>, and <var>globs</var> are the same as
  for function <tt class="function">testfile()</tt> above, except that <var>globs</var>
  defaults to <code><var>m</var>.__dict__</code>.

<P>
Optional argument <var>isprivate</var> specifies a function used to
  determine whether a name is private.  The default function treats
  all names as public.  <var>isprivate</var> can be set to
  <code>doctest.is_private</code> to skip over names that are
  private according to Python's underscore naming convention.
  <div class="versionnote"><b>Deprecated since release 2.4.</b>
<var>isprivate</var> was a stupid idea - don't use it.
  If you need to skip tests based on name, filter the list returned by
  <code>DocTestFinder.find()</code> instead.</div><p></p>

<P>

<span class="versionnote">Changed in version 2.3:
The parameter <var>optionflags</var> was added.</span>

<P>

<span class="versionnote">Changed in version 2.4:
The parameters <var>extraglobs</var>, <var>raise_on_error</var>
                  and <var>exclude_empty</var> were added.</span>

</dl>

<P>
There's also a function to run the doctests associated with a single object.
This function is provided for backward compatibility.  There are no plans
to deprecate it, but it's rarely useful:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1076' xml:id='l2h-1076' class="function">run_docstring_examples</tt></b>(</nobr></td>
  <td><var>f, globs</var><big>[</big><var>,
                            verbose</var><big>]</big><var></var><big>[</big><var>, name</var><big>]</big><var></var><big>[</big><var>,
                            compileflags</var><big>]</big><var></var><big>[</big><var>, optionflags</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>

<P>
Test examples associated with object <var>f</var>; for example, <var>f</var> may
  be a module, function, or class object.

<P>
A shallow copy of dictionary argument <var>globs</var> is used for the
  execution context.

<P>
Optional argument <var>name</var> is used in failure messages, and defaults
  to <code>"NoName"</code>.

<P>
If optional argument <var>verbose</var> is true, output is generated even
  if there are no failures.  By default, output is generated only in case
  of an example failure.

<P>
Optional argument <var>compileflags</var> gives the set of flags that should
  be used by the Python compiler when running the examples.  By default, or
  if <code>None</code>, flags are deduced corresponding to the set of future
  features found in <var>globs</var>.

<P>
Optional argument <var>optionflags</var> works as for function
  <tt class="function">testfile()</tt> above.
</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.3.6 Warnings"
  href="doctest-warnings.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.5 Unittest API"
  href="doctest-unittest-api.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-warnings.html">5.2.3.6 Warnings</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-unittest-api.html">5.2.5 Unittest API</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-unittest-api.html" />
	13	<link rel="prev" href="doctest-how-it-works.html" />
	14	<link rel="parent" href="module-doctest.html" />
	15	<link rel="next" href="doctest-unittest-api.html" />
	16	<meta name='aesop' content='information' />
	17	<title>5.2.4 Basic API</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.3.6 Warnings"
	25	href="doctest-warnings.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.5 Unittest API"
	31	href="doctest-unittest-api.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-warnings.html">5.2.3.6 Warnings</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-unittest-api.html">5.2.5 Unittest API</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H2><A NAME="SECTION007240000000000000000"></A><A NAME="doctest-basic-api"></A>
	56	<BR>
	57	5.2.4 Basic API
	58	</H2>
	59
	60	<P>
	61	The functions <tt class="function">testmod()</tt> and <tt class="function">testfile()</tt> provide a
	62	simple interface to doctest that should be sufficient for most basic
	63	uses. For a less formal introduction to these two functions, see
	64	sections <A href="doctest-simple-testmod.html#doctest-simple-testmod">5.2.1</A> and
65	<A href="doctest-simple-testfile.html#doctest-simple-testfile">5.2.2</A>.
66
67	<P>
68	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
69	<td><nobr><b><tt id='l2h-1074' xml:id='l2h-1074' class="function">testfile</tt></b>(</nobr></td>
70	<td><var>filename</var><big>[</big><var>, module_relative</var><big>]</big><var></var><big>[</big><var>,
71	name</var><big>]</big><var></var><big>[</big><var>, package</var><big>]</big><var></var><big>[</big><var>,
72	globs</var><big>]</big><var></var><big>[</big><var>, verbose</var><big>]</big><var></var><big>[</big><var>,
73	report</var><big>]</big><var></var><big>[</big><var>, optionflags</var><big>]</big><var></var><big>[</big><var>,
74	extraglobs</var><big>]</big><var></var><big>[</big><var>, raise_on_error</var><big>]</big><var></var><big>[</big><var>,
75	parser</var><big>]</big><var></var>)</td></tr></table></dt>
76	<dd>
77
78	<P>
79	All arguments except <var>filename</var> are optional, and should be
80	specified in keyword form.
81
82	<P>
83	Test examples in the file named <var>filename</var>. Return
84	"<tt class="samp">(<var>failure_count</var>, <var>test_count</var>)</tt>".
85
86	<P>
87	Optional argument <var>module_relative</var> specifies how the filename
88	should be interpreted:
89
90	<P>
91
92	<UL>
93	<LI>If <var>module_relative</var> is <code>True</code> (the default), then
94	<var>filename</var> specifies an OS-independent module-relative
95	path. By default, this path is relative to the calling
96	module's directory; but if the <var>package</var> argument is
97	specified, then it is relative to that package. To ensure
98	OS-independence, <var>filename</var> should use <code>/</code> characters
99	to separate path segments, and may not be an absolute path
100	(i.e., it may not begin with <code>/</code>).
101	</LI>
102	<LI>If <var>module_relative</var> is <code>False</code>, then <var>filename</var>
103	specifies an OS-specific path. The path may be absolute or
104	relative; relative paths are resolved with respect to the
105	current working directory.
106
107	</LI>
108	</UL>
109
110	<P>
111	Optional argument <var>name</var> gives the name of the test; by default,
112	or if <code>None</code>, <code>os.path.basename(<var>filename</var>)</code> is used.
113
114	<P>
115	Optional argument <var>package</var> is a Python package or the name of a
116	Python package whose directory should be used as the base directory
117	for a module-relative filename. If no package is specified, then
118	the calling module's directory is used as the base directory for
119	module-relative filenames. It is an error to specify <var>package</var>
120	if <var>module_relative</var> is <code>False</code>.
121
122	<P>
123	Optional argument <var>globs</var> gives a dict to be used as the globals
124	when executing examples. A new shallow copy of this dict is
125	created for the doctest, so its examples start with a clean slate.
126	By default, or if <code>None</code>, a new empty dict is used.
127
128	<P>
129	Optional argument <var>extraglobs</var> gives a dict merged into the
130	globals used to execute examples. This works like
131	<tt class="method">dict.update()</tt>: if <var>globs</var> and <var>extraglobs</var> have a
132	common key, the associated value in <var>extraglobs</var> appears in the
133	combined dict. By default, or if <code>None</code>, no extra globals are
134	used. This is an advanced feature that allows parameterization of
135	doctests. For example, a doctest can be written for a base class, using
136	a generic name for the class, then reused to test any number of
137	subclasses by passing an <var>extraglobs</var> dict mapping the generic
138	name to the subclass to be tested.
139
140	<P>
141	Optional argument <var>verbose</var> prints lots of stuff if true, and prints
142	only failures if false; by default, or if <code>None</code>, it's true
143	if and only if <code>'-v'</code> is in <code>sys.argv</code>.
144
145	<P>
146	Optional argument <var>report</var> prints a summary at the end when true,
147	else prints nothing at the end. In verbose mode, the summary is
148	detailed, else the summary is very brief (in fact, empty if all tests
149	passed).
150
151	<P>
152	Optional argument <var>optionflags</var> or's together option flags. See
153	section <A href="doctest-options.html#doctest-options">5.2.3</A>.
154
155	<P>
156	Optional argument <var>raise_on_error</var> defaults to false. If true,
157	an exception is raised upon the first failure or unexpected exception
158	in an example. This allows failures to be post-mortem debugged.
159	Default behavior is to continue running examples.
160
161	<P>
162	Optional argument <var>parser</var> specifies a <tt class="class">DocTestParser</tt> (or
163	subclass) that should be used to extract tests from the files. It
164	defaults to a normal parser (i.e., <code><tt class="class">DocTestParser</tt>()</code>).
165
166	<P>
167
168	<span class="versionnote">New in version 2.4.</span>
169
170	</dl>
171
172	<P>
173	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
174	<td><nobr><b><tt id='l2h-1075' xml:id='l2h-1075' class="function">testmod</tt></b>(</nobr></td>
175	<td><var></var><big>[</big><var>m</var><big>]</big><var></var><big>[</big><var>, name</var><big>]</big><var></var><big>[</big><var>,
176	globs</var><big>]</big><var></var><big>[</big><var>, verbose</var><big>]</big><var></var><big>[</big><var>,
177	isprivate</var><big>]</big><var></var><big>[</big><var>, report</var><big>]</big><var></var><big>[</big><var>,
178	optionflags</var><big>]</big><var></var><big>[</big><var>, extraglobs</var><big>]</big><var></var><big>[</big><var>,
179	raise_on_error</var><big>]</big><var></var><big>[</big><var>, exclude_empty</var><big>]</big><var></var>)</td></tr></table></dt>
180	<dd>
181
182	<P>
183	All arguments are optional, and all except for <var>m</var> should be
184	specified in keyword form.
185
186	<P>
187	Test examples in docstrings in functions and classes reachable
188	from module <var>m</var> (or module <tt class="module">__main__</tt> if <var>m</var> is not
189	supplied or is <code>None</code>), starting with <code><var>m</var>.__doc__</code>.
190
191	<P>
192	Also test examples reachable from dict <code><var>m</var>.__test__</code>, if it
193	exists and is not <code>None</code>. <code><var>m</var>.__test__</code> maps
194	names (strings) to functions, classes and strings; function and class
195	docstrings are searched for examples; strings are searched directly,
196	as if they were docstrings.
197
198	<P>
199	Only docstrings attached to objects belonging to module <var>m</var> are
200	searched.
201
202	<P>
203	Return "<tt class="samp">(<var>failure_count</var>, <var>test_count</var>)</tt>".
204
205	<P>
206	Optional argument <var>name</var> gives the name of the module; by default,
207	or if <code>None</code>, <code><var>m</var>.__name__</code> is used.
208
209	<P>
210	Optional argument <var>exclude_empty</var> defaults to false. If true,
211	objects for which no doctests are found are excluded from consideration.
212	The default is a backward compatibility hack, so that code still
213	using <tt class="method">doctest.master.summarize()</tt> in conjunction with
214	<tt class="function">testmod()</tt> continues to get output for objects with no tests.
215	The <var>exclude_empty</var> argument to the newer <tt class="class">DocTestFinder</tt>
216	constructor defaults to true.
217
218	<P>
219	Optional arguments <var>extraglobs</var>, <var>verbose</var>, <var>report</var>,
220	<var>optionflags</var>, <var>raise_on_error</var>, and <var>globs</var> are the same as
221	for function <tt class="function">testfile()</tt> above, except that <var>globs</var>
222	defaults to <code><var>m</var>.__dict__</code>.
223
224	<P>
225	Optional argument <var>isprivate</var> specifies a function used to
226	determine whether a name is private. The default function treats
227	all names as public. <var>isprivate</var> can be set to
228	<code>doctest.is_private</code> to skip over names that are
229	private according to Python's underscore naming convention.
230	<div class="versionnote"><b>Deprecated since release 2.4.</b>
231	<var>isprivate</var> was a stupid idea - don't use it.
232	If you need to skip tests based on name, filter the list returned by
233	<code>DocTestFinder.find()</code> instead.</div><p></p>
234
235	<P>
236
237	<span class="versionnote">Changed in version 2.3:
238	The parameter <var>optionflags</var> was added.</span>
239
240	<P>
241
242	<span class="versionnote">Changed in version 2.4:
243	The parameters <var>extraglobs</var>, <var>raise_on_error</var>
244	and <var>exclude_empty</var> were added.</span>
245
246	</dl>
247
248	<P>
249	There's also a function to run the doctests associated with a single object.
250	This function is provided for backward compatibility. There are no plans
251	to deprecate it, but it's rarely useful:
252
253	<P>
254	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
255	<td><nobr><b><tt id='l2h-1076' xml:id='l2h-1076' class="function">run_docstring_examples</tt></b>(</nobr></td>
256	<td><var>f, globs</var><big>[</big><var>,
257	verbose</var><big>]</big><var></var><big>[</big><var>, name</var><big>]</big><var></var><big>[</big><var>,
258	compileflags</var><big>]</big><var></var><big>[</big><var>, optionflags</var><big>]</big><var></var>)</td></tr></table></dt>
259	<dd>
260
261	<P>
262	Test examples associated with object <var>f</var>; for example, <var>f</var> may
263	be a module, function, or class object.
264
265	<P>
266	A shallow copy of dictionary argument <var>globs</var> is used for the
267	execution context.
268
269	<P>
270	Optional argument <var>name</var> is used in failure messages, and defaults
271	to <code>"NoName"</code>.
272
273	<P>
274	If optional argument <var>verbose</var> is true, output is generated even
275	if there are no failures. By default, output is generated only in case
276	of an example failure.
277
278	<P>
279	Optional argument <var>compileflags</var> gives the set of flags that should
280	be used by the Python compiler when running the examples. By default, or
281	if <code>None</code>, flags are deduced corresponding to the set of future
282	features found in <var>globs</var>.
283
284	<P>
285	Optional argument <var>optionflags</var> works as for function
286	<tt class="function">testfile()</tt> above.
287	</dl>
288
289	<P>
290
291	<DIV CLASS="navigation">
292	<div class='online-navigation'>
293	<p></p><hr />
294	<table align="center" width="100%" cellpadding="0" cellspacing="2">
295	<tr>
296	<td class='online-navigation'><a rel="prev" title="5.2.3.6 Warnings"
297	href="doctest-warnings.html"><img src='../icons/previous.png'
298	border='0' height='32' alt='Previous Page' width='32' /></A></td>
299	<td class='online-navigation'><a rel="parent" title="5.2 doctest "
300	href="module-doctest.html"><img src='../icons/up.png'
301	border='0' height='32' alt='Up One Level' width='32' /></A></td>
302	<td class='online-navigation'><a rel="next" title="5.2.5 Unittest API"
303	href="doctest-unittest-api.html"><img src='../icons/next.png'
304	border='0' height='32' alt='Next Page' width='32' /></A></td>
305	<td align="center" width="100%">Python Library Reference</td>
306	<td class='online-navigation'><a rel="contents" title="Table of Contents"
307	href="contents.html"><img src='../icons/contents.png'
308	border='0' height='32' alt='Contents' width='32' /></A></td>
309	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
310	border='0' height='32' alt='Module Index' width='32' /></a></td>
311	<td class='online-navigation'><a rel="index" title="Index"
312	href="genindex.html"><img src='../icons/index.png'
313	border='0' height='32' alt='Index' width='32' /></A></td>
314	</tr></table>
315	<div class='online-navigation'>
316	<b class="navlabel">Previous:</b>
317	<a class="sectref" rel="prev" href="doctest-warnings.html">5.2.3.6 Warnings</A>
318	<b class="navlabel">Up:</b>
319	<a class="sectref" rel="parent" href="module-doctest.html">5.2 doctest </A>
320	<b class="navlabel">Next:</b>
321	<a class="sectref" rel="next" href="doctest-unittest-api.html">5.2.5 Unittest API</A>
322	</div>
323	</div>
324	<hr />
325	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
326	</DIV>
327	<!--End of Navigation Panel-->
328	<ADDRESS>
329	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
330	</ADDRESS>
331	</BODY>
332	</HTML>