projects / OpenSPARC-T2-DV / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 design and verification files.
[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / lib / module-doctest.html
CommitLineData
86530b38
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="module-unittest.html" />
13<link rel="prev" href="module-pydoc.html" />
14<link rel="parent" href="misc.html" />
15<link rel="next" href="doctest-simple-testmod.html" />
16<meta name='aesop' content='information' />
17<title>5.2 doctest -- Test interactive Python examples</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.1 pydoc "
25 href="module-pydoc.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. Miscellaneous Services"
28 href="misc.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.1 Simple Usage: Checking"
31 href="doctest-simple-testmod.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="module-pydoc.html">5.1 pydoc </A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="misc.html">5. Miscellaneous Services</A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="doctest-simple-testmod.html">5.2.1 Simple Usage: Checking</A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H1><A NAME="SECTION007200000000000000000">
565.2 <tt class="module">doctest</tt> --
57 Test interactive Python examples</A>
58</H1>
59
60<P>
61<A NAME="module-doctest"></A>
62
63<P>
64
65<P>
66The <tt class="module"><a href="module-doctest.html">doctest</a></tt> module searches for pieces of text that look like
67interactive Python sessions, and then executes those sessions to
68verify that they work exactly as shown. There are several common ways to
69use doctest:
70
71<P>
72
73<UL>
74<LI>To check that a module's docstrings are up-to-date by verifying
75 that all interactive examples still work as documented.
76</LI>
77<LI>To perform regression testing by verifying that interactive
78 examples from a test file or a test object work as expected.
79</LI>
80<LI>To write tutorial documentation for a package, liberally
81 illustrated with input-output examples. Depending on whether
82 the examples or the expository text are emphasized, this has
83 the flavor of "literate testing" or "executable documentation".
84</LI>
85</UL>
86
87<P>
88Here's a complete but small example module:
89
90<P>
91<div class="verbatim"><pre>
92"""
93This is the "example" module.
94
95The example module supplies one function, factorial(). For example,
96
97&gt;&gt;&gt; factorial(5)
98120
99"""
100
101def factorial(n):
102 """Return the factorial of n, an exact integer &gt;= 0.
103
104 If the result is small enough to fit in an int, return an int.
105 Else return a long.
106
107 &gt;&gt;&gt; [factorial(n) for n in range(6)]
108 [1, 1, 2, 6, 24, 120]
109 &gt;&gt;&gt; [factorial(long(n)) for n in range(6)]
110 [1, 1, 2, 6, 24, 120]
111 &gt;&gt;&gt; factorial(30)
112 265252859812191058636308480000000L
113 &gt;&gt;&gt; factorial(30L)
114 265252859812191058636308480000000L
115 &gt;&gt;&gt; factorial(-1)
116 Traceback (most recent call last):
117 ...
118 ValueError: n must be &gt;= 0
119
120 Factorials of floats are OK, but the float must be an exact integer:
121 &gt;&gt;&gt; factorial(30.1)
122 Traceback (most recent call last):
123 ...
124 ValueError: n must be exact integer
125 &gt;&gt;&gt; factorial(30.0)
126 265252859812191058636308480000000L
127
128 It must also not be ridiculously large:
129 &gt;&gt;&gt; factorial(1e100)
130 Traceback (most recent call last):
131 ...
132 OverflowError: n too large
133 """
134</pre></div>
135<div class="verbatim"><pre>
136 import math
137 if not n &gt;= 0:
138 raise ValueError("n must be &gt;= 0")
139 if math.floor(n) != n:
140 raise ValueError("n must be exact integer")
141 if n+1 == n: # catch a value like 1e300
142 raise OverflowError("n too large")
143 result = 1
144 factor = 2
145 while factor &lt;= n:
146 result *= factor
147 factor += 1
148 return result
149
150def _test():
151 import doctest
152 doctest.testmod()
153
154if __name__ == "__main__":
155 _test()
156</pre></div>
157
158<P>
159If you run <span class="file">example.py</span> directly from the command line,
160<tt class="module"><a href="module-doctest.html">doctest</a></tt> works its magic:
161
162<P>
163<div class="verbatim"><pre>
164$ python example.py
165$
166</pre></div>
167
168<P>
169There's no output! That's normal, and it means all the examples
170worked. Pass <b class="programopt">-v</b> to the script, and <tt class="module"><a href="module-doctest.html">doctest</a></tt>
171prints a detailed log of what it's trying, and prints a summary at the
172end:
173
174<P>
175<div class="verbatim"><pre>
176$ python example.py -v
177Trying:
178 factorial(5)
179Expecting:
180 120
181ok
182Trying:
183 [factorial(n) for n in range(6)]
184Expecting:
185 [1, 1, 2, 6, 24, 120]
186ok
187Trying:
188 [factorial(long(n)) for n in range(6)]
189Expecting:
190 [1, 1, 2, 6, 24, 120]
191ok
192</pre></div>
193
194<P>
195And so on, eventually ending with:
196
197<P>
198<div class="verbatim"><pre>
199Trying:
200 factorial(1e100)
201Expecting:
202 Traceback (most recent call last):
203 ...
204 OverflowError: n too large
205ok
2061 items had no tests:
207 __main__._test
2082 items passed all tests:
209 1 tests in __main__
210 8 tests in __main__.factorial
2119 tests in 3 items.
2129 passed and 0 failed.
213Test passed.
214$
215</pre></div>
216
217<P>
218That's all you need to know to start making productive use of
219<tt class="module"><a href="module-doctest.html">doctest</a></tt>! Jump in. The following sections provide full
220details. Note that there are many examples of doctests in
221the standard Python test suite and libraries. Especially useful examples
222can be found in the standard test file <span class="file">Lib/test/test_doctest.py</span>.
223
224<P>
225
226<p><br /></p><hr class='online-navigation' />
227<div class='online-navigation'>
228<!--Table of Child-Links-->
229<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
230
231<UL CLASS="ChildLinks">
232<LI><A href="doctest-simple-testmod.html">5.2.1 Simple Usage: Checking Examples in
233 Docstrings</a>
234<LI><A href="doctest-simple-testfile.html">5.2.2 Simple Usage: Checking Examples in a Text
235 File</a>
236<LI><A href="doctest-how-it-works.html">5.2.3 How It Works</a>
237<UL>
238<LI><A href="doctest-which-docstrings.html">5.2.3.1 Which Docstrings Are Examined?</a>
239<LI><A href="doctest-finding-examples.html">5.2.3.2 How are Docstring Examples
240 Recognized?</a>
241<LI><A href="doctest-execution-context.html">5.2.3.3 What's the Execution Context?</a>
242<LI><A href="doctest-exceptions.html">5.2.3.4 What About Exceptions?</a>
243<LI><A href="doctest-options.html">5.2.3.5 Option Flags and Directives</a>
244<LI><A href="doctest-warnings.html">5.2.3.6 Warnings</a>
245</ul>
246<LI><A href="doctest-basic-api.html">5.2.4 Basic API</a>
247<LI><A href="doctest-unittest-api.html">5.2.5 Unittest API</a>
248<LI><A href="doctest-advanced-api.html">5.2.6 Advanced API</a>
249<UL>
250<LI><A href="doctest-DocTest.html">5.2.6.1 DocTest Objects</a>
251<LI><A href="doctest-Example.html">5.2.6.2 Example Objects</a>
252<LI><A href="doctest-DocTestFinder.html">5.2.6.3 DocTestFinder objects</a>
253<LI><A href="doctest-DocTestParser.html">5.2.6.4 DocTestParser objects</a>
254<LI><A href="doctest-DocTestRunner.html">5.2.6.5 DocTestRunner objects</a>
255<LI><A href="doctest-OutputChecker.html">5.2.6.6 OutputChecker objects</a>
256</ul>
257<LI><A href="doctest-debugging.html">5.2.7 Debugging</a>
258<LI><A href="doctest-soapbox.html">5.2.8 Soapbox</a>
259</ul>
260<!--End of Table of Child-Links-->
261</div>
262
263<DIV CLASS="navigation">
264<div class='online-navigation'>
265<p></p><hr />
266<table align="center" width="100%" cellpadding="0" cellspacing="2">
267<tr>
268<td class='online-navigation'><a rel="prev" title="5.1 pydoc "
269 href="module-pydoc.html"><img src='../icons/previous.png'
270 border='0' height='32' alt='Previous Page' width='32' /></A></td>
271<td class='online-navigation'><a rel="parent" title="5. Miscellaneous Services"
272 href="misc.html"><img src='../icons/up.png'
273 border='0' height='32' alt='Up One Level' width='32' /></A></td>
274<td class='online-navigation'><a rel="next" title="5.2.1 Simple Usage: Checking"
275 href="doctest-simple-testmod.html"><img src='../icons/next.png'
276 border='0' height='32' alt='Next Page' width='32' /></A></td>
277<td align="center" width="100%">Python Library Reference</td>
278<td class='online-navigation'><a rel="contents" title="Table of Contents"
279 href="contents.html"><img src='../icons/contents.png'
280 border='0' height='32' alt='Contents' width='32' /></A></td>
281<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
282 border='0' height='32' alt='Module Index' width='32' /></a></td>
283<td class='online-navigation'><a rel="index" title="Index"
284 href="genindex.html"><img src='../icons/index.png'
285 border='0' height='32' alt='Index' width='32' /></A></td>
286</tr></table>
287<div class='online-navigation'>
288<b class="navlabel">Previous:</b>
289<a class="sectref" rel="prev" href="module-pydoc.html">5.1 pydoc </A>
290<b class="navlabel">Up:</b>
291<a class="sectref" rel="parent" href="misc.html">5. Miscellaneous Services</A>
292<b class="navlabel">Next:</b>
293<a class="sectref" rel="next" href="doctest-simple-testmod.html">5.2.1 Simple Usage: Checking</A>
294</div>
295</div>
296<hr />
297<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
298</DIV>
299<!--End of Navigation Panel-->
300<ADDRESS>
301See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
302</ADDRESS>
303</BODY>
304</HTML>
Full OpenSPARC design & verification tarball including full HDL.