clearing up dictionary keys/set member docs

[mwm]

BPO	1368768

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2007-04-04.17:11:28.000>
created_at = <Date 2005-11-29.01:40:08.000>
labels = ['type-feature', 'docs']
title = 'clearing up dictionary keys/set member docs'
updated_at = <Date 2007-04-04.17:11:28.000>
user = 'https://bugs.python.org/mwm'

bugs.python.org fields:

activity = <Date 2007-04-04.17:11:28.000>
actor = 'sonderblade'
assignee = 'none'
closed = True
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2005-11-29.01:40:08.000>
creator = 'mwm'
dependencies = []
files = []
hgrepos = []
issue_num = 1368768
keywords = []
message_count = 3.0
messages = ['26935', '26936', '26937']
nosy_count = 3.0
nosy_names = ['collinwinter', 'mwm', 'sonderblade']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue1368768'
versions = []

[mwm]

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.

[collinwinter]

Logged In: YES
user_id=1344176

I have submitted patch bpo-1397711 which resolves this issue.

[sonderblade]

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