5.2.7 Warnings

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.
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__"])
```

See About this document... for information on suggesting changes.