docs patch: dicts and sets

[Alan Isaac]

This discussion ended abruptly, and I'd like to see it reach a
conclusion. I will attempt to synthesize Bill and Carsten's
proposals.

There are two proposed patches. The first is to
http://docs.python.org/lib/typesmapping.html
where it is proposed for footnote (3) to state:

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.

The second is for http://docs.python.org/lib/types-set.html
where the proposal is to append a new sentence to the 2nd paragraph:

Iteration over a set returns elements in an indeterminate
order,which generally depends on factors outside the scope of the
containing program.

Alan Isaac

[7stud]

>Actually, it would just move the "endless, petty discussions about what

>minutiae are more important" into the docs. I don't see how that's an
improvement.

Because it highlights the issues you will be faced with when using the
described functions. People will post about an issue they had with a
function, and then they will post their solution. Instead of having
to search all over google for an answer, the most relevant discussions
will be right in the docs. As you read the user comments, you would
be able to quickly tell whether a comment pertains to the issue you
are having trouble with, and if the comment isn't relevant, you can
skip the comment and look at the next comment. If you wanted, you
could limit yourself to reading just the official python description
of the function and be no worse off.

>And most will simply be confused.

Then it's likely someone will post something to clear up the confusion.

[Steve Holden]

7stud wrote:

>Actually, it would just move the "endless, petty discussions about what
minutiae are more important" into the docs. I don't see how that's an
improvement.

Because it highlights the issues you will be faced with when using the
described functions. People will post about an issue they had with a
function, and then they will post their solution. Instead of having
to search all over google for an answer, the most relevant discussions
will be right in the docs. As you read the user comments, you would
be able to quickly tell whether a comment pertains to the issue you
are having trouble with, and if the comment isn't relevant, you can
skip the comment and look at the next comment. If you wanted, you
could limit yourself to reading just the official python description
of the function and be no worse off.

>And most will simply be confused.

Then it's likely someone will post something to clear up the confusion.

But the real point is that it won't actually do much good to turn the
documentation into a miniature version of c.l.py itself.

You and other readers might be interested in a recent experiment by
Georg Brandl, one of the Python core developers. As Georg says, "For the
impatient: the result can be seen at <http://pydoc.gbrandl.d e>".

This is based on a translation of the existing Latex source into
ReStructured Text format. I understand Georg is considering enabling
user comments, among other enhancements. Yo should also understand that
this is a work in progress which may never come to full fruition.

regards
Steve
--
Steve Holden [phone] [phone]
Holden Web LLC/Ltd http://www.holdenweb.com
Skype: holdenweb http://del.icio.us/steve.holden
------------------ Asciimercial ---------------------
Get on the web: Blog, lens and tag your way to fame!!
holdenweb.blogs pot.com squidoo.com/pythonology
tagged items: del.icio.us/steve.holden/python
All these services currently offer free registration!
-------------- Thank You for Reading ----------------

[thinkogram]

On May 19, 8:06 am, Steven Bethard <steven.beth... @gmail.comwrote :

Seems to me that you're focusing on the wrong part of the docs. The
source of this "bug" is not sets or dicts,

Seems to me, this thread has lost touch with reality. There is no
bug, just a quest to make some random change to docs just to make
the OP feel better about not being able to grasp the concept of an
unordered collection.

Seems to me, he missed something so basic that docs won't help him.
When you care about order, then don't use an unordered collection.
Case closed. No need to add useless, distracting garbage to the docs.

Seems to me, some people would rather think themselves into knots
than to accept the obvious.
Richard T