diff options
| -rw-r--r-- | Doc/lib/libdoctest.tex | 175 | ||||
| -rw-r--r-- | Lib/doctest.py | 2 |
2 files changed, 148 insertions, 29 deletions
diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex index 919f86b..c51ba2d 100644 --- a/Doc/lib/libdoctest.tex +++ b/Doc/lib/libdoctest.tex @@ -78,8 +78,8 @@ def factorial(n): return result def _test(): - import doctest, example - return doctest.testmod(example) + import doctest + return doctest.testmod() if __name__ == "__main__": _test() @@ -100,33 +100,25 @@ end: \begin{verbatim} $ python example.py -v -Running example.__doc__ Trying: factorial(5) Expecting: 120 ok -0 of 1 examples failed in example.__doc__ -Running example.factorial.__doc__ Trying: [factorial(n) for n in range(6)] Expecting: [1, 1, 2, 6, 24, 120] ok Trying: [factorial(long(n)) for n in range(6)] Expecting: [1, 1, 2, 6, 24, 120] -ok -Trying: factorial(30) -Expecting: 265252859812191058636308480000000L -ok -\end{verbatim} +ok\end{verbatim} And so on, eventually ending with: \begin{verbatim} Trying: factorial(1e100) Expecting: -Traceback (most recent call last): - ... -OverflowError: n too large + Traceback (most recent call last): + ... + OverflowError: n too large ok -0 of 8 examples failed in example.factorial.__doc__ 2 items passed all tests: 1 tests in example 8 tests in example.factorial @@ -137,28 +129,27 @@ $ \end{verbatim} That's all you need to know to start making productive use of -\module{doctest}! Jump in. The docstrings in \file{doctest.py} contain -detailed information about all aspects of \module{doctest}, and we'll -just cover the more important points here. +\module{doctest}! Jump in. -\subsection{Normal Usage} +\subsection{Simple Usage} -In normal use, end each module \module{M} with: +The simplest (not necessarily the best) way to start using doctest is to +end each module \module{M} with: \begin{verbatim} def _test(): - import doctest, M # replace M with your module's name - return doctest.testmod(M) # ditto + import doctest + return doctest.testmod() if __name__ == "__main__": _test() \end{verbatim} -If you want to test the current module as the main module, you don't need to -pass M to \function{testmod()}; in this case, it will test the current -module. +\module{doctest} then examines docstrings in the module calling +\function{testmod()}. If you want to test a different module, you can +pass that module object to \function{testmod()}. -Then running the module as a script causes the examples in the docstrings +Running the module as a script causes the examples in the docstrings to get executed and verified: \begin{verbatim} @@ -167,7 +158,9 @@ python M.py This won't display anything unless an example fails, in which case the failing example(s) and the cause(s) of the failure(s) are printed to stdout, -and the final line of output is \code{'Test failed.'}. +and the final line of output is +\\code{'***Test Failed*** \var{N} failures.'}, where \var{N} is the +number of examples that failed. Run it with the \programopt{-v} switch instead: @@ -178,9 +171,9 @@ python M.py -v and a detailed report of all examples tried is printed to standard output, along with assorted summaries at the end. -You can force verbose mode by passing \code{verbose=1} to +You can force verbose mode by passing \code{verbose=True} to \function{testmod()}, or -prohibit it by passing \code{verbose=0}. In either of those cases, +prohibit it by passing \code{verbose=False}. In either of those cases, \code{sys.argv} is not examined by \function{testmod()}. In any case, \function{testmod()} returns a 2-tuple of ints \code{(\var{f}, @@ -188,6 +181,132 @@ 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 \code{(#failures, #tests)}. + + 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 dicti 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{\module{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 module constants, + and defaults to 0. + +% Possible values: +% +% DONT_ACCEPT_TRUE_FOR_1 +% By default, if an expected output block contains just "1", +% an actual output block containing just "True" is considered +% to be a match, and similarly for "0" versus "False". When +% DONT_ACCEPT_TRUE_FOR_1 is specified, neither substitution +% is allowed. +% +% DONT_ACCEPT_BLANKLINE +% By default, if an expected output block contains a line +% containing only the string "<BLANKLINE>", then that line +% will match a blank line in the actual output. When +% DONT_ACCEPT_BLANKLINE is specified, this substitution is +% not allowed. +% +% NORMALIZE_WHITESPACE +% When NORMALIZE_WHITESPACE is specified, all sequences of +% whitespace are treated as equal. I.e., any sequence of +% whitespace within the expected output will match any +% sequence of whitespace within the actual output. +% +% ELLIPSIS +% When ELLIPSIS is specified, then an ellipsis marker +% ("...") in the expected output can match any substring in +% the actual output. +% +% UNIFIED_DIFF +% When UNIFIED_DIFF is specified, failures that involve +% multi-line expected and actual outputs will be displayed +% using a unified diff. +% +% CONTEXT_DIFF +% When CONTEXT_DIFF is specified, failures that involve +% multi-line expected and actual outputs will be displayed +% using a context diff. + + 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{\module{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{\class{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[Many new module constants for use with \var{optionflags} + were added]{2.4} + + \versionchanged[The parameters \var{extraglobs} and \var{raise_on_error} + were added]{2.4} +\end{funcdesc} + + \subsection{Which Docstrings Are Examined?} See the docstrings in \file{doctest.py} for all the details. They're diff --git a/Lib/doctest.py b/Lib/doctest.py index 80a61c5..7c07131 100644 --- a/Lib/doctest.py +++ b/Lib/doctest.py @@ -1610,7 +1610,7 @@ def testmod(m=None, name=None, globs=None, verbose=None, isprivate=None, are not skipped. Also test examples reachable from dict m.__test__ if it exists and is - not None. m.__dict__ maps names to functions, classes and strings; + not None. m.__test__ maps names to functions, classes and strings; function and class docstrings are tested even if the name is private; strings are tested directly, as if they were docstrings. |