]> granicus.if.org Git - python/commitdiff
doc: Suggest to hash(tuple of attr) rather than XOR
authorVictor Stinner <victor.stinner@gmail.com>
Mon, 19 Dec 2016 12:15:35 +0000 (13:15 +0100)
committerVictor Stinner <victor.stinner@gmail.com>
Mon, 19 Dec 2016 12:15:35 +0000 (13:15 +0100)
Issue #28383: __hash__ documentation recommends naive XOR to combine but this
is suboptimal. Update the doc to suggest to reuse the hash() method using a
tuple, with an example.

Doc/reference/datamodel.rst

index db2fa1762e5cda72c5b4a3ef83e5129cb39f33e1..4adf5fa59fdf9811416ec892137dda6a5a526cb1 100644 (file)
@@ -1409,8 +1409,12 @@ Basic customization
    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.
+   advised to mix together the hash values of the components of the object that
+   also play a part in comparison of objects by packing them into a tuple and
+   hashing the tuple. Example::
+
+       def __hash__(self):
+           return hash((self.name, self.nick, self.color))
 
    If a class does not define a :meth:`__cmp__` or :meth:`__eq__` method it
    should not define a :meth:`__hash__` operation either; if it defines