[Python-checkins] cpython (merge 3.3 -> default): - Issue #18440: Clarify that `hash()` can truncate the value returned from an

[barry.warsaw]

http://hg.python.org/cpython/rev/f01f0c9cbcc8
changeset:   84638:f01f0c9cbcc8
parent:      84634:ccbaf6762b54
parent:      84637:8fe13940b033
user:        Barry Warsaw <barry at python.org>
date:        Mon Jul 15 15:21:41 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
@@ -587,11 +587,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
@@ -581,6 +581,9 @@
 Documentation
 -------------
 
+- Issue #18440: Clarify that `hash()` can truncate the value returned from an
+  object's custom `__hash__()` method.
+
 - Issue #17844: Add links to encoders and decoders for bytes-to-bytes codecs.
 
 - Issue #14097: improve the "introduction" page of the tutorial.

-- 
Repository URL: http://hg.python.org/cpython