On May 20, 3:12 am, Raymond Hettinger <[EMAIL PROTECTED]> wrote: > On May 13, 4:52 pm, [EMAIL PROTECTED] 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!] -- http://mail.python.org/mailman/listinfo/python-list
