Forward port total_ordering() and cmp_to_key().
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index b85eb71..f371ffe 100644
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1014,9 +1014,8 @@
*reverse* is a boolean value. If set to ``True``, then the list elements are
sorted as if each comparison were reversed.
- To convert an old-style *cmp* function to a *key* function, see the
- `CmpToKey recipe in the ASPN cookbook
- <http://code.activestate.com/recipes/576653/>`_\.
+ Use :func:`functools.cmp_to_key` to convert an
+ old-style *cmp* function to a *key* function.
For sorting examples and a brief sorting tutorial, see `Sorting HowTo
<http://wiki.python.org/moin/HowTo/Sorting/>`_\.
diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index 94be636..1511a25 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -15,6 +15,51 @@
The :mod:`functools` module defines the following functions:
+.. function:: cmp_to_key(func)
+
+ Transform an old-style comparison function to a key-function. Used with
+ tools that accept key functions (such as :func:`sorted`, :func:`min`,
+ :func:`max`, :func:`heapq.nlargest`, :func:`heapq.nsmallest`,
+ :func:`itertools.groupby`).
+ This function is primarily used as a transition tool for programs
+ being converted from Py2.x which supported the use of comparison
+ functions.
+
+ A compare function is any callable that accept two arguments, compares
+ them, and returns a negative number for less-than, zero for equality,
+ or a positive number for greater-than. A key function is a callable
+ that accepts one argument and returns another value that indicates
+ the position in the desired collation sequence.
+
+ Example::
+
+ sorted(iterable, key=cmp_to_key(locale.strcoll)) # locale-aware sort order
+
+ .. versionadded:: 3.2
+
+.. function:: total_ordering(cls)
+
+ Given a class defining one or more rich comparison ordering methods, this
+ class decorator supplies the rest. This simplies the effort involved
+ in specifying all of the possible rich comparison operations:
+
+ The class must define one of :meth:`__lt__`, :meth:`__le__`,
+ :meth:`__gt__`, or :meth:`__ge__`.
+ In addition, the class should supply an :meth:`__eq__` method.
+
+ For example::
+
+ @total_ordering
+ class Student:
+ def __eq__(self, other):
+ return ((self.lastname.lower(), self.firstname.lower()) ==
+ (other.lastname.lower(), other.firstname.lower()))
+ def __lt__(self, other):
+ return ((self.lastname.lower(), self.firstname.lower()) <
+ (other.lastname.lower(), other.firstname.lower()))
+
+ .. versionadded:: 3.2
+
.. function:: partial(func, *args, **keywords)
Return a new :class:`partial` object which when called will behave like *func*
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 586fc8f..70eeca3 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1567,6 +1567,9 @@
*key* specifies a function of one argument that is used to extract a comparison
key from each list element: ``key=str.lower``. The default value is ``None``.
+ Use :func:`functools.cmp_to_key` to convert an
+ old-style *cmp* function to a *key* function.
+
*reverse* is a boolean value. If set to ``True``, then the list elements are
sorted as if each comparison were reversed.