## 5.1.7 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.