projects / OpenSPARC-T2-SAM / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 architecture model.
[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / lib / doctest-options.html
CommitLineData
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-warnings.html" />
13<link rel="prev" href="doctest-exceptions.html" />
14<link rel="parent" href="doctest-how-it-works.html" />
15<link rel="next" href="doctest-warnings.html" />
16<meta name='aesop' content='information' />
17<title>5.2.3.5 Option Flags and Directives</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.4 What About Exceptions?"
25 href="doctest-exceptions.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.3 How It Works"
28 href="doctest-how-it-works.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.6 Warnings"
31 href="doctest-warnings.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-exceptions.html">5.2.3.4 What About Exceptions?</A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="doctest-how-it-works.html">5.2.3 How It Works</A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="doctest-warnings.html">5.2.3.6 Warnings</A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H3><A NAME="SECTION007235000000000000000"></A><A NAME="doctest-options"></A>
56<BR>
575.2.3.5 Option Flags and Directives
58</H3>
59
60<P>
61A number of option flags control various aspects of doctest's
62behavior. Symbolic names for the flags are supplied as module constants,
63which can be or'ed together and passed to various functions. The names
64can also be used in doctest directives (see below).
65
66<P>
67The first group of options define test semantics, controlling
68aspects of how doctest decides whether actual output matches an
69example's expected output:
70
71<P>
72<dl><dt><b><tt id='l2h-1062' xml:id='l2h-1062'>DONT_ACCEPT_TRUE_FOR_1</tt></b></dt>
73<dd>
74 By default, if an expected output block contains just <code>1</code>,
75 an actual output block containing just <code>1</code> or just
76 <code>True</code> is considered to be a match, and similarly for <code>0</code>
77 versus <code>False</code>. When <tt class="constant">DONT_ACCEPT_TRUE_FOR_1</tt> is
78 specified, neither substitution is allowed. The default behavior
79 caters to that Python changed the return type of many functions
80 from integer to boolean; doctests expecting "little integer"
81 output still work in these cases. This option will probably go
82 away, but not for several years.
83</dd></dl>
84
85<P>
86<dl><dt><b><tt id='l2h-1063' xml:id='l2h-1063'>DONT_ACCEPT_BLANKLINE</tt></b></dt>
87<dd>
88 By default, if an expected output block contains a line
89 containing only the string <code>&lt;BLANKLINE&gt;</code>, then that line
90 will match a blank line in the actual output. Because a
91 genuinely blank line delimits the expected output, this is
92 the only way to communicate that a blank line is expected. When
93 <tt class="constant">DONT_ACCEPT_BLANKLINE</tt> is specified, this substitution
94 is not allowed.
95</dd></dl>
96
97<P>
98<dl><dt><b><tt id='l2h-1064' xml:id='l2h-1064'>NORMALIZE_WHITESPACE</tt></b></dt>
99<dd>
100 When specified, all sequences of whitespace (blanks and newlines) are
101 treated as equal. Any sequence of whitespace within the expected
102 output will match any sequence of whitespace within the actual output.
103 By default, whitespace must match exactly.
104 <tt class="constant">NORMALIZE_WHITESPACE</tt> is especially useful when a line
105 of expected output is very long, and you want to wrap it across
106 multiple lines in your source.
107</dd></dl>
108
109<P>
110<dl><dt><b><tt id='l2h-1065' xml:id='l2h-1065'>ELLIPSIS</tt></b></dt>
111<dd>
112 When specified, an ellipsis marker (<code>...</code>) in the expected output
113 can match any substring in the actual output. This includes
114 substrings that span line boundaries, and empty substrings, so it's
115 best to keep usage of this simple. Complicated uses can lead to the
116 same kinds of "oops, it matched too much!" surprises that <tt class="regexp">.*</tt>
117 is prone to in regular expressions.
118</dd></dl>
119
120<P>
121<dl><dt><b><tt id='l2h-1066' xml:id='l2h-1066'>IGNORE_EXCEPTION_DETAIL</tt></b></dt>
122<dd>
123 When specified, an example that expects an exception passes if
124 an exception of the expected type is raised, even if the exception
125 detail does not match. For example, an example expecting
126 "<tt class="samp">ValueError: 42</tt>" will pass if the actual exception raised is
127 "<tt class="samp">ValueError: 3*14</tt>", but will fail, e.g., if
128 <tt class="exception">TypeError</tt> is raised.
129
130<P>
131Note that a similar effect can be obtained using <tt class="constant">ELLIPSIS</tt>,
132 and <tt class="constant">IGNORE_EXCEPTION_DETAIL</tt> may go away when Python releases
133 prior to 2.4 become uninteresting. Until then,
134 <tt class="constant">IGNORE_EXCEPTION_DETAIL</tt> is the only clear way to write a
135 doctest that doesn't care about the exception detail yet continues
136 to pass under Python releases prior to 2.4 (doctest directives
137 appear to be comments to them). For example,
138
139<P>
140<div class="verbatim"><pre>
141&gt;&gt;&gt; (1, 2)[3] = 'moo' #doctest: +IGNORE_EXCEPTION_DETAIL
142Traceback (most recent call last):
143 File "&lt;stdin&gt;", line 1, in ?
144TypeError: object doesn't support item assignment
145</pre></div>
146
147<P>
148passes under Python 2.4 and Python 2.3. The detail changed in 2.4,
149 to say "does not" instead of "doesn't".
150
151<P>
152</dd></dl>
153
154<P>
155<dl><dt><b><tt id='l2h-1067' xml:id='l2h-1067'>COMPARISON_FLAGS</tt></b></dt>
156<dd>
157 A bitmask or'ing together all the comparison flags above.
158</dd></dl>
159
160<P>
161The second group of options controls how test failures are reported:
162
163<P>
164<dl><dt><b><tt id='l2h-1068' xml:id='l2h-1068'>REPORT_UDIFF</tt></b></dt>
165<dd>
166 When specified, failures that involve multi-line expected and
167 actual outputs are displayed using a unified diff.
168</dd></dl>
169
170<P>
171<dl><dt><b><tt id='l2h-1069' xml:id='l2h-1069'>REPORT_CDIFF</tt></b></dt>
172<dd>
173 When specified, failures that involve multi-line expected and
174 actual outputs will be displayed using a context diff.
175</dd></dl>
176
177<P>
178<dl><dt><b><tt id='l2h-1070' xml:id='l2h-1070'>REPORT_NDIFF</tt></b></dt>
179<dd>
180 When specified, differences are computed by <code>difflib.Differ</code>,
181 using the same algorithm as the popular <span class="file">ndiff.py</span> utility.
182 This is the only method that marks differences within lines as
183 well as across lines. For example, if a line of expected output
184 contains digit <code>1</code> where actual output contains letter <code>l</code>,
185 a line is inserted with a caret marking the mismatching column
186 positions.
187</dd></dl>
188
189<P>
190<dl><dt><b><tt id='l2h-1071' xml:id='l2h-1071'>REPORT_ONLY_FIRST_FAILURE</tt></b></dt>
191<dd>
192 When specified, display the first failing example in each doctest,
193 but suppress output for all remaining examples. This will prevent
194 doctest from reporting correct examples that break because of
195 earlier failures; but it might also hide incorrect examples that
196 fail independently of the first failure. When
197 <tt class="constant">REPORT_ONLY_FIRST_FAILURE</tt> is specified, the remaining
198 examples are still run, and still count towards the total number of
199 failures reported; only the output is suppressed.
200</dd></dl>
201
202<P>
203<dl><dt><b><tt id='l2h-1072' xml:id='l2h-1072'>REPORTING_FLAGS</tt></b></dt>
204<dd>
205 A bitmask or'ing together all the reporting flags above.
206</dd></dl>
207
208<P>
209"Doctest directives" may be used to modify the option flags for
210individual examples. Doctest directives are expressed as a special
211Python comment following an example's source code:
212
213<P>
214<dl><dd class="grammar">
215<div class="productions">
216<table>
217
218 <tr>
219 <td><a id='tok-directive' xml:id='tok-directive'>directive</a></td>
220 <td>::=</td>
221 <td>"#" "doctest:" <a class='grammartoken' href="doctest-options.html#tok-doctest-directive_options">directive_options</a></td></tr>
222 <tr>
223 <td><a id='tok-directive_options' xml:id='tok-directive_options'>directive_options</a></td>
224 <td>::=</td>
225 <td><a class='grammartoken' href="doctest-options.html#tok-doctest-directive_option">directive_option</a> ("," <a class='grammartoken' href="doctest-options.html#tok-doctest-directive_option">directive_option</a>)*</td></tr>
226 <tr>
227 <td><a id='tok-directive_option' xml:id='tok-directive_option'>directive_option</a></td>
228 <td>::=</td>
229 <td><a class='grammartoken' href="doctest-options.html#tok-doctest-on_or_off">on_or_off</a> <a class='grammartoken' href="doctest-options.html#tok-doctest-directive_option_name">directive_option_name</a></td></tr>
230 <tr>
231 <td><a id='tok-on_or_off' xml:id='tok-on_or_off'>on_or_off</a></td>
232 <td>::=</td>
233 <td>"+" | "-"</td></tr>
234 <tr>
235 <td><a id='tok-directive_option_name' xml:id='tok-directive_option_name'>directive_option_name</a></td>
236 <td>::=</td>
237 <td>"DONT_ACCEPT_BLANKLINE" | "NORMALIZE_WHITESPACE" | ...</td></tr>
238</table>
239</div>
240<a class="grammar-footer"
241 href="grammar-doctest.txt" type="text/plain"
242 >Download entire grammar as text.</a>
243</dd></dl>
244
245<P>
246Whitespace is not allowed between the <code>+</code> or <code>-</code> and the
247directive option name. The directive option name can be any of the
248option flag names explained above.
249
250<P>
251An example's doctest directives modify doctest's behavior for that
252single example. Use <code>+</code> to enable the named behavior, or
253<code>-</code> to disable it.
254
255<P>
256For example, this test passes:
257
258<P>
259<div class="verbatim"><pre>
260&gt;&gt;&gt; print range(20) #doctest: +NORMALIZE_WHITESPACE
261[0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
26210, 11, 12, 13, 14, 15, 16, 17, 18, 19]
263</pre></div>
264
265<P>
266Without the directive it would fail, both because the actual output
267doesn't have two blanks before the single-digit list elements, and
268because the actual output is on a single line. This test also passes,
269and also requires a directive to do so:
270
271<P>
272<div class="verbatim"><pre>
273&gt;&gt;&gt; print range(20) # doctest:+ELLIPSIS
274[0, 1, ..., 18, 19]
275</pre></div>
276
277<P>
278Multiple directives can be used on a single physical line, separated
279by commas:
280
281<P>
282<div class="verbatim"><pre>
283&gt;&gt;&gt; print range(20) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
284[0, 1, ..., 18, 19]
285</pre></div>
286
287<P>
288If multiple directive comments are used for a single example, then
289they are combined:
290
291<P>
292<div class="verbatim"><pre>
293&gt;&gt;&gt; print range(20) # doctest: +ELLIPSIS
294... # doctest: +NORMALIZE_WHITESPACE
295[0, 1, ..., 18, 19]
296</pre></div>
297
298<P>
299As the previous example shows, you can add "<tt class="samp">...</tt>" lines to your
300example containing only directives. This can be useful when an
301example is too long for a directive to comfortably fit on the same
302line:
303
304<P>
305<div class="verbatim"><pre>
306&gt;&gt;&gt; print range(5) + range(10,20) + range(30,40) + range(50,60)
307... # doctest: +ELLIPSIS
308[0, ..., 4, 10, ..., 19, 30, ..., 39, 50, ..., 59]
309</pre></div>
310
311<P>
312Note that since all options are disabled by default, and directives apply
313only to the example they appear in, enabling options (via <code>+</code> in a
314directive) is usually the only meaningful choice. However, option flags
315can also be passed to functions that run doctests, establishing different
316defaults. In such cases, disabling an option via <code>-</code> in a directive
317can be useful.
318
319<P>
320
321<span class="versionnote">Changed in version 2.4:
322Constants <tt class="constant">DONT_ACCEPT_BLANKLINE</tt>,
323 <tt class="constant">NORMALIZE_WHITESPACE</tt>, <tt class="constant">ELLIPSIS</tt>,
324 <tt class="constant">IGNORE_EXCEPTION_DETAIL</tt>,
325 <tt class="constant">REPORT_UDIFF</tt>, <tt class="constant">REPORT_CDIFF</tt>,
326 <tt class="constant">REPORT_NDIFF</tt>, <tt class="constant">REPORT_ONLY_FIRST_FAILURE</tt>,
327 <tt class="constant">COMPARISON_FLAGS</tt> and <tt class="constant">REPORTING_FLAGS</tt>
328 were added; by default <code>&lt;BLANKLINE&gt;</code> in expected output
329 matches an empty line in actual output; and doctest directives
330 were added.</span>
331
332<P>
333There's also a way to register new option flag names, although this
334isn't useful unless you intend to extend <tt class="module"><a href="module-doctest.html">doctest</a></tt> internals
335via subclassing:
336
337<P>
338<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
339 <td><nobr><b><tt id='l2h-1073' xml:id='l2h-1073' class="function">register_optionflag</tt></b>(</nobr></td>
340 <td><var>name</var>)</td></tr></table></dt>
341<dd>
342 Create a new option flag with a given name, and return the new
343 flag's integer value. <tt class="function">register_optionflag()</tt> can be
344 used when subclassing <tt class="class">OutputChecker</tt> or
345 <tt class="class">DocTestRunner</tt> to create new options that are supported by
346 your subclasses. <tt class="function">register_optionflag</tt> should always be
347 called using the following idiom:
348
349<P>
350<div class="verbatim"><pre>
351 MY_FLAG = register_optionflag('MY_FLAG')
352</pre></div>
353
354<P>
355
356<span class="versionnote">New in version 2.4.</span>
357
358</dl>
359
360<P>
361
362<DIV CLASS="navigation">
363<div class='online-navigation'>
364<p></p><hr />
365<table align="center" width="100%" cellpadding="0" cellspacing="2">
366<tr>
367<td class='online-navigation'><a rel="prev" title="5.2.3.4 What About Exceptions?"
368 href="doctest-exceptions.html"><img src='../icons/previous.png'
369 border='0' height='32' alt='Previous Page' width='32' /></A></td>
370<td class='online-navigation'><a rel="parent" title="5.2.3 How It Works"
371 href="doctest-how-it-works.html"><img src='../icons/up.png'
372 border='0' height='32' alt='Up One Level' width='32' /></A></td>
373<td class='online-navigation'><a rel="next" title="5.2.3.6 Warnings"
374 href="doctest-warnings.html"><img src='../icons/next.png'
375 border='0' height='32' alt='Next Page' width='32' /></A></td>
376<td align="center" width="100%">Python Library Reference</td>
377<td class='online-navigation'><a rel="contents" title="Table of Contents"
378 href="contents.html"><img src='../icons/contents.png'
379 border='0' height='32' alt='Contents' width='32' /></A></td>
380<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
381 border='0' height='32' alt='Module Index' width='32' /></a></td>
382<td class='online-navigation'><a rel="index" title="Index"
383 href="genindex.html"><img src='../icons/index.png'
384 border='0' height='32' alt='Index' width='32' /></A></td>
385</tr></table>
386<div class='online-navigation'>
387<b class="navlabel">Previous:</b>
388<a class="sectref" rel="prev" href="doctest-exceptions.html">5.2.3.4 What About Exceptions?</A>
389<b class="navlabel">Up:</b>
390<a class="sectref" rel="parent" href="doctest-how-it-works.html">5.2.3 How It Works</A>
391<b class="navlabel">Next:</b>
392<a class="sectref" rel="next" href="doctest-warnings.html">5.2.3.6 Warnings</A>
393</div>
394</div>
395<hr />
396<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
397</DIV>
398<!--End of Navigation Panel-->
399<ADDRESS>
400See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
401</ADDRESS>
402</BODY>
403</HTML>
Full OpenSPARC architecture tarball including simulator, hypervisor, and OBP.