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

functools 模块用于高阶函数：作用于或返回其他函数的函数。通常，对于此模块而言，任何可调用对象都可以视为函数。

functools 模块定义了以下函数

@functools.cache(user_function)¶

简单轻量级的无界函数缓存。有时称为 “记忆化”。

返回与 lru_cache(maxsize=None) 相同的结果，为函数参数创建一个围绕字典查找的精简包装器。因为它永远不需要驱逐旧值，所以它比具有大小限制的 lru_cache() 更小更快。

例如

@cache
def factorial(n):
    return n * factorial(n-1) if n else 1

>>> factorial(10)      # no previously cached result, makes 11 recursive calls
3628800
>>> factorial(5)       # just looks up cached value result
120
>>> factorial(12)      # makes two new recursive calls, the other 10 are cached
479001600

缓存是线程安全的，因此包装后的函数可以在多个线程中使用。这意味着底层数据结构在并发更新期间将保持一致。

如果另一个线程在初始调用完成并缓存之前进行了额外的调用，则包装后的函数可能会被调用多次。

3.9 版新增。

@functools.cached_property(func)¶

将类的方法转换为属性，该属性的值计算一次，然后在实例的生命周期内缓存为普通属性。类似于 property()，但增加了缓存功能。对于实例中计算成本高昂但实际上不可变的属性很有用。

例子

class DataSet:

    def __init__(self, sequence_of_numbers):
        self._data = tuple(sequence_of_numbers)

    @cached_property
    def stdev(self):
        return statistics.stdev(self._data)

cached_property() 的机制与 property() 有所不同。除非定义了 setter，否则常规属性会阻止属性写入。相反，cached_property 允许写入。

cached_property 装饰器仅在查找时运行，并且仅在不存在同名属性时运行。当它运行时，cached_property 会写入同名属性。后续的属性读写优先于 cached_property 方法，并且它的工作方式类似于普通属性。

可以通过删除属性来清除缓存的值。这允许 cached_property 方法再次运行。

cached_property 不能防止多线程使用中可能出现的竞争条件。getter 函数可能会在同一个实例上运行多次，最后一次运行设置缓存的值。如果缓存的属性是幂等的，或者在实例上运行多次没有危害，那么这样做是可以的。如果需要同步，请在装饰的 getter 函数内部或缓存的属性访问周围实现必要的锁定。

请注意，此装饰器会干扰 PEP 412 密钥共享字典的操作。这意味着实例字典可能比平时占用更多空间。

此外，此装饰器要求每个实例上的 __dict__ 属性是可变映射。这意味着它不适用于某些类型，例如元类（因为类型实例上的 __dict__ 属性是类命名空间的只读代理），以及那些指定 __slots__ 但不包括 __dict__ 作为已定义槽之一的类型（因为此类根本不提供 __dict__ 属性）。

如果不可用可变映射，或者希望实现节省空间的密钥共享，则可以通过将 property() 堆叠在 lru_cache() 之上来实现类似于 cached_property() 的效果。有关这与 cached_property() 有何不同的更多详细信息，请参阅如何缓存方法调用？。

3.8 版新增。

在 3.12 版更改: 在 Python 3.12 之前，cached_property 包含一个未记录的锁，以确保在多线程使用中，getter 函数保证每个实例只运行一次。但是，锁是按属性而不是按实例的，这可能会导致锁争用过高。在 Python 3.12+ 中，此锁定已被删除。

functools.cmp_to_key(func)¶

将旧式比较函数转换为键函数。与接受键函数的工具一起使用（例如 sorted()、min()、max()、heapq.nlargest()、heapq.nsmallest()、itertools.groupby()）。此函数主要用作从 Python 2 转换程序的过渡工具，Python 2 支持使用比较函数。

比较函数是任何接受两个参数、比较它们并返回负数表示小于、零表示相等或正数表示大于的可调用对象。键函数是接受一个参数并返回另一个值以用作排序键的可调用对象。

例子

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

有关排序示例和简短的排序教程，请参阅排序技术。

3.2 版新增。

@functools.lru_cache(user_function)¶

@functools.lru_cache(maxsize=128, typed=False)

装饰器，用于使用记忆可调用对象包装函数，该对象最多保存 maxsize 个最近的调用。当一个开销大或 I/O 密集型函数使用相同的参数定期调用时，它可以节省时间。

缓存是线程安全的，因此包装后的函数可以在多个线程中使用。这意味着底层数据结构在并发更新期间将保持一致。

如果另一个线程在初始调用完成并缓存之前进行了额外的调用，则包装后的函数可能会被调用多次。

由于使用字典缓存结果，因此函数的位置参数和关键字参数必须是可哈希的。

不同的参数模式可以被认为是具有单独缓存条目的不同调用。例如，f(a=1, b=2) 和 f(b=2, a=1) 的关键字参数顺序不同，并且可能有两个单独的缓存条目。

如果指定了 user_function，则它必须是可调用的。这允许将 lru_cache 装饰器直接应用于用户函数，并将 maxsize 保留为其默认值 128

@lru_cache
def count_vowels(sentence):
    return sum(sentence.count(vowel) for vowel in 'AEIOUaeiou')

如果将 maxsize 设置为 None，则禁用 LRU 功能，并且缓存可以无限增长。

如果将 typed 设置为 true，则不同类型的函数参数将分别缓存。如果 typed 为 false，则实现通常会将它们视为等效调用，并且只缓存一个结果。（某些类型，如 str 和 int，即使 typed 为 false，也可能分别缓存。）

请注意，类型特异性仅适用于函数的直接参数，而不适用于其内容。标量参数 Decimal(42) 和 Fraction(42) 被视为具有不同结果的不同调用。相反，元组参数 ('answer', Decimal(42)) 和 ('answer', Fraction(42)) 被视为等效。

包装函数配备了一个 cache_parameters() 函数，该函数返回一个新的 dict，显示 maxsize 和 typed 的值。这仅供参考。更改这些值没有任何效果。

为了帮助衡量缓存的有效性和调整 maxsize 参数，包装函数配备了一个 cache_info() 函数，该函数返回一个命名元组，显示 hits、misses、maxsize 和 currsize。

装饰器还提供了一个 cache_clear() 函数，用于清除或使缓存无效。

可以通过 __wrapped__ 属性访问原始的底层函数。这对于内省、绕过缓存或使用不同的缓存重新包装函数很有用。

缓存会保留对参数和返回值的引用，直到它们从缓存中过期或缓存被清除。

如果缓存了一个方法，则 self 实例参数将包含在缓存中。请参阅如何缓存方法调用？

LRU（最近最少使用）缓存在最近的调用最能预测即将到来的调用时效果最佳（例如，新闻服务器上最受欢迎的文章往往每天都在变化）。缓存的大小限制确保了缓存不会在长时间运行的进程（如 Web 服务器）上无限增长。

通常，LRU 缓存只应在您想要重用以前计算的值时使用。因此，缓存具有副作用的函数、需要在每次调用时创建不同的可变对象（如生成器和异步函数）的函数或不纯函数（如 time() 或 random()）是没有意义的。

静态 Web 内容的 LRU 缓存示例

@lru_cache(maxsize=32)
def get_pep(num):
    'Retrieve text of a Python Enhancement Proposal'
    resource = f'https://peps.pythonlang.cn/pep-{num:04d}'
    try:
        with urllib.request.urlopen(resource) as s:
            return s.read()
    except urllib.error.HTTPError:
        return 'Not Found'

>>> for n in 8, 290, 308, 320, 8, 218, 320, 279, 289, 320, 9991:
...     pep = get_pep(n)
...     print(n, len(pep))

>>> get_pep.cache_info()
CacheInfo(hits=3, misses=8, maxsize=32, currsize=8)

使用缓存实现动态规划技术来高效计算斐波那契数列的示例

@lru_cache(maxsize=None)
def fib(n):
    if n < 2:
        return n
    return fib(n-1) + fib(n-2)

>>> [fib(n) for n in range(16)]
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610]

>>> fib.cache_info()
CacheInfo(hits=28, misses=16, maxsize=None, currsize=16)

3.2 版新增。

3.3 版更改: 添加了 typed 选项。

3.8 版更改: 添加了 user_function 选项。

3.9 版更改: 添加了函数 cache_parameters()

@functools.total_ordering¶

给定一个定义了一个或多个丰富比较排序方法的类，此类装饰器将提供其余方法。这简化了指定所有可能的丰富比较操作所涉及的工作

该类必须定义 __lt__()、__le__()、__gt__() 或 __ge__() 中的一个。此外，该类还应提供 __eq__() 方法。

例如

@total_ordering
class Student:
    def _is_valid_operand(self, other):
        return (hasattr(other, "lastname") and
                hasattr(other, "firstname"))
    def __eq__(self, other):
        if not self._is_valid_operand(other):
            return NotImplemented
        return ((self.lastname.lower(), self.firstname.lower()) ==
                (other.lastname.lower(), other.firstname.lower()))
    def __lt__(self, other):
        if not self._is_valid_operand(other):
            return NotImplemented
        return ((self.lastname.lower(), self.firstname.lower()) <
                (other.lastname.lower(), other.firstname.lower()))

注意

虽然此装饰器可以轻松创建行为良好的完全有序类型，但它确实是以牺牲派生比较方法的执行速度较慢和堆栈跟踪更复杂为代价的。如果性能基准测试表明这是给定应用程序的瓶颈，则实现所有六种丰富比较方法可能会更容易提高速度。

注意

此装饰器不会尝试覆盖在类或其超类中声明的方法。这意味着如果超类定义了一个比较运算符，则即使原始方法是抽象的，total_ordering 也不会再次实现它。

3.2 版新增。

3.4 版更改: 现在支持从底层比较函数返回 NotImplemented 以用于无法识别的类型。

functools.partial(func, /, *args, **keywords)¶

返回一个新的 partial 对象，该对象在被调用时，其行为类似于使用位置参数 args 和关键字参数 keywords 调用 func。如果向调用提供了更多参数，则将它们附加到 args。如果提供了其他关键字参数，则它们将扩展和覆盖 keywords。大致等效于

def partial(func, /, *args, **keywords):
    def newfunc(*fargs, **fkeywords):
        newkeywords = {**keywords, **fkeywords}
        return func(*args, *fargs, **newkeywords)
    newfunc.func = func
    newfunc.args = args
    newfunc.keywords = keywords
    return newfunc

partial() 用于偏函数应用程序，它“冻结”函数的部分参数和/或关键字，从而生成一个具有简化签名的新的对象。例如，partial() 可用于创建一个行为类似于 int() 函数的可调用对象，其中 base 参数默认为 2。

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

class functools.partialmethod(func, /, *args, **keywords)¶

返回一个新的 partialmethod 描述符，其行为类似于 partial，但它被设计为用作方法定义，而不是直接可调用。

func 必须是一个描述符或一个可调用对象（同时满足这两个条件的对象，如普通函数，将被作为描述符处理）。

当 func 是一个描述符（例如一个普通的 Python 函数、classmethod()、staticmethod()、abstractmethod() 或另一个 partialmethod 的实例）时，对 __get__ 的调用将被委托给底层描述符，并返回一个适当的 partial 对象作为结果。

当 func 是一个非描述符可调用对象时，将动态创建一个适当的绑定方法。当用作方法时，它的行为类似于普通的 Python 函数：self 参数将作为第一个位置参数插入，甚至在提供给 partialmethod 构造函数的 args 和 keywords 之前。

例子

>>> class Cell:
...     def __init__(self):
...         self._alive = False
...     @property
...     def alive(self):
...         return self._alive
...     def set_state(self, state):
...         self._alive = bool(state)
...     set_alive = partialmethod(set_state, True)
...     set_dead = partialmethod(set_state, False)
...
>>> c = Cell()
>>> c.alive
False
>>> c.set_alive()
>>> c.alive
True

3.4 版新增。

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

将具有两个参数的 function 从左到右累积地应用于 iterable 的项，以便将可迭代对象简化为单个值。例如，reduce(lambda x, y: x+y, [1, 2, 3, 4, 5]) 计算 ((((1+2)+3)+4)+5)。左参数 x 是累加值，右参数 y 是来自 iterable 的更新值。如果存在可选的 initializer，则将其放置在计算中可迭代项的前面，并在可迭代对象为空时充当默认值。如果未给出 initializer 且 iterable 仅包含一项，则返回第一项。

大致相当于

def reduce(function, iterable, initializer=None):
    it = iter(iterable)
    if initializer is None:
        value = next(it)
    else:
        value = initializer
    for element in it:
        value = function(value, element)
    return value

有关生成所有中间值的迭代器，请参阅 itertools.accumulate()。

@functools.singledispatch¶

将函数转换为单分派泛型函数。

要定义泛型函数，请使用 @singledispatch 装饰器对其进行装饰。使用 @singledispatch 定义函数时，请注意，分派发生在第一个参数的类型上。

>>> from functools import singledispatch
>>> @singledispatch
... def fun(arg, verbose=False):
...     if verbose:
...         print("Let me just say,", end=" ")
...     print(arg)

要向函数添加重载实现，请使用泛型函数的 register() 属性，该属性可以用作装饰器。对于使用类型注释的函数，装饰器将自动推断第一个参数的类型。

>>> @fun.register
... def _(arg: int, verbose=False):
...     if verbose:
...         print("Strength in numbers, eh?", end=" ")
...     print(arg)
...
>>> @fun.register
... def _(arg: list, verbose=False):
...     if verbose:
...         print("Enumerate this:")
...     for i, elem in enumerate(arg):
...         print(i, elem)

也可以使用 types.UnionType 和 typing.Union。

>>> @fun.register
... def _(arg: int | float, verbose=False):
...     if verbose:
...         print("Strength in numbers, eh?", end=" ")
...     print(arg)
...
>>> from typing import Union
>>> @fun.register
... def _(arg: Union[list, set], verbose=False):
...     if verbose:
...         print("Enumerate this:")
...     for i, elem in enumerate(arg):
...         print(i, elem)
...

对于不使用类型注释的代码，可以将适当的类型参数显式传递给装饰器本身。

>>> @fun.register(complex)
... def _(arg, verbose=False):
...     if verbose:
...         print("Better than complicated.", end=" ")
...     print(arg.real, arg.imag)
...

为了能够注册 lambda 表达式和预先存在的函数，register() 属性也可以以函数形式使用。

>>> def nothing(arg, verbose=False):
...     print("Nothing.")
...
>>> fun.register(type(None), nothing)

register() 属性返回未装饰的函数。这使得装饰器堆叠、序列化 以及为每个变体独立创建单元测试成为可能。

>>> @fun.register(float)
... @fun.register(Decimal)
... def fun_num(arg, verbose=False):
...     if verbose:
...         print("Half of your number:", end=" ")
...     print(arg / 2)
...
>>> fun_num is fun
False

调用时，泛型函数会根据第一个参数的类型进行分派。

>>> fun("Hello, world.")
Hello, world.
>>> fun("test.", verbose=True)
Let me just say, test.
>>> fun(42, verbose=True)
Strength in numbers, eh? 42
>>> fun(['spam', 'spam', 'eggs', 'spam'], verbose=True)
Enumerate this:
0 spam
1 spam
2 eggs
3 spam
>>> fun(None)
Nothing.
>>> fun(1.23)
0.615

如果没有为特定类型注册实现，则使用其方法解析顺序来查找更通用的实现。使用 @singledispatch 装饰的原始函数将注册到基本 object 类型，这意味着如果没有找到更好的实现，则使用该函数。

如果将实现注册到抽象基类，则基类的虚拟子类将被分派到该实现。

>>> from collections.abc import Mapping
>>> @fun.register
... def _(arg: Mapping, verbose=False):
...     if verbose:
...         print("Keys & Values")
...     for key, value in arg.items():
...         print(key, "=>", value)
...
>>> fun({"a": "b"})
a => b

要检查泛型函数将为给定类型选择哪个实现，请使用 dispatch() 属性。

>>> fun.dispatch(float)
<function fun_num at 0x1035a2840>
>>> fun.dispatch(dict)    # note: default implementation
<function fun at 0x103fe0000>

要访问所有已注册的实现，请使用只读 registry 属性。

>>> fun.registry.keys()
dict_keys([<class 'NoneType'>, <class 'int'>, <class 'object'>,
          <class 'decimal.Decimal'>, <class 'list'>,
          <class 'float'>])
>>> fun.registry[float]
<function fun_num at 0x1035a2840>
>>> fun.registry[object]
<function fun at 0x103fe0000>

3.4 版新增。

在 3.7 版更改: register() 属性现在支持使用类型注释。

在 3.11 版更改: register() 属性现在支持 types.UnionType 和 typing.Union 作为类型注释。

class functools.singledispatchmethod(func)¶

将方法转换为单分派泛型函数。

要定义泛型方法，请使用 @singledispatchmethod 装饰器对其进行装饰。使用 @singledispatchmethod 定义函数时，请注意，分派发生在第一个非 self 或非 cls 参数的类型上。

class Negator:
    @singledispatchmethod
    def neg(self, arg):
        raise NotImplementedError("Cannot negate a")

    @neg.register
    def _(self, arg: int):
        return -arg

    @neg.register
    def _(self, arg: bool):
        return not arg

@singledispatchmethod 支持与其他装饰器（如 @classmethod）嵌套。请注意，为了允许 dispatcher.register，singledispatchmethod 必须是 最外层 的装饰器。以下是 Negator 类，其中 neg 方法绑定到类而不是类的实例。

class Negator:
    @singledispatchmethod
    @classmethod
    def neg(cls, arg):
        raise NotImplementedError("Cannot negate a")

    @neg.register
    @classmethod
    def _(cls, arg: int):
        return -arg

    @neg.register
    @classmethod
    def _(cls, arg: bool):
        return not arg

相同的模式可用于其他类似的装饰器：@staticmethod、@abstractmethod 等。

3.8 版新增。

functools.update_wrapper(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)¶

更新 wrapper 函数，使其看起来像 wrapped 函数。可选参数是元组，用于指定原始函数的哪些属性直接分配给包装函数上的匹配属性，以及包装函数的哪些属性使用原始函数中的相应属性进行更新。这些参数的默认值是模块级常量 WRAPPER_ASSIGNMENTS（它分配给包装函数的 __module__、__name__、__qualname__、__annotations__、__type_params__ 和 __doc__，即文档字符串）和 WRAPPER_UPDATES（它更新包装函数的 __dict__，即实例字典）。

为了允许访问原始函数以进行内省和其他目的（例如，绕过缓存装饰器，如 lru_cache()），此函数会自动向包装器添加一个 __wrapped__ 属性，该属性引用被包装的函数。

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

update_wrapper() 可与函数以外的可调用对象一起使用。被包装对象中缺少的任何在 assigned 或 updated 中命名的属性都将被忽略（即，此函数不会尝试在包装函数上设置它们）。如果包装函数本身缺少 updated 中命名的任何属性，则仍会引发 AttributeError。

版本 3.2 中的变化：现在会自动添加 __wrapped__ 属性。现在默认情况下会复制 __annotations__ 属性。缺少属性不再触发 AttributeError。

版本 3.4 中的变化： __wrapped__ 属性现在始终引用被包装的函数，即使该函数定义了 __wrapped__ 属性。（参见 bpo-17482）

版本 3.12 中的变化：现在默认情况下会复制 __type_params__ 属性。

@functools.wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)¶

这是在定义包装函数时将 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'

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

`partial` 对象¶

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

partial.func¶: 可调用对象或函数。对 partial 对象的调用将使用新的参数和关键字转发给 func。

partial.args¶: 最左侧的位置参数，这些参数将添加到提供给 partial 对象调用的位置参数之前。

partial.keywords¶: 调用 partial 对象时将提供的关键字参数。

partial 对象类似于 function 对象，因为它们是可调用的、弱引用的，并且可以具有属性。但也有一些重要的区别。例如，不会自动创建 __name__ 和 __doc__ 属性。此外，在类中定义的 partial 对象的行为类似于静态方法，并且在实例属性查找期间不会转换为绑定方法。

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

`partial` 对象¶

目录

上一主题

下一主题

本页

functools — 高阶函数和可调用对象上的操作¶

partial 对象¶

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

`partial` 对象¶