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/?fun...&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]

Alan Isaac wrote:

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

https://sourceforge.net/tracker/?fun...&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]

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

Alan Isaac wrote:

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

https://sourceforge.net/tracker/?fun...0&aid=1721372&...

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

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]

7stud wrote:

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

>Alan Isaac wrote:

>>I submitted the language based on Bill and Carsten's proposals:
https://sourceforge.net/tracker/?fun...0&aid=1721372&...
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

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

[7stud]

On May 19, 11:38 am, Steve Holden <s...@holdenweb .comwrote:

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]

7stud wrote:

On May 19, 11:38 am, Steve Holden <s...@holdenweb .comwrote:

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

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

[7stud]

On May 19, 12:36 pm, Steve Holden <s...@holdenweb .comwrote:

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]

7stud wrote:

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

>Alan Isaac wrote:

>>I submitted the language based on Bill and Carsten's proposals:
https://sourceforge.net/tracker/?fun...0&aid=1721372&...
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.

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]

7stud wrote:

On May 19, 12:36 pm, Steve Holden <s...@holdenweb .comwrote:

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

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