<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"lib.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"lib.html" title='Python Library Reference'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"doctest-options.html" />
<link rel=
"prev" href=
"doctest-execution-context.html" />
<link rel=
"parent" href=
"doctest-how-it-works.html" />
<link rel=
"next" href=
"doctest-options.html" />
<meta name='aesop' content='information'
/>
<title>5.2.3.4 What About Exceptions?
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"5.2.3.3 What's the Execution"
href=
"doctest-execution-context.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"5.2.3 How It Works"
href=
"doctest-how-it-works.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"5.2.3.5 Option Flags and"
href=
"doctest-options.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td><td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td><td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"doctest-execution-context.html">5.2.3.3 What's the Execution
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"doctest-how-it-works.html">5.2.3 How It Works
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"doctest-options.html">5.2.3.5 Option Flags and
</A>
<!--End of Navigation Panel-->
<H3><A NAME=
"SECTION007234000000000000000"></A><A NAME=
"doctest-exceptions"></A>
5.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. Since 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.
<div class=
"verbatim"><pre>
>>> [
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
<tt class=
"exception">ValueError
</tt> is raised, with the
"<tt class="samp
">list.remove(x): x not in list</tt>" 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:
<div class=
"verbatim"><pre>
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:
<div class=
"verbatim"><pre>
>>> raise ValueError('multi\n line\ndetail')
Traceback (most recent call last):
File
"<stdin>", line
1, in ?
The last three lines (starting with
<tt class=
"exception">ValueError
</tt>) are
compared against the exception's type and detail, and the rest are
Best practice is to omit the traceback stack, unless it adds
significant documentation value to the example. So the last example
<div class=
"verbatim"><pre>
>>> raise ValueError('multi\n line\ndetail')
Traceback (most recent call last):
Note that tracebacks are treated very specially. In particular, in the
rewritten example, the use of
"<tt class="samp
">...</tt>" is independent of doctest's
<tt class=
"constant">ELLIPSIS
</tt> 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:
<LI>Doctest can't guess whether your expected output came from an
exception traceback or from ordinary printing. So, e.g., an example
that expects
"<tt class="samp
">ValueError: 42 is prime</tt>" will pass whether
<tt class=
"exception">ValueError
</tt> 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.
<LI>Each line of the traceback stack (if present) must be indented
further than the first line of the example,
<em>or
</em> 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.
<LI>When the
<tt class=
"constant">IGNORE_EXCEPTION_DETAIL
</tt> doctest option is
is specified, everything following the leftmost colon is ignored.
<LI>The interactive shell omits the traceback header line for some
<tt class=
"exception">SyntaxError
</tt>s. But doctest uses the traceback header
line to distinguish exceptions from non-exceptions. So in the rare
case where you need to test a
<tt class=
"exception">SyntaxError
</tt> that omits the
traceback header, you will need to manually add the traceback header
line to your test example.
<LI>For some
<tt class=
"exception">SyntaxError
</tt>s, Python displays the character
position of the syntax error, using a
<code>^
</code> marker:
<div class=
"verbatim"><pre>
File
"<stdin>", line
1SyntaxError: 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
<code>^
</code> marker in the wrong location:
<div class=
"verbatim"><pre>
Traceback (most recent call last):
File
"<stdin>", line
1SyntaxError: invalid syntax
<span class=
"versionnote">Changed in version
2.4:
The ability to handle a multi-line exception detail,
and the
<tt class=
"constant">IGNORE_EXCEPTION_DETAIL
</tt> doctest option,
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"5.2.3.3 What's the Execution"
href=
"doctest-execution-context.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"5.2.3 How It Works"
href=
"doctest-how-it-works.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"5.2.3.5 Option Flags and"
href=
"doctest-options.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td><td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td><td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"doctest-execution-context.html">5.2.3.3 What's the Execution
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"doctest-how-it-works.html">5.2.3 How It Works
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"doctest-options.html">5.2.3.5 Option Flags and
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.
projects / OpenSPARC-T2-SAM / blob