GNU Info

(python2.1-lib.info)Warnings

---

Next: Soapbox Prev: How are Docstring Examples Recognized? Up: doctest

---

Enter node , (file) or (file)node

Warnings
--------

  1. Sloppy imports can cause trouble; e.g., if you do

          from XYZ import XYZclass

     then `XYZclass' is a name in `M.__dict__' too, and doctest has no
     way to know that `XYZclass' wasn't _defined_ in `M'.  So it may
     try to execute the examples in `XYZclass''s docstring, and those
     in turn may require a different set of globals to work correctly.
     I prefer to do "`import *'"-friendly imports, a la

          from XYZ import XYZclass as _XYZclass

     and then the leading underscore makes `_XYZclass' a private name so
     testmod skips it by default.  Other approaches are described in
     `doctest.py'.

  2. `doctest' is serious about requiring exact matches in expected
     output.  If even a single character doesn't match, the test fails.
     This will probably surprise you a few times, as you learn exactly
     what Python does and doesn't guarantee about output.  For example,
     when printing a dict, Python doesn't guarantee that the key-value
     pairs will be printed in any particular order, so a test like

          >>> foo()
          {"Hermione": "hippogryph", "Harry": "broomstick"}
          >>>

     is vulnerable!  One workaround is to do

          >>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"}
          1
          >>>

     instead.  Another is to do

          >>> d = foo().items()
          >>> d.sort()
          >>> d
          [('Harry', 'broomstick'), ('Hermione', 'hippogryph')]

     There are others, but you get the idea.

     Another bad idea is to print things that embed an object address,
     like

          >>> id(1.0) # certain to fail some of the time
          7948648
          >>>

     Floating-point numbers are also subject to small output variations
     across platforms, because Python defers to the platform C library
     for float formatting, and C libraries vary widely in quality here.

          >>> 1./7  # risky
          0.14285714285714285
          >>> print 1./7 # safer
          0.142857142857
          >>> print round(1./7, 6) # much safer
          0.142857

     Numbers of the form `I/2.**J' are safe across all platforms, and I
     often contrive doctest examples to produce numbers of that form:

          >>> 3./4  # utterly safe
          0.75

     Simple fractions are also easier for people to understand, and
     that makes for better documentation.

  3. Be careful if you have code that must only execute once.

     If you have module-level code that must only execute once, a more
     foolproof definition of `_test()' is

          def _test():
              import doctest, sys
              doctest.testmod(sys.modules["__main__"])