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