Another microburst of snail-like progress.
diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex
index 7558309..282fb3a 100644
--- a/Doc/lib/libdoctest.tex
+++ b/Doc/lib/libdoctest.tex
@@ -183,92 +183,6 @@
failed and \var{t} is the total number of docstring examples
attempted.
-\begin{funcdesc}{testmod}{\optional{m}\optional{, name}\optional{,
- globs}\optional{, verbose}\optional{,
- isprivate}\optional{, report}\optional{,
- optionflags}\optional{, extraglobs}\optional{,
- raise_on_error}}
-
- All arguments are optional, and all except for \var{m} should be
- specified in keyword form.
-
- Test examples in docstrings in functions and classes reachable
- from module \var{m} (or the current module if \var{m} is not supplied
- or is \code{None}), starting with \code{\var{m}.__doc__}.
-
- Also test examples reachable from dict \code{\var{m}.__test__}, if it
- exists and is not \code{None}. \code{\var{m}.__test__} maps
- names (strings) to functions, classes and strings; function and class
- docstrings are searched for examples; strings are searched directly,
- as if they were docstrings.
-
- Only docstrings attached to objects belonging to module \var{m} are
- searched.
-
- Return \samp{(\var{failure_count}, \var{test_count})}.
-
- Optional argument \var{name} gives the name of the module; by default,
- or if \code{None}, \code{\var{m}.__name__} is used.
-
- Optional argument \var{globs} gives a dict to be used as the globals
- when executing examples; by default, or if \code{None},
- \code{\var{m}.__dict__} is used. A new shallow copy of this dict is
- created for each docstring with examples, so that each docstring's
- examples start with a clean slate.
-
- Optional argument \var{extraglobs} gives a dict merged into the
- globals used to execute examples. This works like
- \method{dict.update()}: if \var{globs} and \var{extraglobs} have a
- common key, the associated value in \var{extraglobs} appears in the
- combined dict. By default, or if \code{None}, no extra globals are
- used. This is an advanced feature that allows parameterization of
- doctests. For example, a doctest can be written for a base class, using
- a generic name for the class, then reused to test any number of
- subclasses by passing an \var{extraglobs} dict mapping the generic
- name to the subclass to be tested.
-
- Optional argument \var{verbose} prints lots of stuff if true, and prints
- only failures if false; by default, or if \code{None}, it's true
- if and only if \code{'-v'} is in \code{sys.argv}.
-
- Optional argument \var{report} prints a summary at the end when true,
- else prints nothing at the end. In verbose mode, the summary is
- detailed, else the summary is very brief (in fact, empty if all tests
- passed).
-
- Optional argument \var{optionflags} or's together option flags. See
- see section \ref{doctest-options}.
-
- Optional argument \var{raise_on_error} defaults to false. If true,
- an exception is raised upon the first failure or unexpected exception
- in an example. This allows failures to be post-mortem debugged.
- Default behavior is to continue running examples.
-
- Optional argument \var{isprivate} specifies a function used to
- determine whether a name is private. The default function treats
- all names as public. \var{isprivate} can be set to
- \code{doctest.is_private} to skip over names that are
- private according to Python's underscore naming convention.
- \deprecated{2.4}{\var{isprivate} was a stupid idea -- don't use it.
- If you need to skip tests based on name, filter the list returned by
- \code{DocTestFinder.find()} instead.}
-
-% """ [XX] This is no longer true:
-% Advanced tomfoolery: testmod runs methods of a local instance of
-% class doctest.Tester, then merges the results into (or creates)
-% global Tester instance doctest.master. Methods of doctest.master
-% can be called directly too, if you want to do something unusual.
-% Passing report=0 to testmod is especially useful then, to delay
-% displaying a summary. Invoke doctest.master.summarize(verbose)
-% when you're done fiddling.
-
- \versionchanged[The parameter \var{optionflags} was added]{2.3}
-
- \versionchanged[The parameters \var{extraglobs} and \var{raise_on_error}
- were added]{2.4}
-\end{funcdesc}
-
-
\subsection{Which Docstrings Are Examined?}
The module docstring, and all function, class and method docstrings are
@@ -386,10 +300,10 @@
\subsection{Option Flags and Directive Names\label{doctest-options}}
-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.
+A number of option flags control various aspects of doctest's comparison
+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.
\begin{datadesc}{DONT_ACCEPT_TRUE_FOR_1}
By default, if an expected output block contains just \code{1},
@@ -445,8 +359,8 @@
\versionchanged[Constants \constant{DONT_ACCEPT_BLANKLINE},
\constant{NORMALIZE_WHITESPACE}, \constant{ELLIPSIS},
\constant{UNIFIED_DIFF}, and \constant{CONTEXT_DIFF}
- were added, and \code{<BLANKLINE>} in expected output matches
- an empty line in actual output by default]{2.4}
+ were added, and by default \code{<BLANKLINE>} in expected output
+ matches an empty line in actual output]{2.4}
\subsection{Advanced Usage}
@@ -466,15 +380,80 @@
\versionadded{2.3}
\end{funcdesc}
-\begin{funcdesc}{testmod}{}
- This function provides the most basic interface to the doctests.
- It creates a local instance of class \class{Tester}, runs appropriate
- methods of that class, and merges the results into the global \class{Tester}
- instance, \code{master}.
+\begin{funcdesc}{testmod}{\optional{m}\optional{, name}\optional{,
+ globs}\optional{, verbose}\optional{,
+ isprivate}\optional{, report}\optional{,
+ optionflags}\optional{, extraglobs}\optional{,
+ raise_on_error}}
- To get finer control than \function{testmod()} offers, create an instance
- of \class{Tester} with custom policies, or run methods of \code{master}
- directly. See \code{Tester.__doc__} for details.
+ All arguments are optional, and all except for \var{m} should be
+ specified in keyword form.
+
+ Test examples in docstrings in functions and classes reachable
+ from module \var{m} (or the current module if \var{m} is not supplied
+ or is \code{None}), starting with \code{\var{m}.__doc__}.
+
+ Also test examples reachable from dict \code{\var{m}.__test__}, if it
+ exists and is not \code{None}. \code{\var{m}.__test__} maps
+ names (strings) to functions, classes and strings; function and class
+ docstrings are searched for examples; strings are searched directly,
+ as if they were docstrings.
+
+ Only docstrings attached to objects belonging to module \var{m} are
+ searched.
+
+ Return \samp{(\var{failure_count}, \var{test_count})}.
+
+ Optional argument \var{name} gives the name of the module; by default,
+ or if \code{None}, \code{\var{m}.__name__} is used.
+
+ Optional argument \var{globs} gives a dict to be used as the globals
+ when executing examples; by default, or if \code{None},
+ \code{\var{m}.__dict__} is used. A new shallow copy of this dict is
+ created for each docstring with examples, so that each docstring's
+ examples start with a clean slate.
+
+ Optional argument \var{extraglobs} gives a dict merged into the
+ globals used to execute examples. This works like
+ \method{dict.update()}: if \var{globs} and \var{extraglobs} have a
+ common key, the associated value in \var{extraglobs} appears in the
+ combined dict. By default, or if \code{None}, no extra globals are
+ used. This is an advanced feature that allows parameterization of
+ doctests. For example, a doctest can be written for a base class, using
+ a generic name for the class, then reused to test any number of
+ subclasses by passing an \var{extraglobs} dict mapping the generic
+ name to the subclass to be tested.
+
+ Optional argument \var{verbose} prints lots of stuff if true, and prints
+ only failures if false; by default, or if \code{None}, it's true
+ if and only if \code{'-v'} is in \code{sys.argv}.
+
+ Optional argument \var{report} prints a summary at the end when true,
+ else prints nothing at the end. In verbose mode, the summary is
+ detailed, else the summary is very brief (in fact, empty if all tests
+ passed).
+
+ Optional argument \var{optionflags} or's together option flags. See
+ see section \ref{doctest-options}.
+
+ Optional argument \var{raise_on_error} defaults to false. If true,
+ an exception is raised upon the first failure or unexpected exception
+ in an example. This allows failures to be post-mortem debugged.
+ Default behavior is to continue running examples.
+
+ Optional argument \var{isprivate} specifies a function used to
+ determine whether a name is private. The default function treats
+ all names as public. \var{isprivate} can be set to
+ \code{doctest.is_private} to skip over names that are
+ private according to Python's underscore naming convention.
+ \deprecated{2.4}{\var{isprivate} was a stupid idea -- don't use it.
+ If you need to skip tests based on name, filter the list returned by
+ \code{DocTestFinder.find()} instead.}
+
+ \versionchanged[The parameter \var{optionflags} was added]{2.3}
+
+ \versionchanged[The parameters \var{extraglobs} and \var{raise_on_error}
+ were added]{2.4}
\end{funcdesc}
\begin{funcdesc}{testsource}{module, name}
@@ -527,10 +506,14 @@
\subsection{How are Docstring Examples Recognized?}
In most cases a copy-and-paste of an interactive console session works
-fine---just make sure the leading whitespace is rigidly consistent
-(you can mix tabs and spaces if you're too lazy to do it right, but
-\module{doctest} is not in the business of guessing what you think a tab
-means).
+fine, but doctest isn't trying to do an exact emulation of any specific
+Python shell. All hard tab characters are expanded to spaces, using
+8-column tab stops. If you don't believe tabs should mean that, too
+bad: don't use hard tabs, or write your own \class{DocTestParser}
+class.
+
+\versionchanged[Expanding tabs to spaces is new; previous versions
+ tried to preserve hard tabs, with confusing results]{2.4}
\begin{verbatim}
>>> # comments are ignored
@@ -560,7 +543,12 @@
\begin{itemize}
\item Expected output cannot contain an all-whitespace line, since such a
- line is taken to signal the end of expected output.
+ line is taken to signal the end of expected output. If expected
+ output does contain a blank line, put \code{<BLANKLINE>} in your
+ doctest example each place a blank line is expected.
+ \versionchanged[\code{<BLANKLINE>} was added; there was no way to
+ use expected output containing empty lines in
+ previous versions]{2.4}
\item Output to stdout is captured, but not output to stderr (exception
tracebacks are captured via a different means).
@@ -600,7 +588,7 @@
and as many leading whitespace characters are stripped from the
expected output as appeared in the initial \code{'>\code{>}>~'} line
-that triggered it.
+that started the example.
\end{itemize}
\subsection{Warnings}