23.2.3.4 What About Exceptions?
No problem, provided that the traceback is the only output produced by
the example: just paste in the traceback.23.1Since tracebacks contain details that are likely to change rapidly (for
example, exact file paths and line numbers), this is one case where doctest
works hard to be flexible in what it accepts.
Simple example:
>>> [1, 2, 3].remove(42)
Traceback (most recent call last):
File "<stdin>", line 1, in ?
ValueError: list.remove(x): x not in list
That doctest succeeds if ValueError is raised, with the
"list.remove(x): x not in list" detail as shown.
The expected output for an exception must start with a traceback
header, which may be either of the following two lines, indented the
same as the first line of the example:
Traceback (most recent call last):
Traceback (innermost last):
The traceback header is followed by an optional traceback stack, whose
contents are ignored by doctest. The traceback stack is typically
omitted, or copied verbatim from an interactive session.
The traceback stack is followed by the most interesting part: the
line(s) containing the exception type and detail. This is usually the
last line of a traceback, but can extend across multiple lines if the
exception has a multi-line detail:
>>> raise ValueError('multi\n line\ndetail')
Traceback (most recent call last):
File "<stdin>", line 1, in ?
ValueError: multi
line
detail
The last three lines (starting with ValueError) are
compared against the exception's type and detail, and the rest are
ignored.
Best practice is to omit the traceback stack, unless it adds
significant documentation value to the example. So the last example
is probably better as:
>>> raise ValueError('multi\n line\ndetail')
Traceback (most recent call last):
...
ValueError: multi
line
detail
Note that tracebacks are treated very specially. In particular, in the
rewritten example, the use of "..." is independent of doctest's
ELLIPSIS option. The ellipsis in that example could be left
out, or could just as well be three (or three hundred) commas or digits,
or an indented transcript of a Monty Python skit.
Some details you should read once, but won't need to remember:
- Doctest can't guess whether your expected output came from an
exception traceback or from ordinary printing. So, e.g., an example
that expects "ValueError: 42 is prime" will pass whether
ValueError is actually raised or if the example merely
prints that traceback text. In practice, ordinary output rarely begins
with a traceback header line, so this doesn't create real problems.
- Each line of the traceback stack (if present) must be indented
further than the first line of the example, or start with a
non-alphanumeric character. The first line following the traceback
header indented the same and starting with an alphanumeric is taken
to be the start of the exception detail. Of course this does the
right thing for genuine tracebacks.
- When the IGNORE_EXCEPTION_DETAIL doctest option is
is specified, everything following the leftmost colon is ignored.
- The interactive shell omits the traceback header line for some
SyntaxErrors. But doctest uses the traceback header
line to distinguish exceptions from non-exceptions. So in the rare
case where you need to test a SyntaxError that omits the
traceback header, you will need to manually add the traceback header
line to your test example.
- For some SyntaxErrors, Python displays the character
position of the syntax error, using a
^ marker:
>>> 1 1
File "<stdin>", line 1
1 1
^
SyntaxError: invalid syntax
Since the lines showing the position of the error come before the
exception type and detail, they are not checked by doctest. For
example, the following test would pass, even though it puts the
^ marker in the wrong location:
>>> 1 1
Traceback (most recent call last):
File "<stdin>", line 1
1 1
^
SyntaxError: invalid syntax
Changed in version 2.4:
The ability to handle a multi-line exception detail,
and the IGNORE_EXCEPTION_DETAIL doctest option,
were added.
Footnotes
- ... traceback.23.1
- Examples containing
both expected output and an exception are not supported. Trying
to guess where one ends and the other begins is too error-prone,
and that also makes for a confusing test.
Release 2.5.2, documentation updated on 21st February, 2008.
See About this document... for information on suggesting changes.
|