From ccae479e2de19a042a75a1c1e1cdca7453de86f6 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Sun, 9 Nov 2014 17:10:17 -0800 Subject: [PATCH] Issue 22830: Clarify docs for functools.cmp_to_key(). --- Doc/library/functools.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 9336f799f7..086b0b5d1b 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -22,8 +22,8 @@ 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`, + Transform an old-style comparison function to a :term:`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 Python 3 where comparison functions are @@ -32,13 +32,16 @@ The :mod:`functools` module defines the following functions: A comparison 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. + argument and returns another value to be used as the sort key. Example:: sorted(iterable, key=cmp_to_key(locale.strcoll)) # locale-aware sort order + For sorting examples and a brief sorting tutorial, see `Sorting HowTo + `_\. + + .. versionadded:: 2.7 .. function:: total_ordering(cls) -- 2.50.1