[docs] [issue18440] hash() and __hash__() do not document their size constraints

[Barry A. Warsaw]

New submission from Barry A. Warsaw:

If you have a custom object that implements __hash__() and it returns a value wider than Py_ssize_t, built-in hash() on the object will truncate information.  This is because hash() takes the value returned by obj.__hash__() and coerces it through PyLong_FromSsize_t().  This can cause object hashes to have different values on 64bit and 32bit machines, e.g. on 64bit Linux where Py_ssize_t is 8 bytes wide vs. 32bit Linux where it is 4 bytes wide.

This may be perfectly reasonable from an implementation point of (ref: issue9778) but it is surprising since it is not documented.

This size constraint on object hashes should be documented.

from ctypes import *

class Foo:
    def __hash__(self):
        return 0x1332a6000000000

print(hash(Foo()), sizeof(c_ssize_t))

---64bit Ubuntu 13.10---
$ python3.3 hashex.py
86459409655398400 8

---32bit Ubuntu 13.10---
$ python3 hashex.py
40260800 4

----------
assignee: docs at python
components: Documentation
messages: 193014
nosy: barry, docs at python
priority: normal
severity: normal
status: open
title: hash() and __hash__() do not document their size constraints
type: behavior
versions: Python 3.2, Python 3.3, Python 3.4

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue18440>
_______________________________________