Now that they've settled down, document doctest directives.

tim-one · tim-one · commit 026f8dc103da · 2004-08-19T16:38:58.000Z
diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex
@@ -298,12 +298,12 @@ \subsection{What About Exceptions?}
                 exception detail, were added]{2.4}
 
 
-\subsection{Option Flags and Directive Names\label{doctest-options}}
+\subsection{Option Flags and Directives\label{doctest-options}}
 
 A number of option flags control various aspects of doctest's comparison
-behavior. Symbolic names for the flags are supplied as module constants,
+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.
+can also be used in doctest directives (see below).
 
 \begin{datadesc}{DONT_ACCEPT_TRUE_FOR_1}
     By default, if an expected output block contains just \code{1},
@@ -340,9 +340,10 @@ \subsection{Option Flags and Directive Names\label{doctest-options}}
 \begin{datadesc}{ELLIPSIS}
     When specified, an ellipsis marker (\code{...}) in the expected output
     can match any substring in the actual output.  This includes
-    substrings that span line boundaries, so it's best to keep usage of
-    this simple.  Complicated uses can lead to the same kinds of
-    surprises that \regexp{.*} is prone to in regular expressions.
+    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 \regexp{.*}
+    is prone to in regular expressions.
 \end{datadesc}
 
 \begin{datadesc}{UNIFIED_DIFF}
@@ -356,11 +357,68 @@ \subsection{Option Flags and Directive Names\label{doctest-options}}
 \end{datadesc}
 
 
+A "doctest directive" is a trailing Python comment on a line of a doctest
+example:
+
+\begin{productionlist}[doctest]
+    \production{directive}
+               {"#" "doctest:" \token{on_or_off} \token{directive_name}}
+    \production{on_or_off}
+               {"+" | "-"}
+    \production{directive_name}
+               {"DONT_ACCEPT_BLANKLINE" | "NORMALIZE_WHITESPACE" | ...}
+\end{productionlist}
+
+Whitespace is not allowed between the \code{+} or \code{-} and the
+directive name.  The directive name can be any of the option names
+explained above.
+
+The doctest directives appearing in a single example modify doctest's
+behavior for that single example.  Use \code{+} to enable the named
+behavior, or \code{-} to disable it.
+
+For example, this test passes:
+
+\begin{verbatim}
+>>> 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]
+\end{verbatim}
+
+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:
+
+\begin{verbatim}
+>>> print range(20) # doctest:+ELLIPSIS
+[0, 1, ..., 18, 19]
+\end{verbatim}
+
+Only one directive per physical line is accepted.  If you want to
+use multiple directives for a single example, you can add
+\samp{...} lines to your example containing only directives:
+
+\begin{verbatim}
+>>> print range(20) #doctest: +ELLIPSIS
+...                 #doctest: +NORMALIZE_WHITESPACE
+[0,    1, ...,   18,    19]
+\end{verbatim}
+
+Note that since all options are disabled by default, and directives apply
+only to the example they appear in, enabling options (via \code{+} 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 \code{-} in a directive
+can be useful.
+
 \versionchanged[Constants \constant{DONT_ACCEPT_BLANKLINE},
     \constant{NORMALIZE_WHITESPACE}, \constant{ELLIPSIS},
     \constant{UNIFIED_DIFF}, and \constant{CONTEXT_DIFF}
-    were added, and by default \code{<BLANKLINE>} in expected output
-    matches an empty line in actual output]{2.4}
+    were added; by default \code{<BLANKLINE>} in expected output
+    matches an empty line in actual output; and doctest directives
+    were added]{2.4}
+
 
 \subsection{Advanced Usage}
 
diff --git a/Lib/test/test_doctest.py b/Lib/test/test_doctest.py
@@ -758,6 +758,11 @@ def optionflags(): r"""
     >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
     (0, 1)
 
+    An example from the docs:
+    >>> 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]
+
 The ELLIPSIS flag causes ellipsis marker ("...") in the expected
 output to match any substring in the actual output:
 
@@ -780,8 +785,8 @@ def optionflags(): r"""
     >>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
     (0, 1)
 
-... should also match nothing gracefully (note that a regular-expression
-implementation of ELLIPSIS would take a loooong time to match this one!):
+    ... should also match nothing gracefully (note that a regular-expression
+    implementation of ELLIPSIS would take a loooong time to match this one!):
 
     >>> for i in range(100):
     ...     print i**2 #doctest: +ELLIPSIS
@@ -801,7 +806,7 @@ def optionflags(): r"""
     9801
     ...
 
-... can be surprising; e.g., this test passes:
+    ... can be surprising; e.g., this test passes:
 
     >>> for i in range(21): #doctest: +ELLIPSIS
     ...     print i
@@ -815,6 +820,15 @@ def optionflags(): r"""
     ...
     0
 
+    Examples from the docs:
+
+    >>> print range(20) # doctest:+ELLIPSIS
+    [0, 1, ..., 18, 19]
+
+    >>> print range(20) # doctest: +ELLIPSIS
+    ...                 # doctest: +NORMALIZE_WHITESPACE
+    [0,    1, ...,   18,    19]
+
 The UNIFIED_DIFF flag causes failures that involve multi-line expected
 and actual outputs to be displayed using a unified diff:
 
