traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Another microburst of snail-like progress.

This commit is contained in:
Tim Peters 2004-08-13 21:55:21 +00:00
parent 9d499f2f96
commit 83e259a2c2
1 changed files with 94 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

200
Doc/lib/libdoctest.tex
View File

@ -183,92 +183,6 @@ In any case, \function{testmod()} returns a 2-tuple of ints \code{(\var{f},
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 @@ be left out, or could just as well be three (or three hundred) commas.
\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 @@ also be used in doctest directives.
\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 @@ are run.
\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 @@ are run.
\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 @@ The fine print:
\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 @@ Backslashes in a raw docstring: m\n
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}