[Python-checkins] python/dist/src/Lib doctest.py,1.52,1.53

[tim_one at users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Lib
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv18647/Lib

Modified Files:
	doctest.py 
Log Message:
Removed lots of stuff from the module docstring.  My intent for 2.4 is
to put details in the LaTeX docs instead, and lots of stuff in the
module docstring wasn't useful anyway.


Index: doctest.py
===================================================================
RCS file: /cvsroot/python/python/dist/src/Lib/doctest.py,v
retrieving revision 1.52
retrieving revision 1.53
diff -C2 -d -r1.52 -r1.53
*** doctest.py	9 Aug 2004 04:12:36 -0000	1.52
--- doctest.py	9 Aug 2004 04:34:45 -0000	1.53
***************
*** 7,20 ****
  # 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:
  
  def _test():
!     import doctest, M           # replace M with your module's name
!     return doctest.testmod(M)   # ditto
  
  if __name__ == "__main__":
--- 7,19 ----
  # Provided as-is; use at your own risk; no warranty; no promises; enjoy!
  
  r"""Module doctest -- a framework for running examples in docstrings.
  
  NORMAL USAGE
  
! In simplest use, end each module M to be tested with:
  
  def _test():
!     import doctest
!     return doctest.testmod()
  
  if __name__ == "__main__":
***************
*** 38,43 ****
  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
  examined by testmod.
  
--- 37,42 ----
  with assorted summaries at the end.
  
! 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.
  
***************
*** 46,49 ****
--- 45,54 ----
  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?
***************
*** 60,84 ****
    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
        <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).
  
  WHAT'S THE EXECUTION CONTEXT?
--- 65,75 ----
    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, 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.
  
  
  WHAT'S THE EXECUTION CONTEXT?
***************
*** 97,142 ****
  
  
- 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?
  
--- 88,91 ----
***************
*** 150,172 ****
      >>>
  
! Note that only the exception type and value are compared (specifically,
! only the last line in the traceback).
! 
! 
! 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!?
  
  Oh ya.  It's easy!  In most cases a copy-and-paste of an interactive
--- 99,106 ----
      >>>
  
! Note that only the exception type and value are compared.
  
  
! SO WHAT DOES A DOCTEST EXAMPLE LOOK LIKE ALREADY!?
  
  Oh ya.  It's easy!  In most cases a copy-and-paste of an interactive
***************
*** 198,204 ****
  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).
--- 132,135 ----
***************
*** 235,289 ****
  
  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.
  """
  
--- 166,170 ----
  
  If you execute this very file, the examples above will be found and
! executed.
  """