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

 

[Alan Isaac]

I submitted the language based on Bill and Carsten's proposals:

https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1721372&group_id=5470

That language has been rejected.
You many want to read the discussion and see if
acceptible language still seems discoverable.

Alan Isaac

 

[Steven Bethard]

I submitted the language based on Bill and Carsten's proposals:

https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1721372&group_id=5470

That language has been rejected.
You many want to read the discussion and see if
acceptible language still seems discoverable.

Seems to me that you're focusing on the wrong part of the docs. The
source of this "bug" is not sets or dicts, but the default __hash__
method implementation. Why don't you propose adding something like:

The default __hash__ method is based on an object's id(), and can
therefore change between different iterations of the same program.

to the docs for __hash__:

http://docs.python.org/ref/customization.html

Then if you really feel you need to add something for sets and dicts,
you can add a cross-reference to the __hash__ docs.

STeVe

 

[7stud]

Seems to me that you're focusing on the wrong part of the docs. The
source of this "bug" is not sets or dicts, but the default __hash__
method implementation. Why don't you propose adding something like:

The default __hash__ method is based on an object's id(), and can
therefore change between different iterations of the same program.

to the docs for __hash__:

http://docs.python.org/ref/customization.html

Then if you really feel you need to add something for sets and dicts,
you can add a cross-reference to the __hash__ docs.

STeVe

Here's an idea--add All the proposed changes to the docs. Why not
allow user's to add any explanations to the docs that they want? Then
readers can choose the explanations that make the most sense to them.
It would eliminate endless, petty discussions about what minutiae are
more important, and it would allow people to spend their time on more
productive efforts. And it would improve the docs exponentially.

 

[Steve Holden]

Here's an idea--add All the proposed changes to the docs. Why not
allow user's to add any explanations to the docs that they want? Then
readers can choose the explanations that make the most sense to them.
It would eliminate endless, petty discussions about what minutiae are
more important, and it would allow people to spend their time on more
productive efforts. And it would improve the docs exponentially.

Except in those instances where users added information that was
explicitly wrong. Which any reader of this newsgroup knows is all too
easy to do. So there would need to be some editorial control. Which
would take effort that may not currently be available.

regards
Steve
--
Steve Holden +1 571 484 6266 +1 800 494 3119
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.blogspot.com squidoo.com/pythonology
tagged items: del.icio.us/steve.holden/python
All these services currently offer free registration!
-------------- Thank You for Reading ----------------

 

[7stud]

Except in those instances where users added information that was
explicitly wrong.

It's a self correcting mechanism. Other reader's will spot the error
and post corrections.

 

[Steve Holden]

It's a self correcting mechanism. Other reader's will spot the error
and post corrections.

The last thing I want to read in a language's documentation is an
ill-informed and sometimes interminable argument about a particular feature.

For documentation I'm all in favor of user contributions, but I believe
an editorial process is required to ensure readability. I am aware that
the documentation isn't perfect but it's pretty good, and I don't think
throwing it open to anyone (including, by the way, web spammers) to add
to it is necessarily the best way to improve it.

regards
Steve
--
Steve Holden +1 571 484 6266 +1 800 494 3119
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.blogspot.com squidoo.com/pythonology
tagged items: del.icio.us/steve.holden/python
All these services currently offer free registration!
-------------- Thank You for Reading ----------------

 

[7stud]

The last thing I want to read in a language's documentation is an
ill-informed and sometimes interminable argument about a particular feature.

Yet some readers will be able to get to the bottom of an issue they
are having by reading those comments.

 

[Steven Bethard]

Here's an idea--add All the proposed changes to the docs. Why not
allow user's to add any explanations to the docs that they want? Then
readers can choose the explanations that make the most sense to them.
It would eliminate endless, petty discussions about what minutiae are
more important, and it would allow people to spend their time on more
productive efforts.

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.

STeVe

 

[Robert Kern]

Yet some readers will be able to get to the bottom of an issue they
are having by reading those comments.

And most will simply be confused.

--
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
that is made terrible by our own mad attempt to interpret it as though it had
an underlying truth."
-- Umberto Eco

 

[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]

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.


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.de>".

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 +1 571 484 6266 +1 800 494 3119
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.blogspot.com squidoo.com/pythonology
tagged items: del.icio.us/steve.holden/python
All these services currently offer free registration!
-------------- Thank You for Reading ----------------

 

[thinkogram]

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