diff options
author | Raymond Hettinger <python@rcn.com> | 2003-07-11 22:32:18 (GMT) |
---|---|---|
committer | Raymond Hettinger <python@rcn.com> | 2003-07-11 22:32:18 (GMT) |
commit | 92f21b13ea3642e2b029c3027897e177e121f7b0 (patch) | |
tree | 9a28e2768176cc219489d49c298d4f2f8b39314f /Doc/lib/libdoctest.tex | |
parent | b6d2f3e07d6214a91b25c9d76e3ac75ae5a65efc (diff) | |
download | cpython-92f21b13ea3642e2b029c3027897e177e121f7b0.zip cpython-92f21b13ea3642e2b029c3027897e177e121f7b0.tar.gz cpython-92f21b13ea3642e2b029c3027897e177e121f7b0.tar.bz2 |
Document Jim Fulton's docttest extensions.
Diffstat (limited to 'Doc/lib/libdoctest.tex')
-rw-r--r-- | Doc/lib/libdoctest.tex | 78 |
1 files changed, 70 insertions, 8 deletions
diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex index 2a33047..f213089 100644 --- a/Doc/lib/libdoctest.tex +++ b/Doc/lib/libdoctest.tex @@ -65,7 +65,7 @@ def factorial(n): raise ValueError("n must be >= 0") if math.floor(n) != n: raise ValueError("n must be exact integer") - if n+1 == n: # e.g., 1e300 + if n+1 == n: # catch a value like 1e300 raise OverflowError("n too large") result = 1 factor = 2 @@ -243,13 +243,75 @@ value of the example). \subsection{Advanced Usage} -\function{testmod()} actually creates a local instance of class -\class{Tester}, runs appropriate methods of that class, and merges -the results into global \class{Tester} instance \code{master}. - -You can create your own instances of \class{Tester}, and so build your -own policies, or even run methods of \code{master} directly. See -\code{Tester.__doc__} for details. +Several module level functions are available for controlling how doctests +are run. + +\begin{funcdesc}{debug}{module, name} + Debug a single docstring containing doctests. + + Provide the \var{module} (or dotted name of the module) containing the + docstring to be debugged and the \var{name} (within the module) of the + object with the docstring to be debugged. + + The doctest examples are extracted (see function \function{testsource()}), + and written to a temporary file. The Python debugger, \refmodule{pdb}, + is then invoked on that file. + \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}. + + To get finer control than \function{testmod()} offers, create an instance + of \class{Tester} with custom policies and run the methods of \code{master} + directly. See \code{Tester.__doc__} for details. +\end{funcdesc} + +\begin{funcdesc}{testsource}{module, name} + Extract the doctest examples from a docstring. + + Provide the \var{module} (or dotted name of the module) containing the + tests to be extracted and the \var{name} (within the module) of the object + with the docstring containing the tests to be extracted. + + The doctest examples are returned as a string containing Python + code. The expected output blocks in the examples are converted + to Python comments. + \versionadded{2.3} +\end{funcdesc} + +\begin{funcdesc}{DocTestSuite}{\optional{module}} + Convert doctest tests for a module to a \refmodule{unittest} + \class{TestSuite}. + + The returned \class{TestSuite} is to be run by the unittest framework + and runs each doctest in the module. If any of the doctests fail, + then the synthesized unit test fails, and a \exception{DocTestTestFailure} + exception is raised showing the name of the file containing the test and a + (sometimes approximate) line number. + + The optional \var{module} argument provides the module to be tested. It + can be a module object or a (possibly dotted) module name. If not + specified, the module calling \function{DocTestSuite()} is used. + + Example using one of the many ways that the \refmodule{unittest} module + can use a \class{TestSuite}: + + \begin{verbatim} + import unittest + import doctest + import my_module_with_doctests + + suite = doctest.DocTestSuite(my_module_with_doctests) + runner = unittest.TextTestRunner() + runner.run(suite) + \end{verbatim} + + \versionadded{2.3} +\end{funcdesc} \subsection{How are Docstring Examples Recognized?} |