[Python-checkins] cpython (3.3): - Issue #18440: Clarify that `hash()` can truncate the value returned from an
barry.warsaw
python-checkins at python.org
Mon Jul 15 21:22:36 CEST 2013
http://hg.python.org/cpython/rev/8fe13940b033
changeset: 84637:8fe13940b033
branch: 3.3
parent: 84632:6a6ca7c49c2a
user: Barry Warsaw <barry at python.org>
date: Mon Jul 15 14:47:29 2013 -0400
summary:
- Issue #18440: Clarify that `hash()` can truncate the value returned from an
object's custom `__hash__()` method.
files:
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
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -583,11 +583,16 @@
.. 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
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1264,10 +1264,21 @@
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
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -210,6 +210,9 @@
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.
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list