 |
 |
 |
Python Library Reference |  |
 |
 |
|
|
|
Python Library Reference | |
|
|
A number of option flags control various aspects of doctest's behavior. Symbolic names for the flags are supplied as module constants, which can be or'ed together and passed to various functions. The names can also be used in doctest directives (see below).
The first group of options define test semantics, controlling aspects of how doctest decides whether actual output matches an example's expected output:
1,
an actual output block containing just 1 or just
True is considered to be a match, and similarly for 0
versus False. When DONT_ACCEPT_TRUE_FOR_1 is
specified, neither substitution is allowed. The default behavior
caters to that Python changed the return type of many functions
from integer to boolean; doctests expecting "little integer"
output still work in these cases. This option will probably go
away, but not for several years.
<BLANKLINE>, then that line
will match a blank line in the actual output. Because a
genuinely blank line delimits the expected output, this is
the only way to communicate that a blank line is expected. When
DONT_ACCEPT_BLANKLINE is specified, this substitution
is not allowed.
...) in the expected output
can match any substring in the actual output. This includes
substrings that span line boundaries, and empty substrings, so it's
best to keep usage of this simple. Complicated uses can lead to the
same kinds of "oops, it matched too much!" surprises that .*
is prone to in regular expressions.
Note that a similar effect can be obtained using ELLIPSIS, and IGNORE_EXCEPTION_DETAIL may go away when Python releases prior to 2.4 become uninteresting. Until then, IGNORE_EXCEPTION_DETAIL is the only clear way to write a doctest that doesn't care about the exception detail yet continues to pass under Python releases prior to 2.4 (doctest directives appear to be comments to them). For example,
>>> (1, 2)[3] = 'moo' #doctest: +IGNORE_EXCEPTION_DETAIL Traceback (most recent call last): File "<stdin>", line 1, in ? TypeError: object doesn't support item assignment
passes under Python 2.4 and Python 2.3. The detail changed in 2.4, to say "does not" instead of "doesn't".
When specified, do not run the example at all. This can be useful in contexts where doctest examples serve as both documentation and test cases, and an example should be included for documentation purposes, but should not be checked. E.g., the example's output might be random; or the example might depend on resources which would be unavailable to the test driver.
The SKIP flag can also be used for temporarily "commenting out" examples.
The second group of options controls how test failures are reported:
difflib.Differ,
using the same algorithm as the popular ndiff.py utility.
This is the only method that marks differences within lines as
well as across lines. For example, if a line of expected output
contains digit 1 where actual output contains letter l,
a line is inserted with a caret marking the mismatching column
positions.
"Doctest directives" may be used to modify the option flags for individual examples. Doctest directives are expressed as a special Python comment following an example's source code:
| directive | ::= | "#" "doctest:" directive_options |
| directive_options | ::= | directive_option ("," directive_option)* |
| directive_option | ::= | on_or_off directive_option_name |
| on_or_off | ::= | "+" | "-" |
| directive_option_name | ::= | "DONT_ACCEPT_BLANKLINE" | "NORMALIZE_WHITESPACE" | ... |
Whitespace is not allowed between the + or - and the
directive option name. The directive option name can be any of the
option flag names explained above.
An example's doctest directives modify doctest's behavior for that
single example. Use + to enable the named behavior, or
- to disable it.
For example, this test passes:
>>> print range(20) #doctest: +NORMALIZE_WHITESPACE [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
Without the directive it would fail, both because the actual output doesn't have two blanks before the single-digit list elements, and because the actual output is on a single line. This test also passes, and also requires a directive to do so:
>>> print range(20) # doctest:+ELLIPSIS [0, 1, ..., 18, 19]
Multiple directives can be used on a single physical line, separated by commas:
>>> print range(20) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE [0, 1, ..., 18, 19]
If multiple directive comments are used for a single example, then they are combined:
>>> print range(20) # doctest: +ELLIPSIS ... # doctest: +NORMALIZE_WHITESPACE [0, 1, ..., 18, 19]
As the previous example shows, you can add "..." lines to your example containing only directives. This can be useful when an example is too long for a directive to comfortably fit on the same line:
>>> print range(5) + range(10,20) + range(30,40) + range(50,60) ... # doctest: +ELLIPSIS [0, ..., 4, 10, ..., 19, 30, ..., 39, 50, ..., 59]
Note that since all options are disabled by default, and directives apply
only to the example they appear in, enabling options (via + in a
directive) is usually the only meaningful choice. However, option flags
can also be passed to functions that run doctests, establishing different
defaults. In such cases, disabling an option via - in a directive
can be useful.
Changed in version 2.4:
Constants DONT_ACCEPT_BLANKLINE,
NORMALIZE_WHITESPACE, ELLIPSIS,
IGNORE_EXCEPTION_DETAIL,
REPORT_UDIFF, REPORT_CDIFF,
REPORT_NDIFF, REPORT_ONLY_FIRST_FAILURE,
COMPARISON_FLAGS and REPORTING_FLAGS
were added; by default <BLANKLINE> in expected output
matches an empty line in actual output; and doctest directives
were added.
Changed in version 2.5:
Constant SKIP was added.
There's also a way to register new option flag names, although this isn't useful unless you intend to extend doctest internals via subclassing:
| name) |
MY_FLAG = register_optionflag('MY_FLAG')
New in version 2.4.
|
|
|
Python Library Reference | |
|
|