diff options
author | Tim Peters <tim.peters@gmail.com> | 2004-09-25 00:10:53 (GMT) |
---|---|---|
committer | Tim Peters <tim.peters@gmail.com> | 2004-09-25 00:10:53 (GMT) |
commit | 7a082142d8f26be420bb302dd2b3624ee543c06e (patch) | |
tree | 02f5392d997781ece09fd6dd1c8ec314dcb9f727 /Doc/lib | |
parent | 27ebcae450c0b4aec47ef0e8a9bbcfdc4054f3bc (diff) | |
download | cpython-7a082142d8f26be420bb302dd2b3624ee543c06e.zip cpython-7a082142d8f26be420bb302dd2b3624ee543c06e.tar.gz cpython-7a082142d8f26be420bb302dd2b3624ee543c06e.tar.bz2 |
Since the LaTeX isn't doctest'ed, examples are always wrong <wink>.
Diffstat (limited to 'Doc/lib')
-rw-r--r-- | Doc/lib/libdoctest.tex | 38 |
1 files changed, 21 insertions, 17 deletions
diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex index 0fb5c54..3fb4af1 100644 --- a/Doc/lib/libdoctest.tex +++ b/Doc/lib/libdoctest.tex @@ -2,8 +2,8 @@ Test interactive Python examples} \declaremodule{standard}{doctest} -\moduleauthor{Tim Peters}{tim_one@users.sourceforge.net} -\sectionauthor{Tim Peters}{tim_one@users.sourceforge.net} +\moduleauthor{Tim Peters}{tim@python.org} +\sectionauthor{Tim Peters}{tim@python.org} \sectionauthor{Moshe Zadka}{moshez@debian.org} \sectionauthor{Edward Loper}{edloper@users.sourceforge.net} @@ -11,17 +11,21 @@ The \module{doctest} module searches for pieces of text that look like interactive Python sessions, and then executes those sessions to -verify that they work exactly as shown. There are two common ways to +verify that they work exactly as shown. There are several common ways to use doctest: -\begin{enumerate} +\begin{itemize} \item To check that a module's docstrings are up-to-date by verifying that all interactive examples still work as documented. \item To perform regression testing by verifying that interactive examples from a test file or a test object work as expected. -\end{enumerate} +\item To write tutorial documentation for a package, liberally + illustrated with input-ouput examples. Depending on whether + the examples or the expository text are emphasized, this has + the flavor of "literate testing" or "executable documentation". +\end{itemize} -Here's a complete but small example: +Here's a complete but small example module: \begin{verbatim} """ @@ -81,16 +85,13 @@ def factorial(n): result = 1 factor = 2 while factor <= n: - try: - result *= factor - except OverflowError: - result *= long(factor) + result *= factor factor += 1 return result def _test(): import doctest - return doctest.testmod() + doctest.testmod() if __name__ == "__main__": _test() @@ -138,10 +139,12 @@ Expecting: ... OverflowError: n too large ok +1 items had no tests: + __main__._test 2 items passed all tests: - 1 tests in example - 8 tests in example.factorial -9 tests in 2 items. + 1 tests in __main__ + 8 tests in __main__.factorial +9 tests in 3 items. 9 passed and 0 failed. Test passed. $ @@ -150,9 +153,10 @@ $ That's all you need to know to start making productive use of \module{doctest}! Jump in. The following sections provide full details. Note that there are many examples of doctests in -the standard Python test suite and libraries. +the standard Python test suite and libraries. Especially useful examples +can be found in the standard test file \file{Lib/test/test_doctest.py}. -\subsection{Simple Usage: Checking Examples in +\subsection{Simple Usage: Checking Examples in Docstrings\label{doctest-simple-testmod}} The simplest way to start using doctest (but not necessarily the way @@ -1262,7 +1266,7 @@ initialized by the constructor, and should not be modified directly. \class{DocTestFinder} defines the following method: -\begin{methoddesc}{find}{obj\optional{, name}\optional{, +\begin{methoddesc}{find}{obj\optional{, name}\optional{, module}\optional{, globs}\optional{, extraglobs}} Return a list of the \class{DocTest}s that are defined by \var{obj}'s docstring, or by any of its contained objects' |