summaryrefslogtreecommitdiffstats
path: root/Doc/reference/datamodel.rst
diff options
context:
space:
mode:
authorBarry Warsaw <barry@python.org>2013-07-15 18:47:29 (GMT)
committerBarry Warsaw <barry@python.org>2013-07-15 18:47:29 (GMT)
commit224a599c0c0755a3a2602a9f0051a6707c8e1162 (patch)
tree598c3d6fac4c1ccec71c549b9b1cd4172592b4cb /Doc/reference/datamodel.rst
parent48830035e5e616b9660014cc451198b82e3f8a8e (diff)
downloadcpython-224a599c0c0755a3a2602a9f0051a6707c8e1162.zip
cpython-224a599c0c0755a3a2602a9f0051a6707c8e1162.tar.gz
cpython-224a599c0c0755a3a2602a9f0051a6707c8e1162.tar.bz2
- Issue #18440: Clarify that `hash()` can truncate the value returned from an
object's custom `__hash__()` method.
Diffstat (limited to 'Doc/reference/datamodel.rst')
-rw-r--r--Doc/reference/datamodel.rst19
1 files changed, 15 insertions, 4 deletions
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index e815690..f8e9280 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1264,10 +1264,21 @@ Basic customization
Called by built-in function :func:`hash` and for operations on members of
hashed collections including :class:`set`, :class:`frozenset`, and
- :class:`dict`. :meth:`__hash__` should return an integer. The only required
- property is that objects which compare equal have the same hash value; it is
- advised to somehow mix together (e.g. using exclusive or) the hash values for
- the components of the object that also play a part in comparison of objects.
+ :class:`dict`. :meth:`__hash__` should return an integer. The only
+ required property is that objects which compare equal have the same hash
+ value; it is advised to somehow mix together (e.g. using exclusive or) the
+ hash values for the components of the object that also play a part in
+ comparison of objects.
+
+ .. note::
+
+ :func:`hash` truncates the value returned from an object's custom
+ :meth:`__hash__` method to the size of a :c:type:`Py_ssize_t`. This is
+ typically 8 bytes on 64-bit builds and 4 bytes on 32-bit builds. If an
+ object's :meth:`__hash__` must interoperate on builds of different bit
+ sizes, be sure to check the width on all supported builds. An easy way
+ to do this is with
+ ``python -c "import sys; print(sys.hash_info.width)"``
If a class does not define an :meth:`__eq__` method it should not define a
:meth:`__hash__` operation either; if it defines :meth:`__eq__` but not