23.2.3.6 Warnings

###
23.2.3.6 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"}
    True

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
    >>> class C: pass
    >>> C()   # the default repr() for instances embeds an address
    <__main__.C instance at 0x00AC18F0>

The `ELLIPSIS` directive gives a nice approach for the last example:

    >>> C() #doctest: +ELLIPSIS
    <__main__.C instance at 0x...>

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.