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-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> | |
57 | 5.2.3.5 Option Flags and Directives | |
58 | </H3> | |
59 | ||
60 | <P> | |
61 | A number of option flags control various aspects of doctest's | |
62 | behavior. Symbolic names for the flags are supplied as module constants, | |
63 | which can be or'ed together and passed to various functions. The names | |
64 | can also be used in doctest directives (see below). | |
65 | ||
66 | <P> | |
67 | The first group of options define test semantics, controlling | |
68 | aspects of how doctest decides whether actual output matches an | |
69 | example'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><BLANKLINE></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> | |
131 | Note 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 | >>> (1, 2)[3] = 'moo' #doctest: +IGNORE_EXCEPTION_DETAIL | |
142 | Traceback (most recent call last): | |
143 | File "<stdin>", line 1, in ? | |
144 | TypeError: object doesn't support item assignment | |
145 | </pre></div> | |
146 | ||
147 | <P> | |
148 | passes 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> | |
161 | The 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 | |
210 | individual examples. Doctest directives are expressed as a special | |
211 | Python 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> | |
246 | Whitespace is not allowed between the <code>+</code> or <code>-</code> and the | |
247 | directive option name. The directive option name can be any of the | |
248 | option flag names explained above. | |
249 | ||
250 | <P> | |
251 | An example's doctest directives modify doctest's behavior for that | |
252 | single example. Use <code>+</code> to enable the named behavior, or | |
253 | <code>-</code> to disable it. | |
254 | ||
255 | <P> | |
256 | For example, this test passes: | |
257 | ||
258 | <P> | |
259 | <div class="verbatim"><pre> | |
260 | >>> print range(20) #doctest: +NORMALIZE_WHITESPACE | |
261 | [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, | |
262 | 10, 11, 12, 13, 14, 15, 16, 17, 18, 19] | |
263 | </pre></div> | |
264 | ||
265 | <P> | |
266 | Without the directive it would fail, both because the actual output | |
267 | doesn't have two blanks before the single-digit list elements, and | |
268 | because the actual output is on a single line. This test also passes, | |
269 | and also requires a directive to do so: | |
270 | ||
271 | <P> | |
272 | <div class="verbatim"><pre> | |
273 | >>> print range(20) # doctest:+ELLIPSIS | |
274 | [0, 1, ..., 18, 19] | |
275 | </pre></div> | |
276 | ||
277 | <P> | |
278 | Multiple directives can be used on a single physical line, separated | |
279 | by commas: | |
280 | ||
281 | <P> | |
282 | <div class="verbatim"><pre> | |
283 | >>> print range(20) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE | |
284 | [0, 1, ..., 18, 19] | |
285 | </pre></div> | |
286 | ||
287 | <P> | |
288 | If multiple directive comments are used for a single example, then | |
289 | they are combined: | |
290 | ||
291 | <P> | |
292 | <div class="verbatim"><pre> | |
293 | >>> print range(20) # doctest: +ELLIPSIS | |
294 | ... # doctest: +NORMALIZE_WHITESPACE | |
295 | [0, 1, ..., 18, 19] | |
296 | </pre></div> | |
297 | ||
298 | <P> | |
299 | As the previous example shows, you can add "<tt class="samp">...</tt>" lines to your | |
300 | example containing only directives. This can be useful when an | |
301 | example is too long for a directive to comfortably fit on the same | |
302 | line: | |
303 | ||
304 | <P> | |
305 | <div class="verbatim"><pre> | |
306 | >>> 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> | |
312 | Note that since all options are disabled by default, and directives apply | |
313 | only to the example they appear in, enabling options (via <code>+</code> in a | |
314 | directive) is usually the only meaningful choice. However, option flags | |
315 | can also be passed to functions that run doctests, establishing different | |
316 | defaults. In such cases, disabling an option via <code>-</code> in a directive | |
317 | can be useful. | |
318 | ||
319 | <P> | |
320 | ||
321 | <span class="versionnote">Changed in version 2.4: | |
322 | Constants <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><BLANKLINE></code> in expected output | |
329 | matches an empty line in actual output; and doctest directives | |
330 | were added.</span> | |
331 | ||
332 | <P> | |
333 | There's also a way to register new option flag names, although this | |
334 | isn't useful unless you intend to extend <tt class="module"><a href="module-doctest.html">doctest</a></tt> internals | |
335 | via 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> | |
400 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
401 | </ADDRESS> | |
402 | </BODY> | |
403 | </HTML> |