Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
I hope the concept of hashability is better understandable now.
Thanks to Tim Hatch for pointing out the flaws here.
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index 24d4f69..9442d29 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -262,7 +262,7 @@
comparison is ``==`` or ``!=``. The latter cases return :const:`False` or
:const:`True`, respectively.
-:class:`timedelta` objects are hashable (usable as dictionary keys), support
+:class:`timedelta` objects are :term:`hashable` (usable as dictionary keys), support
efficient pickling, and in Boolean contexts, a :class:`timedelta` object is
considered to be true if and only if it isn't equal to ``timedelta(0)``.
diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst
index 4da3be9..baea5d4 100644
--- a/Doc/library/difflib.rst
+++ b/Doc/library/difflib.rst
@@ -20,7 +20,7 @@
.. class:: SequenceMatcher
This is a flexible class for comparing pairs of sequences of any type, so long
- as the sequence elements are hashable. The basic algorithm predates, and is a
+ as the sequence elements are :term:`hashable`. The basic algorithm predates, and is a
little fancier than, an algorithm published in the late 1980's by Ratcliff and
Obershelp under the hyperbolic name "gestalt pattern matching." The idea is to
find the longest contiguous matching subsequence that contains no "junk"
@@ -313,7 +313,7 @@
on blanks or hard tabs.
The optional arguments *a* and *b* are sequences to be compared; both default to
- empty strings. The elements of both sequences must be hashable.
+ empty strings. The elements of both sequences must be :term:`hashable`.
:class:`SequenceMatcher` objects have the following methods:
diff --git a/Doc/library/random.rst b/Doc/library/random.rst
index 02adf7a..e19d07e 100644
--- a/Doc/library/random.rst
+++ b/Doc/library/random.rst
@@ -60,7 +60,7 @@
.. function:: seed([x])
Initialize the basic random number generator. Optional argument *x* can be any
- hashable object. If *x* is omitted or ``None``, current system time is used;
+ :term:`hashable` object. If *x* is omitted or ``None``, current system time is used;
current system time is also used to initialize the generator when the module is
first imported. If randomness sources are provided by the operating system,
they are used instead of the system time (see the :func:`os.urandom` function
@@ -165,7 +165,7 @@
(the sample) to be partitioned into grand prize and second place winners (the
subslices).
- Members of the population need not be hashable or unique. If the population
+ Members of the population need not be :term:`hashable` or unique. If the population
contains repeats, then each occurrence is a possible selection in the sample.
To choose a sample from a range of integers, use an :func:`xrange` object as an
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 046d494..a74758b 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1419,7 +1419,7 @@
.. index:: object: set
-A :dfn:`set` object is an unordered collection of distinct hashable objects.
+A :dfn:`set` object is an unordered collection of distinct :term:`hashable` objects.
Common uses include membership testing, removing duplicates from a sequence, and
computing mathematical operations such as intersection, union, difference, and
symmetric difference.
@@ -1438,7 +1438,7 @@
The :class:`set` type is mutable --- the contents can be changed using methods
like :meth:`add` and :meth:`remove`. Since it is mutable, it has no hash value
and cannot be used as either a dictionary key or as an element of another set.
-The :class:`frozenset` type is immutable and hashable --- its contents cannot be
+The :class:`frozenset` type is immutable and :term:`hashable` --- its contents cannot be
altered after it is created; it can therefore be used as a dictionary key or as
an element of another set.
@@ -1538,8 +1538,7 @@
Since sets only define partial ordering (subset relationships), the output of
the :meth:`list.sort` method is undefined for lists of sets.
-Set elements are like dictionary keys; they need to define both :meth:`__hash__`
-and :meth:`__eq__` methods.
+Set elements, like dictionary keys, must be :term:`hashable`.
Binary operations that mix :class:`set` instances with :class:`frozenset` return
the type of the first operand. For example: ``frozenset('ab') | set('bc')``
@@ -1619,21 +1618,20 @@
statement: del
builtin: len
-A :dfn:`mapping` object maps immutable values to arbitrary objects. Mappings
-are mutable objects. There is currently only one standard mapping type, the
-:dfn:`dictionary`.
-(For other containers see the built in :class:`list`,
-:class:`set`, and :class:`tuple` classes, and the :mod:`collections`
-module.)
+A :dfn:`mapping` object maps :term:`hashable` values to arbitrary objects.
+Mappings are mutable objects. There is currently only one standard mapping
+type, the :dfn:`dictionary`. (For other containers see the built in
+:class:`list`, :class:`set`, and :class:`tuple` classes, and the
+:mod:`collections` module.)
-A dictionary's keys are *almost* arbitrary values. Only
-values containing lists, dictionaries or other mutable types (that are compared
-by value rather than by object identity) may not be used as keys. Numeric types
-used for keys obey the normal rules for numeric comparison: if two numbers
-compare equal (such as ``1`` and ``1.0``) then they can be used interchangeably
-to index the same dictionary entry. (Note however, that since computers
-store floating-point numbers as approximations it is usually unwise to
-use them as dictionary keys.)
+A dictionary's keys are *almost* arbitrary values. Values that are not
+:term:`hashable`, that is, values containing lists, dictionaries or other
+mutable types (that are compared by value rather than by object identity) may
+not be used as keys. Numeric types used for keys obey the normal rules for
+numeric comparison: if two numbers compare equal (such as ``1`` and ``1.0``)
+then they can be used interchangeably to index the same dictionary entry. (Note
+however, that since computers store floating-point numbers as approximations it
+is usually unwise to use them as dictionary keys.)
Dictionaries can be created by placing a comma-separated list of ``key: value``
pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst
index 21007d9..225991a 100644
--- a/Doc/library/weakref.rst
+++ b/Doc/library/weakref.rst
@@ -87,7 +87,7 @@
but cannot be propagated; they are handled in exactly the same way as exceptions
raised from an object's :meth:`__del__` method.
- Weak references are hashable if the *object* is hashable. They will maintain
+ Weak references are :term:`hashable` if the *object* is hashable. They will maintain
their hash value even after the *object* was deleted. If :func:`hash` is called
the first time only after the *object* was deleted, the call will raise
:exc:`TypeError`.
@@ -108,7 +108,7 @@
the proxy in most contexts instead of requiring the explicit dereferencing used
with weak reference objects. The returned object will have a type of either
``ProxyType`` or ``CallableProxyType``, depending on whether *object* is
- callable. Proxy objects are not hashable regardless of the referent; this
+ callable. Proxy objects are not :term:`hashable` regardless of the referent; this
avoids a number of problems related to their fundamentally mutable nature, and
prevent their use as dictionary keys. *callback* is the same as the parameter
of the same name to the :func:`ref` function.