[Python-Dev] Documentation Error for __hash__

[Michael Foord]

Hello all,

The documentation for __hash__ seems to be outdated. I'm happy to submit 
a patch, so long as I am not misunderstanding something.

http://docs.python.org/dev/reference/datamodel.html#object.__hash__

The documentation states:

If a class does not define a __cmp__() or __eq__() method it should not 
define a __hash__() operation either; if it defines __cmp__() or 
__eq__() but not __hash__(), its instances will not be usable as 
dictionary keys. If a class defines mutable objects and implements a 
__cmp__() or __eq__() method, it should not implement __hash__(), since 
the dictionary implementation requires that a key’s hash value is 
immutable (if the object’s hash value changes, it will be in the wrong 
hash bucket).


This may have been true for old style classes, but as new style classes 
inherit a default __hash__ from object - mutable objects *will* be 
usable as dictionary keys (hashed on identity) *unless* they implement a 
__hash__ method that raises a type error.

Shouldn't the advice be that classes that implement comparison methods 
should always implement __hash__ (wasn't this nearly enforced?), and 
that mutable objects should raise a TypeError in __hash__.

Additionally the following documentation states that __reversed__ is new 
in Python 2.6 and I think it was actually new in Python 2.4 (it 
certainly works for Python 2.5 and IronPython 1 which targets 2.4...).

http://docs.python.org/dev/reference/datamodel.html#object.__reversed__

Michael Foord

-- 
http://www.ironpythoninaction.com/
http://www.voidspace.org.uk/
http://www.trypython.org/
http://www.ironpython.info/
http://www.theotherdelia.co.uk/
http://www.resolverhacks.net/