[Python-checkins] python/dist/src/Doc/lib libdoctest.tex,1.36,1.37
tim_one at users.sourceforge.net
tim_one at users.sourceforge.net
Thu Aug 26 06:47:33 CEST 2004
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv13629/Doc/lib
Modified Files:
libdoctest.tex
Log Message:
Reorg of exception section. Now that there are fewer details needing
explanation, it's easier to push the remaining insufferably anal details
into a "fine print" section at the bottom.
Index: libdoctest.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdoctest.tex,v
retrieving revision 1.36
retrieving revision 1.37
diff -u -d -r1.36 -r1.37
--- libdoctest.tex 26 Aug 2004 02:45:50 -0000 1.36
+++ libdoctest.tex 26 Aug 2004 04:47:31 -0000 1.37
@@ -221,12 +221,13 @@
\subsection{What About Exceptions?}
-No problem: just paste in the expected 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.
-This makes the full story involved, but you really don't have
-to remember much. Simple example:
+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.
+
+Simple example:
\begin{verbatim}
>>> [1, 2, 3].remove(42)
@@ -236,9 +237,7 @@
\end{verbatim}
That doctest succeeds if \exception{ValueError} is raised, with the
-\samp{list.remove(x): x not in list} detail as shown.\footnote{The
- doctest also succeeds if it prints the exact text of the traceback
- message; otherwise, it fails.}
+\samp{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
@@ -250,17 +249,13 @@
\end{verbatim}
The traceback header is followed by an optional traceback stack, whose
-contents are ignored by doctest. Each line of the traceback stack
-must be indented further than the first line of the example, \emph{or}
-start with a non-alphanumeric character. Typically, the traceback
-stack is either omitted or copied verbatim from an interactive
-session.
+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
+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, as illustrated in the following
-example:
+exception has a multi-line detail:
\begin{verbatim}
>>> raise ValueError('multi\n line\ndetail')
@@ -276,7 +271,7 @@
ignored.
Best practice is to omit the traceback stack, unless it adds
-significant documentation value to the example. So the example above
+significant documentation value to the example. So the last example
is probably better as:
\begin{verbatim}
@@ -288,14 +283,36 @@
detail
\end{verbatim}
-Note the tracebacks are treated very specially. In particular, in the
+Note that tracebacks are treated very specially. In particular, in the
rewritten example, the use of \samp{...} is independent of doctest's
-\constant{ELLIPSIS} option. The ellipsis in that example could
-be left out, or could just as well be three (or three hundred) commas.
+\constant{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:
+
+\begin{itemize}
+
+\item Doctest can't guess whether your expected output came from an
+ exception traceback or from ordinary printing. So, e.g., an example
+ that expects \samp{ValueError: 42 is prime} will pass whether
+ \exception{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.
+
+\item Each line of the traceback stack (if present) must be indented
+ further than the first line of the example, \emph{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.
+
+\end{itemize}
\versionchanged[The ability to handle a multi-line exception detail
was added]{2.4}
+
\subsection{Option Flags and Directives\label{doctest-options}}
A number of option flags control various aspects of doctest's comparison
@@ -303,6 +320,10 @@
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:
+
\begin{datadesc}{DONT_ACCEPT_TRUE_FOR_1}
By default, if an expected output block contains just \code{1},
an actual output block containing just \code{1} or just
@@ -344,6 +365,8 @@
is prone to in regular expressions.
\end{datadesc}
+The second group of options controls how test failures are displayed:
+
\begin{datadesc}{REPORT_UDIFF}
When specified, failures that involve multi-line expected and
actual outputs are displayed using a unified diff.
@@ -406,7 +429,7 @@
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 requires a directive to do so:
+and also requires a directive to do so:
\begin{verbatim}
>>> print range(20) # doctest:+ELLIPSIS
More information about the Python-checkins
mailing list