This document is for an old version of Python that is no longer supported. You should upgrade and read the Python 当前稳定版本的文档.

# 9.8. `functools` — 高阶函数和可调用对象上的操作

2.5 新版功能.

源代码: Lib/functools.py

`functools` 模块应用于高阶函数，即——参数或（和）返回值为其他函数的函数。通常来说，此模块的功能适用于所有可调用对象。

`functools` 模块定义了以下函数:

`functools.``cmp_to_key`(func)

  Transform an old-style comparison function to a key function. Used with tools that accept key functions (such as `sorted()`, `min()`, `max()`, `heapq.nlargest()`, `heapq.nsmallest()`, `itertools.groupby()`). This function is primarily used as a transition tool for programs being converted to Python 3 where comparison functions are no longer supported.

  比较函数意为一个可调用对象，该对象接受两个参数并比较它们，结果为小于则返回一个负数，相等则返回零，大于则返回一个正数。key function则是一个接受一个参数，并返回另一个用以排序的值的可调用对象。

  示例:

      sorted(iterable, key=cmp_to_key(locale.strcoll))  # locale-aware sort order

  有关排序示例和简要排序教程，请参阅 排序指南 。

  2.7 新版功能.

`functools.``total_ordering`(cls)

  给定一个声明一个或多个全比较排序方法的类，这个类装饰器实现剩余的方法。这减轻了指定所有可能的全比较操作的工作。

  此类必须包含以下方法之一：`__lt__()` 、`__le__()`、`__gt__()` 或 `__ge__()`。另外，此类必须支持 `__eq__()` 方法。

  例如

      @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()))

  2.7 新版功能.

`functools.``reduce`(function, iterable[, initializer])

  This is the same function as `reduce()`. It is made available in this module to allow writing code more forward-compatible with Python 3.

  2.6 新版功能.

`functools.``partial`(func[,*args][, **keywords])

  返回一个新的 部分对象，当被调用时其行为类似于 func 附带位置参数 args 和关键字参数 keywords 被调用。 如果为调用提供了更多的参数，它们会被附加到 args。 如果提供了额外的关键字参数，它们会扩展并重载 keywords。 大致等价于:

      def partial(func, *args, **keywords):
          def newfunc(*fargs, **fkeywords):
              newkeywords = keywords.copy()
              newkeywords.update(fkeywords)
              return func(*(args + fargs), **newkeywords)
          newfunc.func = func
          newfunc.args = args
          newfunc.keywords = keywords
          return newfunc

  `partial()` 会被“冻结了”一部分函数参数和/或关键字的部分函数应用所使用，从而得到一个具有简化签名的新对象。 例如，`partial()` 可用来创建一个行为类似于 `int()` 函数的可调用对象，其中 base 参数默认为二：

      >>> from functools import partial
      >>> basetwo = partial(int, base=2)
      >>> basetwo.__doc__ = 'Convert base 2 string to an int.'
      >>> basetwo('10010')
      18

`functools.``update_wrapper`(wrapper, wrapped[, assigned][, updated])

  Update a wrapper function to look like the wrapped function. The optional arguments are tuples to specify which attributes of the original function are assigned directly to the matching attributes on the wrapper function and which attributes of the wrapper function are updated with the corresponding attributes from the original function. The default values for these arguments are the module level constants WRAPPER_ASSIGNMENTS (which assigns to the wrapper function’s __name__, __module__ and __doc__, the documentation string) and WRAPPER_UPDATES (which updates the wrapper function’s __dict__, i.e. the instance dictionary).

  此函数的主要目的是在 decorator 函数中用来包装被装饰的函数并返回包装器。 如果包装器函数未被更新，则被返回函数的元数据将反映包装器定义而不是原始函数定义，这通常没有什么用处。

`functools.``wraps`(wrapped[, assigned][, updated])

  这是一个便捷函数，用于在定义包装器函数时发起调用 `update_wrapper()` 作为函数装饰器。 它等价于 `partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated)`。 例如:

      >>> from functools import wraps
      >>> def my_decorator(f):
      ...     @wraps(f)
      ...     def wrapper(*args, **kwds):
      ...         print 'Calling decorated function'
      ...         return f(*args, **kwds)
      ...     return wrapper
      ...
      >>> @my_decorator
      ... def example():
      ...     """Docstring"""
      ...     print 'Called example function'
      ...
      >>> example()
      Calling decorated function
      Called example function
      >>> example.__name__
      'example'
      >>> example.__doc__
      'Docstring'

  如果不使用这个装饰器工厂函数，则 example 函数的名称将变为 `'wrapper'`，并且 `example()` 原本的文档字符串将会丢失。

## 9.8.1. `partial` 对象

`partial` 对象是由 `partial()` 创建的可调用对象。 它们具有三个只读属性：

`partial.``func`

  一个可调用对象或函数。 对 `partial` 对象的调用将被转发给 `func` 并附带新的参数和关键字。

`partial.``args`

  最左边的位置参数将放置在提供给 `partial` 对象调用的位置参数之前。

`partial.``keywords`

  当调用 `partial` 对象时将要提供的关键字参数。

`partial` 对象与 `function` 对象的类似之处在于它们都是可调用、可弱引用的对象并可拥有属性。 但两者也存在一些重要的区别。 例如前者不会自动创建 `__name__` 和 `__doc__` 属性。 而且，在类中定义的 `partial` 对象的行为类似于静态方法，并且不会在实例属性查找期间转换为绑定方法。