Start rewriting doctest's LaTeX docs. Damn, this is slow going!

tim-one · tim-one · commit c2388a2b9c75 · 2004-08-10T01:41:28.000Z
diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex
@@ -78,8 +78,8 @@ \section{\module{doctest} ---
     return result
 
 def _test():
-    import doctest, example
-    return doctest.testmod(example)
+    import doctest
+    return doctest.testmod()
 
 if __name__ == "__main__":
     _test()
@@ -100,33 +100,25 @@ \section{\module{doctest} ---
 
 \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 @@ \section{\module{doctest} ---
 \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 @@ \subsection{Normal Usage}
 
 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,16 +171,142 @@ \subsection{Normal Usage}
 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},
 \var{t})}, where \var{f} is the number of docstring examples that
 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
@@ -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.
 
