From 224a599c0c0755a3a2602a9f0051a6707c8e1162 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Mon, 15 Jul 2013 14:47:29 -0400 Subject: [PATCH] - Issue #18440: Clarify that `hash()` can truncate the value returned from an object's custom `__hash__()` method. --- Doc/library/functions.rst | 13 +++++++++---- Doc/reference/datamodel.rst | 19 +++++++++++++++---- Misc/NEWS | 3 +++ 3 files changed, 27 insertions(+), 8 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 04fb95ee2f4..b94c434118a 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -583,11 +583,16 @@ are always available. They are listed here in alphabetical order. .. function:: hash(object) - Return the hash value of the object (if it has one). Hash values are integers. - They are used to quickly compare dictionary keys during a dictionary lookup. - Numeric values that compare equal have the same hash value (even if they are of - different types, as is the case for 1 and 1.0). + Return the hash value of the object (if it has one). Hash values are + integers. They are used to quickly compare dictionary keys during a + dictionary lookup. Numeric values that compare equal have the same hash + value (even if they are of different types, as is the case for 1 and 1.0). + .. note:: + + For object's with custom :meth:`__hash__` methods, note that :func:`hash` + truncates the return value based on the bit width of the host machine. + See :meth:`__hash__` for details. .. function:: help([object]) diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index e815690865b..f8e92807681 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 diff --git a/Misc/NEWS b/Misc/NEWS index 56ebe918fc4..5bfa69641ed 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -210,6 +210,9 @@ Tests Documentation ------------- +- Issue #18440: Clarify that `hash()` can truncate the value returned from an + object's custom `__hash__()` method. + - Issue #17953: Mention that you shouldn't replace sys.modules and deleting key items will cause Python to not be happy.