Doctest provides several mechanisms for debugging doctest examples:
""" >>> def f(x): ... g(x*2) >>> def g(x): ... print x+3 ... import pdb; pdb.set_trace() >>> f(3) 9 """
Then an interactive Python session may look like this:
>>> import a, doctest >>> doctest.testmod(a) --Return-- > <doctest a>(3)g()->None -> import pdb; pdb.set_trace() (Pdb) list 1 def g(x): 2 print x+3 3 -> import pdb; pdb.set_trace() [EOF] (Pdb) print x 6 (Pdb) step --Return-- > <doctest a>(2)f()->None -> g(x*2) (Pdb) list 1 def f(x): 2 -> g(x*2) [EOF] (Pdb) print x 3 (Pdb) step --Return-- > <doctest a>(1)?()->None -> f(3) (Pdb) cont (0, 3) >>>
Changed in version 2.4:
The ability to use
usefully inside doctests was added.
Functions that convert doctests to Python code, and possibly run the synthesized code under the debugger:
Argument s is a string containing doctest examples. The string is converted to a Python script, where doctest examples in s are converted to regular code, and everything else is converted to Python comments. The generated script is returned as a string. For example,
import doctest print doctest.script_from_examples(r""" Set x and y to 1 and 2. >>> x, y = 1, 2 Print their sum: >>> print x+y 3 """)
# Set x and y to 1 and 2. x, y = 1, 2 # # Print their sum: print x+y # Expected: ## 3
This function is used internally by other functions (see below), but can also be useful when you want to transform an interactive Python session into a Python script.
New in version 2.4.
Argument module is a module object, or dotted name of a module, containing the object whose doctests are of interest. Argument name is the name (within the module) of the object with the doctests of interest. The result is a string, containing the object's docstring converted to a Python script, as described for script_from_examples() above. For example, if module a.py contains a top-level function f(), then
import a, doctest print doctest.testsource(a, "a.f")
prints a script version of function f()'s docstring, with doctests converted to code, and the rest placed in comments.
New in version 2.3.
|module, name[, pm])|
The module and name arguments are the same as for function testsource() above. The synthesized Python script for the named object's docstring is written to a temporary file, and then that file is run under the control of the Python debugger, pdb.
A shallow copy of
module.__dict__ is used for both local
and global execution context.
Optional argument pm controls whether post-mortem debugging is
used. If pm has a true value, the script file is run directly, and
the debugger gets involved only if the script terminates via raising an
unhandled exception. If it does, then post-mortem debugging is invoked,
pdb.post_mortem(), passing the traceback object
from the unhandled exception. If pm is not specified, or is false,
the script is run under the debugger from the start, via passing an
appropriate execfile() call to
New in version 2.3.
Changed in version 2.4: The pm argument was added.
|src[, pm][, globs])|
This is like function debug() above, except that a string containing doctest examples is specified directly, via the src argument.
Optional argument pm has the same meaning as in function debug() above.
Optional argument globs gives a dictionary to use as both
local and global execution context. If not specified, or
an empty dictionary is used. If specified, a shallow copy of the
dictionary is used.
New in version 2.4.
The DebugRunner class, and the special exceptions it may raise, are of most interest to testing framework authors, and will only be sketched here. See the source code, and especially DebugRunner's docstring (which is a doctest!) for more details:
|[checker][, verbose][, optionflags])|
A subclass of DocTestRunner that raises an exception as soon as a failure is encountered. If an unexpected exception occurs, an UnexpectedException exception is raised, containing the test, the example, and the original exception. If the output doesn't match, then a DocTestFailure exception is raised, containing the test, the example, and the actual output.
For information about the constructor parameters and methods, see the documentation for DocTestRunner in section 5.2.6.
There are two exceptions that may be raised by DebugRunner instances:
|test, example, got)|
|test, example, exc_info)|
See About this document... for information on suggesting changes.