Removed lots of stuff from the module docstring. My intent for 2.4 is

tim-one · tim-one · commit 80e53141b922 · 2004-08-09T04:34:45.000Z
to put details in the LaTeX docs instead, and lots of stuff in the
module docstring wasn't useful anyway.
diff --git a/Lib/doctest.py b/Lib/doctest.py
@@ -6,16 +6,15 @@
 
 # Provided as-is; use at your own risk; no warranty; no promises; enjoy!
 
-# [XX] This docstring is out-of-date:
 r"""Module doctest -- a framework for running examples in docstrings.
 
 NORMAL USAGE
 
-In normal use, end each module M with:
+In simplest use, end each module M to be tested with:
 
 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()
@@ -37,14 +36,20 @@ def _test():
 and a detailed report of all examples tried is printed to stdout, along
 with assorted summaries at the end.
 
-You can force verbose mode by passing "verbose=1" to testmod, or prohibit
-it by passing "verbose=0".  In either of those cases, sys.argv is not
+You can force verbose mode by passing "verbose=True" to testmod, or prohibit
+it by passing "verbose=False".  In either of those cases, sys.argv is not
 examined by testmod.
 
 In any case, testmod returns a 2-tuple of ints (f, t), where f is the
 number of docstring examples that failed and t is the total number of
 docstring examples attempted.
 
+There are a variety of other ways to run doctests, including integration
+with the unittest framework, and support for running non-Python text
+files containing doctests.  There are also many ways to override parts
+of doctest's default behaviors.  See the Library Reference Manual for
+details.
+
 
 WHICH DOCSTRINGS ARE EXAMINED?
 
@@ -59,27 +64,13 @@ def _test():
 + If M.__test__ exists and "is true", it must be a dict, and
   each entry maps a (string) name to a function object, class object, or
   string.  Function and class object docstrings found from M.__test__
-  are searched even if the name is private, and strings are searched
-  directly as if they were docstrings.  In output, a key K in M.__test__
-  appears with name
+  are searched, and strings are searched directly as if they were docstrings.
+  In output, a key K in M.__test__ appears with name
       <name of M>.__test__.K
 
 Any classes found are recursively searched similarly, to test docstrings in
-their contained methods and nested classes.  All names reached from
-M.__test__ are searched.
-
-Optionally, functions with private names can be skipped (unless listed in
-M.__test__) by supplying a function to the "isprivate" argument that will
-identify private functions.  For convenience, one such function is
-supplied.  docttest.is_private considers a name to be private if it begins
-with an underscore (like "_my_func") but doesn't both begin and end with
-(at least) two underscores (like "__init__").  By supplying this function
-or your own "isprivate" function to testmod, the behavior can be customized.
-
-If you want to test docstrings in objects with private names too, stuff
-them into an M.__test__ dict, or see ADVANCED USAGE below (e.g., pass your
-own isprivate function to Tester's constructor, or call the rundoc method
-of a Tester instance).
+their contained methods and nested classes.
+
 
 WHAT'S THE EXECUTION CONTEXT?
 
@@ -96,48 +87,6 @@ def _test():
 M.__dict__ merged with the globals from other imported modules.
 
 
-WHAT IF I WANT TO TEST A WHOLE PACKAGE?
-
-Piece o' cake, provided the modules do their testing from docstrings.
-Here's the test.py I use for the world's most elaborate Rational/
-floating-base-conversion pkg (which I'll distribute some day):
-
-from Rational import Cvt
-from Rational import Format
-from Rational import machprec
-from Rational import Rat
-from Rational import Round
-from Rational import utils
-
-modules = (Cvt,
-           Format,
-           machprec,
-           Rat,
-           Round,
-           utils)
-
-def _test():
-    import doctest
-    import sys
-    verbose = "-v" in sys.argv
-    for mod in modules:
-        doctest.testmod(mod, verbose=verbose, report=0)
-    doctest.master.summarize()
-
-if __name__ == "__main__":
-    _test()
-
-IOW, it just runs testmod on all the pkg modules.  testmod remembers the
-names and outcomes (# of failures, # of tries) for each item it's seen, and
-passing "report=0" prevents it from printing a summary in verbose mode.
-Instead, the summary is delayed until all modules have been tested, and
-then "doctest.master.summarize()" forces the summary at the end.
-
-So this is very nice in practice:  each module can be tested individually
-with almost no work beyond writing up docstring examples, and collections
-of modules can be tested too as a unit with no more work than the above.
-
-
 WHAT ABOUT EXCEPTIONS?
 
 No problem, as long as the only output generated by the example is the
@@ -149,25 +98,10 @@ def _test():
     ValueError: list.remove(x): x not in list
     >>>
 
-Note that only the exception type and value are compared (specifically,
-only the last line in the traceback).
-
+Note that only the exception type and value are compared.
 
-ADVANCED USAGE
 
-doctest.testmod() captures the testing policy I find most useful most
-often.  You may want other policies.
-
-testmod() actually creates a local instance of class doctest.Tester, runs
-appropriate methods of that class, and merges the results into global
-Tester instance doctest.master.
-
-You can create your own instances of doctest.Tester, and so build your own
-policies, or even run methods of doctest.master directly.  See
-doctest.Tester.__doc__ for details.
-
-
-SO WHAT DOES A DOCSTRING EXAMPLE LOOK LIKE ALREADY!?
+SO WHAT DOES A DOCTEST EXAMPLE LOOK LIKE ALREADY!?
 
 Oh ya.  It's easy!  In most cases a copy-and-paste of an interactive
 console session works fine -- just make sure the leading whitespace is
@@ -197,9 +131,6 @@ def _test():
 
 Bummers:
 
-+ Expected output cannot contain an all-whitespace line, since such a line
-  is taken to signal the end of expected output.
-
 + Output to stdout is captured, but not output to stderr (exception
   tracebacks are captured via a different means).
 
@@ -234,57 +165,7 @@ def _test():
 output as appeared in the initial ">>>" line that triggered it.
 
 If you execute this very file, the examples above will be found and
-executed, leading to this output in verbose mode:
-
-Running doctest.__doc__
-Trying: [1, 2, 3].remove(42)
-Expecting:
-Traceback (most recent call last):
-  File "<stdin>", line 1, in ?
-ValueError: list.remove(x): x not in list
-ok
-Trying: x = 12
-Expecting: nothing
-ok
-Trying: x
-Expecting: 12
-ok
-Trying:
-if x == 13:
-    print "yes"
-else:
-    print "no"
-    print "NO"
-    print "NO!!!"
-Expecting:
-no
-NO
-NO!!!
-ok
-... and a bunch more like that, with this summary at the end:
-
-5 items had no tests:
-    doctest.Tester.__init__
-    doctest.Tester.run__test__
-    doctest.Tester.summarize
-    doctest.run_docstring_examples
-    doctest.testmod
-12 items passed all tests:
-   8 tests in doctest
-   6 tests in doctest.Tester
-  10 tests in doctest.Tester.merge
-  14 tests in doctest.Tester.rundict
-   3 tests in doctest.Tester.rundoc
-   3 tests in doctest.Tester.runstring
-   2 tests in doctest.__test__._TestClass
-   2 tests in doctest.__test__._TestClass.__init__
-   2 tests in doctest.__test__._TestClass.get
-   1 tests in doctest.__test__._TestClass.square
-   2 tests in doctest.__test__.string
-   7 tests in doctest.is_private
-60 tests in 17 items.
-60 passed and 0 failed.
-Test passed.
+executed.
 """
 
 __all__ = [
