[ python-Bugs-1368768 ] clearing up dictionary keys/set member docs

[SourceForge.net]

Bugs item #1368768, was opened at 2005-11-28 20:40
Message generated for change (Settings changed) made by rhettinger
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1368768&group_id=5470

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: Documentation
Group: Feature Request
>Status: Closed
>Resolution: Fixed
Priority: 5
Private: No
Submitted By: Mike Meyer (mwm)
Assigned to: Nobody/Anonymous (nobody)
Summary: clearing up dictionary keys/set member docs

Initial Comment:
The documentation for dictionaries says "A dictionary's keys are 
almost arbitrary values. Only values containing lists, dictionaries or 
other mutable types (that are compared by value rather than by 
object identity) may not be used as keys." This is wrong. tuples are 
an immutable type, but not all tuples can be used as keys.

The set documentation says "A set object is an unordered collection 
of immutable values.". This is also wrong - at least for common 
definitions of immutable.

Immutability is a convenient way of dealing with builtin types, but is 
a red herring. It's whether or not the object has a hash value that 
matters, and it's the behavior of that hash value (coupled with 
comparison) that determine whether or not things behave as 
expected.

The __hash__ documentation deals with these issues. I suggest 
replacing the current descriptions with one that references hashing, 
and a footnote pointing to the __hash__ docs for details:

Any hashable object(1) can be used as a dictionary key/set element. 
Lists, sets and dicts are not hashable, and can not be used. Tuples 
can be used if all the things they contain are hashable. Instances of 
all other built-in types and most user-defined classes are hashable.

(1) Objects for which the hash() function returns an appropriate 
value. See the __hash__ documentation for details.

----------------------------------------------------------------------

Comment By: Björn Lindqvist (sonderblade)
Date: 2007-04-04 12:11

Message:
Logged In: YES 
user_id=51702
Originator: NO

That patch have been committed, this bug should be closed.

----------------------------------------------------------------------

Comment By: Collin Winter (collinwinter)
Date: 2006-01-05 07:28

Message:
Logged In: YES 
user_id=1344176

I have submitted patch #1397711 which resolves this issue.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1368768&group_id=5470