Update __hash__ doc

[terryjreedy]

BPO	4341
Nosy	@birkenfeld, @terryjreedy, @benjaminp

^{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 = 'https://github.com/birkenfeld'
closed_at = <Date 2008-11-17.22:05:29.881>
created_at = <Date 2008-11-17.21:48:34.751>
labels = ['docs']
title = 'Update __hash__ doc'
updated_at = <Date 2008-11-17.22:05:29.880>
user = 'https://github.com/terryjreedy'

bugs.python.org fields:

activity = <Date 2008-11-17.22:05:29.880>
actor = 'benjamin.peterson'
assignee = 'georg.brandl'
closed = True
closed_date = <Date 2008-11-17.22:05:29.881>
closer = 'benjamin.peterson'
components = ['Documentation']
creation = <Date 2008-11-17.21:48:34.751>
creator = 'terry.reedy'
dependencies = []
files = []
hgrepos = []
issue_num = 4341
keywords = []
message_count = 2.0
messages = ['75984', '75986']
nosy_count = 3.0
nosy_names = ['georg.brandl', 'terry.reedy', 'benjamin.peterson']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'needs patch'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue4341'
versions = ['Python 2.6', 'Python 3.0']

[terryjreedy]

Language/data model/special method names/ __hash__

Sentence 1: "Called for the key object for dictionary operations, and by
the built-in function hash()."

Also called for the members of set and frozenset (and any other hashed
based collection).

Suggestion 1: "Called by the built-in function hash() and for operations
on members or keys of hashed collections. These currently include the
built-in classes set, frozenset, and dict."

Corresponding future-proof changes later in the text:

From "its instances will not be usable as dictionary keys"

to "its instances will not be usable as hashable members or keys".

From "since the dictionary implementation requires"

to "since hashable collection implementations require"
==============================

Sentence 2: "Should return an integer usable as a hash value for
dictionary operations."

I am confused by the qualification 'usable....'. If it does not
qualify, it is meaningless and should be removed. If it does qualify,
it should be replaced by what it means.

My impression is that integers of any value are usable since 2.5.

It is also my impression that 2.x specifically requires an int or long.
If so, "Should return an int or long integer." would be clearer.

For 3.0, I don't know what the boundaries are. A float works, even if
not integral. [bug?] A Fraction does not, even if integral, even though
int(Fraction(n,1)) returns n.

[benjaminp]

Thanks! Fixed in r67245.