improve documentation of __hash__

[pkch]

BPO	15981
Nosy	@bitdancer, @pkch
Superseder	bpo-14617: confusing docs with regard to hash

^{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 2012-09-20.14:59:39.783>
created_at = <Date 2012-09-20.11:00:23.838>
labels = ['type-feature', 'docs']
title = 'improve documentation of __hash__'
updated_at = <Date 2012-09-20.14:59:39.751>
user = 'https://github.com/pkch'

bugs.python.org fields:

activity = <Date 2012-09-20.14:59:39.751>
actor = 'r.david.murray'
assignee = 'docs@python'
closed = True
closed_date = <Date 2012-09-20.14:59:39.783>
closer = 'r.david.murray'
components = ['Documentation']
creation = <Date 2012-09-20.11:00:23.838>
creator = 'max'
dependencies = []
files = []
hgrepos = []
issue_num = 15981
keywords = []
message_count = 2.0
messages = ['170798', '170816']
nosy_count = 3.0
nosy_names = ['r.david.murray', 'docs@python', 'max']
pr_nums = []
priority = 'normal'
resolution = 'duplicate'
stage = 'resolved'
status = 'closed'
superseder = '14617'
type = 'enhancement'
url = 'https://bugs.python.org/issue15981'
versions = ['Python 3.3']

[pkch]

In dev/reference/datamodel#object.__hash__, there are two paragraphs that seem inconsistent. The first paragraph seems to say that a class that overrides __eq__() *should* explicitly flag itself as unhashable. The next paragraph says that a class that overrides __eq__() *will be* flagged unhashable by default. Which one is it?

Here are the two paragraphs:

Classes which inherit a __hash__() method from a parent class but change the meaning of __eq__() such that the hash value returned is no longer appropriate (e.g. by switching to a value-based concept of equality instead of the default identity based equality) can explicitly flag themselves as being unhashable by setting __hash__ = None in the class definition. Doing so means that not only will instances of the class raise an appropriate TypeError when a program attempts to retrieve their hash value, but they will also be correctly identified as unhashable when checking isinstance(obj, collections.Hashable) (unlike classes which define their own __hash__() to explicitly raise TypeError).

If a class that overrides __eq__() needs to retain the implementation of __hash__() from a parent class, the interpreter must be told this explicitly by setting __hash__ = <ParentClass>.__hash__. Otherwise the inheritance of __hash__() will be blocked, just as if __hash__ had been explicitly set to None.

[bitdancer]

This has already been fixed, and the change is visible in the online documentation.