docs patch: dicts and sets

[rurpy at yahoo.com]

On May 11, 7:41 pm, Raymond Hettinger <pyt... at rcn.com> wrote:
> On May 11, 5:59 pm, "Alan Isaac" <ais... at american.edu> wrote:
>
> > This is an attempt to synthesize Bill and Carsten's proposals.
> > (I'm changing the subject line to better match the topic.)
>
> >http://docs.python.org/lib/typesmapping.html:forfootnote (3)
>
> >         Keys and values are listed in an arbitrary order.  This order is
> >         indeterminate and generally depends on factors outside the scope of
> > the
> >         containing program.  However, if items(), keys(), values(),
> >         iteritems(), iterkeys(), and itervalues() are called with no
> >         intervening modifications to the dictionary, the lists will directly
> >         correspond.
>
> >http://docs.python.org/lib/types-set.html:appenda new sentence to 2nd par.
>
> >         Iteration over a set returns elements in an indeterminate
> > order,which
> >         generally depends on factors outside the scope of the containing
> >         program.
>
> This doesn't improve the docs. It suggests some mystic forces at work
> while offering nothing that is actionable or that improves
> understanding.   Adding this kind of muck will only make the docs less
> clear.

I too find the suggested text not very clear and would not
immediately predict from it the effects that started this
thread (or actually, the thread in
http://groups.google.com/group/comp.lang.python/msg/4dc632b476fdc6d3?hl=en&)

> Recommend dropping this one and moving on to solve some real problems.

Perhaps this attitude helps explain some of the problems
in the current documentation.

Dismissing this as not a "real problem" is both wrong
and offensive to people taking the time to actually
propose improvements.

The current docs are clearly wrong.  To repeat what has
already been pointed out, they say, "Keys and values are
listed in an arbitrary order which is non-random,
varies across Python implementations, and depends on the
dictionary's history of insertions and deletions."

It has been shown that even when the history of insertions
and deletions is the same, the order may be different.
Taking "history" to extend across program invocation
boundaries is unconventional to put it charitably, and
there is no reason to assume that interpretation would
occur to a reasonable reader.  The whole issue can be
cleared up simply by clarifying the documentation; I
really fail to see why this should be at all controversial.

I will offer my own suggestion based on the belief that
documentation should be as explicit as possible:

"Keys and values are listed in an arbitrary but non-random
order which may vary across Python versions, implementations,
and the dictionary's history of insertions and deletions.
When the contents are objects using the default implementation
of __hash__() and __eq__(), the order will depend on the
objects' id() values which may be different even between
different invocations of a program (whether executed from
a .py or a .pyc file for example.)"

Apropos sig...
--
Any software can be broken or fixed simply by changing
the documentation.