Add a narrative chapter on object hashing

docs/hashing.rst

@@ -4,7 +4,10 @@ Hashing
 .. warning::
 
  The overarching theme is to never set the ``@attr.s(hash=X)`` parameter yourself.
- Leave it at ``None`` which means that ``attrs`` will do the right thing for you, depending on the other parameters.
+ Leave it at ``None`` which means that ``attrs`` will do the right thing for you, depending on the other parameters:
+
+ - If you want to make objects hashable by value: use ``@attr.s(frozen=True)``.
+ - If you want hashing and comparison by object identity: use ``@attr.s(cmp=False)``
 
  Setting ``hash`` yourself can have unexpected consequences so we recommend to tinker with it only if you know exactly what you're doing.
 
@@ -15,15 +18,10 @@ The *hash* of an object is an integer that represents the contents of an object.
 It can be obtained by calling :func:`hash` on an object and is implemented by writing a ``__hash__`` method for your class.
 
 ``attrs`` will happily write a ``__hash__`` method you [#fn1]_, however it will *not* do so by default.
-Because according to the definition_ from the official Python docs, the returned hash has to fullfill two constraints:
-
-#. The hash of an object *must not* change.
- This is the reason why mutable structures like lists, dictionaries, or sets aren't hashable while immutable ones like tuples or frozensets are.
+Because according to the definition_ from the official Python docs, the returned hash has to fullfill certrain constraints:
 
- If you create a class with ``@attr.s(frozen=True)`` this is fullfilled by definition therefore ``attrs`` will write a ``__hash__`` function for you automatically.
- You can also force it to write one with ``hash=True`` but then it's *your* responsibility to make sure that the object is not mutated.
-
-#. Two objects that are equal, must have the same hash. This means that if ``x == y``, it *must* follow that ``hash(x) == hash(y)``.
+#. Two objects that are equal, **must** have the same hash.
+ This means that if ``x == y``, it *must* follow that ``hash(x) == hash(y)``.
 
  By default, Python classes are compared *and* hashed by their :func:`id`.
  That means that every instance of a class has a different hash, no matter what attributes it carries.
@@ -36,6 +34,18 @@ Because according to the definition_ from the official Python docs, the returned
  The *correct way* to achieve hashing by id is to set ``@attr.s(cmp=False)``.
  Setting ``@attr.s(hash=False)`` (that implies ``cmp=True``) is almost certainly a *bug*.
 
+#. If two object are not equal, their hash **should** be different.
+
+ While this isn't a requirement from a standpoint of correctness, sets and dicts become less effective if there are a lot of identical hashes.
+ The worst case is when all objects have the same hash which turns a set into a list.
+
+#. The hash of an object **must not** change.
+
+ If you create a class with ``@attr.s(frozen=True)`` this is fullfilled by definition, therefore ``attrs`` will write a ``__hash__`` function for you automatically.
+ You can also force it to write one with ``hash=True`` but then it's *your* responsibility to make sure that the object is not mutated.
+
+ This point is the reason why mutable structures like lists, dictionaries, or sets aren't hashable while immutable ones like tuples or frozensets are:
+ point 1 and 2 require that the hash changes with the contents but point 3 forbids it.
 
 For a more thorough explanation of this topic, please refer to this blog post: `Python Hashes and Equality`_.
 

docs/index.rst

@@ -37,7 +37,7 @@ Day-to-Day Usage
 
 - Once you're comfortable with the concepts, our :doc:`api` contains all information you need to use ``attrs`` to its fullest.
 - If you want to put objects into sets or use them as keys in dictionaries, they have to be hashable.
- Unfortunately the topic is more complex than it seems but :doc:`hashing` will give you a primer on what to look out for.
+ The simplest way to do that is to use frozen classes, but the topic is more complex than it seems and :doc:`hashing` will give you a primer on what to look out for.
 - ``attrs`` is built for extension from the ground up.
  :doc:`extending` will show you the affordances it offers and how to make it a building block of your own projects.