diff options
Diffstat (limited to 'Doc/library/functools.rst')
-rw-r--r-- | Doc/library/functools.rst | 48 |
1 files changed, 48 insertions, 0 deletions
diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index a09d3cf725..787c000951 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -15,8 +15,56 @@ The :mod:`functools` module is for higher-order functions: functions that act on or return other functions. In general, any callable object can be treated as a function for the purposes of this module. +.. seealso:: + + Latest version of the `functools Python source code + <http://svn.python.org/view/python/branches/release27-maint/Lib/functools.py?view=markup>`_ + 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 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=cmp_to_key(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 + class decorator supplies the rest. This simplifies 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:: 2.7 .. function:: reduce(function, iterable[, initializer]) |