docs patch: dicts and sets

[rurpy at yahoo.com]

On May 20, 3:12 am, Raymond Hettinger <pyt... at rcn.com> wrote:
> On May 13, 4:52 pm, r... at yahoo.com wrote:
> > Dismissing this as not a "real problem" is both wrong
> > and offensive to people taking the time to actually
> > propose improvements.
>
> I should have elaborated on what I meant by saying that there is not a
> real problem.  Another way to put it is that the docs are sufficient
> when they say that set ordering is arbitrary.  That should be a cue to
> not have *any* expectations about the internal ordering of sets and
> dicts.

I disagree.  When reading the docs, the reader will
always have and need assumtions because the docs can't
describe all behavior from first priciples.  Every
programmer will bring and apply his or her understanding
of how computers and computer programs operate under
the hood.

For example, nowhere in the "file" object documentation
does is say the files are read starting from byte 0.
It relies on the fact that the reader will have that
expectation based on previous experience with computers.

The are two basics principles that I think most
programmers apply sans explicit contradictory
information:
* That documentation about behavior applies within
  the bounds of a single execution.
* That computers are fundamentaly deterministic
  (with a possible exception for code running in
  Microsoft OSes. :-)

When I read that sets return items in arbitrary
order (and the docs aren't even that specific),
I make a natural assumption that, no information
provided to the contrary, within a single program
execution the order will be arbitrary.  Since it
says nothing about between execution, the very
strong general rule applies: that if no obvious
source of volatilty or dependence on environment
exist, the same program should produce the same
results.

> Any further documentation of behavior would be a mistake because it
> would of necessity expose implementation specific details.

You don't need to make promises to explain surprising
behavior.  (The word "may" is amazingly useful in these
cases :-)  A "for example" that exposes implementation
details make no promises yet can make clear non-intuative
behavior.  A concise but clear noting of the surprising
behavior seen by the OP would improve the clarity of the
documentation, not harm it.

> For
> instance, there is another intentionally undocumented observable
> behavior that sets and dicts change their internal order as new
> members are added.  It is also intentional that Python makes almost no
> promises about the location of objects in memory.  IIRC, the only
> guarantees made about object identity are that "a is a" is always true
> and None can be tested with "is".

One last comment.  While I treat opinions from Python
experts on Python technical details with great respect
and appreciation, opinions on documentation should be
viewed with much greater skepticism.  It can be difficult
for an expert to view Python with the same eyes as a
non-guru level programmer, yet the latter is (or
should be) the target audience of the documentation.
[And please, let's not start the reference vs tutorial
thing!]