[TIP] dicts in doctests

[Fred Drake]

On Wed, Sep 17, 2008 at 8:43 PM, Pete <pfein at pobox.com> wrote:
> Any thoughts?  Just go with the first case & hope for the best?  The
> ordering's relatively stable across CPythons (versions & platforms)
> AFAIK...

The ordering is not stable across versions, or even across insertion orders.

Regardless of the specific approach to controlling the output order
(pprint, sorted(d.items()), etc.), it's certain that the order needs
to be explicitly controlled in a doctest.

Keeping it explicit in the test (with a brief explanation if you think
readers won't know why it's done) ensures that the reader understands
that what's returned doesn't promise ordering of any sort, and that's
part of the documentation as well.

(Note that for structures like BTrees, leaving out the ordering
control is just as important, since that is an essential aspect of a
BTree's contract.)


 -Fred

-- 
Fred L. Drake, Jr. <fdrake at gmail.com>
"Chaos is the score upon which reality is written." --Henry Miller