[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / lib / doctest-simple-testfile.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-how-it-works.html" />
<link rel="prev" href="doctest-simple-testmod.html" />
<link rel="parent" href="module-doctest.html" />
<link rel="next" href="doctest-how-it-works.html" />
<meta name='aesop' content='information' />
<title>5.2.2 Simple Usage: Checking Examples in a Text File</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.1 Simple Usage: Checking"
  href="doctest-simple-testmod.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.3 How It Works"
  href="doctest-how-it-works.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-simple-testmod.html">5.2.1 Simple Usage: Checking</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-how-it-works.html">5.2.3 How It Works</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION007220000000000000000"></A><A NAME="doctest-simple-testfile"></A>
<BR>
5.2.2 Simple Usage: Checking Examples in a Text
            File
</H2>

<P>
Another simple application of doctest is testing interactive examples
in a text file.  This can be done with the <tt class="function">testfile()</tt>
function:

<P>
<div class="verbatim"><pre>
import doctest
doctest.testfile("example.txt")
</pre></div>

<P>
That short script executes and verifies any interactive Python
examples contained in the file <span class="file">example.txt</span>.  The file content
is treated as if it were a single giant docstring; the file doesn't
need to contain a Python program!   For example, perhaps <span class="file">example.txt</span>
contains this:

<P>
<div class="verbatim"><pre>
The ``example`` module
======================

Using ``factorial``
-------------------

This is an example text file in reStructuredText format.  First import
``factorial`` from the ``example`` module:

    &gt;&gt;&gt; from example import factorial

Now use it:

    &gt;&gt;&gt; factorial(6)
    120
</pre></div>

<P>
Running <code>doctest.testfile("example.txt")</code> then finds the error
in this documentation:

<P>
<div class="verbatim"><pre>
File "./example.txt", line 14, in example.txt
Failed example:
    factorial(6)
Expected:
    120
Got:
    720
</pre></div>

<P>
As with <tt class="function">testmod()</tt>, <tt class="function">testfile()</tt> won't display anything
unless an example fails.  If an example does fail, then the failing
example(s) and the cause(s) of the failure(s) are printed to stdout, using
the same format as <tt class="function">testmod()</tt>.

<P>
By default, <tt class="function">testfile()</tt> looks for files in the calling
module's directory.  See section&nbsp;<A href="doctest-basic-api.html#doctest-basic-api">5.2.4</A> for a
description of the optional arguments that can be used to tell it to
look for files in other locations.

<P>
Like <tt class="function">testmod()</tt>, <tt class="function">testfile()</tt>'s verbosity can be
set with the <b class="programopt">-v</b> command-line switch or with the optional
keyword argument <var>verbose</var>.

<P>
For more information on <tt class="function">testfile()</tt>, see
section&nbsp;<A href="doctest-basic-api.html#doctest-basic-api">5.2.4</A>.

<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.1 Simple Usage: Checking"
  href="doctest-simple-testmod.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.3 How It Works"
  href="doctest-how-it-works.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-simple-testmod.html">5.2.1 Simple Usage: Checking</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-how-it-works.html">5.2.3 How It Works</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-how-it-works.html" />
	13	<link rel="prev" href="doctest-simple-testmod.html" />
	14	<link rel="parent" href="module-doctest.html" />
	15	<link rel="next" href="doctest-how-it-works.html" />
	16	<meta name='aesop' content='information' />
	17	<title>5.2.2 Simple Usage: Checking Examples in a Text File</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.1 Simple Usage: Checking"
	25	href="doctest-simple-testmod.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.3 How It Works"
	31	href="doctest-how-it-works.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-simple-testmod.html">5.2.1 Simple Usage: Checking</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-how-it-works.html">5.2.3 How It Works</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H2><A NAME="SECTION007220000000000000000"></A><A NAME="doctest-simple-testfile"></A>
	56	<BR>
	57	5.2.2 Simple Usage: Checking Examples in a Text
	58	File
	59	</H2>
	60
	61	<P>
	62	Another simple application of doctest is testing interactive examples
	63	in a text file. This can be done with the <tt class="function">testfile()</tt>
	64	function:
65
66	<P>
67	<div class="verbatim"><pre>
68	import doctest
69	doctest.testfile("example.txt")
70	</pre></div>
71
72	<P>
73	That short script executes and verifies any interactive Python
74	examples contained in the file <span class="file">example.txt</span>. The file content
75	is treated as if it were a single giant docstring; the file doesn't
76	need to contain a Python program! For example, perhaps <span class="file">example.txt</span>
77	contains this:
78
79	<P>
80	<div class="verbatim"><pre>
81	The ``example`` module
82	======================
83
84	Using ``factorial``
85	-------------------
86
87	This is an example text file in reStructuredText format. First import
88	``factorial`` from the ``example`` module:
89
90	>>> from example import factorial
91
92	Now use it:
93
94	>>> factorial(6)
95	120
96	</pre></div>
97
98	<P>
99	Running <code>doctest.testfile("example.txt")</code> then finds the error
100	in this documentation:
101
102	<P>
103	<div class="verbatim"><pre>
104	File "./example.txt", line 14, in example.txt
105	Failed example:
106	factorial(6)
107	Expected:
108	120
109	Got:
110	720
111	</pre></div>
112
113	<P>
114	As with <tt class="function">testmod()</tt>, <tt class="function">testfile()</tt> won't display anything
115	unless an example fails. If an example does fail, then the failing
116	example(s) and the cause(s) of the failure(s) are printed to stdout, using
117	the same format as <tt class="function">testmod()</tt>.
118
119	<P>
120	By default, <tt class="function">testfile()</tt> looks for files in the calling
121	module's directory. See section <A href="doctest-basic-api.html#doctest-basic-api">5.2.4</A> for a
122	description of the optional arguments that can be used to tell it to
123	look for files in other locations.
124
125	<P>
126	Like <tt class="function">testmod()</tt>, <tt class="function">testfile()</tt>'s verbosity can be
127	set with the <b class="programopt">-v</b> command-line switch or with the optional
128	keyword argument <var>verbose</var>.
129
130	<P>
131	For more information on <tt class="function">testfile()</tt>, see
132	section <A href="doctest-basic-api.html#doctest-basic-api">5.2.4</A>.
133
134	<P>
135
136	<DIV CLASS="navigation">
137	<div class='online-navigation'>
138	<p></p><hr />
139	<table align="center" width="100%" cellpadding="0" cellspacing="2">
140	<tr>
141	<td class='online-navigation'><a rel="prev" title="5.2.1 Simple Usage: Checking"
142	href="doctest-simple-testmod.html"><img src='../icons/previous.png'
143	border='0' height='32' alt='Previous Page' width='32' /></A></td>
144	<td class='online-navigation'><a rel="parent" title="5.2 doctest "
145	href="module-doctest.html"><img src='../icons/up.png'
146	border='0' height='32' alt='Up One Level' width='32' /></A></td>
147	<td class='online-navigation'><a rel="next" title="5.2.3 How It Works"
148	href="doctest-how-it-works.html"><img src='../icons/next.png'
149	border='0' height='32' alt='Next Page' width='32' /></A></td>
150	<td align="center" width="100%">Python Library Reference</td>
151	<td class='online-navigation'><a rel="contents" title="Table of Contents"
152	href="contents.html"><img src='../icons/contents.png'
153	border='0' height='32' alt='Contents' width='32' /></A></td>
154	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
155	border='0' height='32' alt='Module Index' width='32' /></a></td>
156	<td class='online-navigation'><a rel="index" title="Index"
157	href="genindex.html"><img src='../icons/index.png'
158	border='0' height='32' alt='Index' width='32' /></A></td>
159	</tr></table>
160	<div class='online-navigation'>
161	<b class="navlabel">Previous:</b>
162	<a class="sectref" rel="prev" href="doctest-simple-testmod.html">5.2.1 Simple Usage: Checking</A>
163	<b class="navlabel">Up:</b>
164	<a class="sectref" rel="parent" href="module-doctest.html">5.2 doctest </A>
165	<b class="navlabel">Next:</b>
166	<a class="sectref" rel="next" href="doctest-how-it-works.html">5.2.3 How It Works</A>
167	</div>
168	</div>
169	<hr />
170	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
171	</DIV>
172	<!--End of Navigation Panel-->
173	<ADDRESS>
174	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
175	</ADDRESS>
176	</BODY>
177	</HTML>