Add functools.CmpToKey()

1 files changed, 22 insertions, 0 deletions

diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index 6dc9f0a..3337ead 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -17,6 +17,28 @@ function for the purposes of this module.
 
 The :mod:`functools` module defines the following functions:
 
+..  function:: CmpToKey(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 to Py3.x where comparison functions are no longer
+    supported.
+
+    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=CmpToKey(locale.strcoll))  # locale-aware sort order
+
+   .. versionadded:: 2.7
+
 .. function:: total_ordering(cls)
 
    Given a class defining one or more rich comparison ordering methods, this