functools 函数工具

是什么，为什么存在

functools 是 Python 标准库中面向高阶函数（ higher-order function ）和可调用对象的模块。高阶函数接收函数、返回函数，或者两者兼有；模块中的工具也适用于实现了调用协议的其他对象。

这组工具解决的是接口之间的小型结构差异。某个回调槽只接受一个实参，而现有函数还需要类别；装饰器创建了新函数，但检查工具仍应看到原接口；旧代码提供二元比较函数，而 sorted() 需要键函数。functools 把这些适配规则做成可组合对象，不要求复制原函数逻辑。

本文集中讲五组彼此相关的适配器：partial() 与 partialmethod() 绑定实参，wraps() 与 update_wrapper() 维护包装器元数据，reduce() 累积输入，cmp_to_key() 转换比较协议，total_ordering 补齐富比较方法。cache、lru_cache 与 cached_property 属于缓存设计，singledispatch 属于运行时分派；它们分别放在相关主题中，避免在模块概览里重复一套不完整规则。

这些工具不会替你定义业务契约。partial() 不会验证被绑定的值，wraps() 不会证明包装器转发正确，reduce() 不会替空输入选择单位元，cmp_to_key() 也不会修复不一致的比较函数。先确定目标接口，再决定适配器，通常比从工具名称反推用途更可靠。

工具地图

工作原理

partial(func, *args, **keywords) 保存目标可调用对象与一组预填实参。调用所得对象时，新的位置实参接在已保存的位置实参之后；新的关键字与已保存关键字合并，且调用时的同名关键字优先。这个过程叫偏应用（ partial application ），它配置调用，不会提前执行 func。

Python 3.14 新增的 functools.Placeholder 可以在已保存的位置实参中预留任意位置。真正调用时，位置实参先从左到右填满所有占位符，其余位置实参再追加到末尾。占位符不能作为关键字值，而且每个占位符都必须被填充。

partialmethod() 解决相同配置出现在类定义中的情况。它是描述符而不是普通可调用对象；访问实例属性时，它先让底层函数完成方法绑定，再应用预填实参。若把普通 partial() 直接放进类体，self 的位置很容易与预填参数发生冲突。

update_wrapper(wrapper, wrapped) 把一组选定属性从被包装对象复制到包装对象，并更新另一组选定属性。默认会处理名称、限定名、文档、注解、类型形参和包装器的 __dict__，还会设置 __wrapped__。wraps(wrapped) 是适合写在包装函数上的便捷装饰器，本质上为 update_wrapper() 预填了参数。

reduce(function, iterable, initial) 从左到右调用二元函数。每一步都把上一次的累积值作为左实参，把下一个输入元素作为右实参；若提供 initial，它位于整条归约链最前面，也是空输入的结果。Python 3.14 允许把 initial 写成关键字，但本文的可运行示例用位置形式，以便在本地 Python 3.12 上核对输出。

排序工具处理两类不同接口。键函数每次接收一个元素并返回可比较的投影； 比较函数（comparator） 每次接收两个元素，并以负数、零、正数表示小于、等于、大于。cmp_to_key() 把后一种接口包装成前一种 API 可以接受的对象，主要用于迁移或接入已有比较协议。

参数适配的流程可以画成一条合并管道：

这张图只描述调用绑定。它没有缓存结果、复制可变对象或锁定预填关键字；这些行为都需要调用方另行实现和测试。

示例

四个示例依次展示函数配置、方法配置、元数据维护，以及归约与比较协议适配。每段输出都来自本地 python3 实际执行。

配置一个事件格式化函数

format_event() 保持通用，invoice_event 则符合只需订单号的调用点。预填关键字 compact=False 仍可在真正调用时覆盖。

func、args 与 keywords 让检查工具和调试代码看到偏函数保存的配置。业务代码仍应通过公开调用接口使用它，不要依赖修改这些诊断属性来动态重配行为。

调用方覆盖 compact 是明确的标准行为。如果该值必须固定，偏函数不是权限边界；应在不暴露该关键字的具名包装函数中强制规则，并为错误调用编写测试。

在类定义中配置方法

partialmethod() 让两个类属性复用同一个状态转换实现。底层函数仍按普通实例方法接收 self，预填的状态位于它之后。

from functools import partialmethod


class Ticket:
    def __init__(self, ticket_id):
        self.ticket_id = ticket_id
        self.state = "open"

    def transition(self, new_state, *, audit=True):
        self.state = new_state
        return f"{self.ticket_id}: {new_state}, audit={audit}"

    resolve = partialmethod(transition, "resolved")
    reopen = partialmethod(transition, "open")


ticket = Ticket(42)
print(ticket.resolve())
print(ticket.reopen(audit=False))
print(ticket.state)

42: resolved, audit=True
42: open, audit=False
open

resolve 与 reopen 仍表现为绑定方法。调用时可以覆盖预填关键字，但这里预填的是位置参数 new_state，额外再传一个位置状态会因为实参数量冲突而失败。

当每个便捷方法还要执行不同校验、授权或副作用时，直接写具名方法通常更清楚。partialmethod() 适合差异确实只有参数配置的情况，不适合隐藏逐渐分叉的业务流程。

保留装饰器的可检查接口

@wraps(func) 让包装后的名称、签名和 __wrapped__ 链指回原函数。包装器依然负责正确接收并转发实参。

from functools import wraps
from inspect import signature, unwrap


def require_role(required_role):
    def decorate(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            role = kwargs.pop("role")
            if role != required_role:
                raise PermissionError("role not allowed")
            return func(*args, **kwargs)

        return wrapper

    return decorate


@require_role("admin")
def close_ticket(ticket_id: int, *, reason: str) -> str:
    return f"closed {ticket_id}: {reason}"


print(close_ticket.__name__)
print(signature(close_ticket))
print(close_ticket(42, reason="duplicate", role="admin"))
print(unwrap(close_ticket)(7, reason="spam"))

close_ticket
(ticket_id: int, *, reason: str) -> str
closed 42: duplicate
closed 7: spam

inspect.signature() 默认沿 __wrapped__ 查看原接口，所以输出没有包装器自己消费的 role。这对透明装饰器很合适，但此示例实际扩展了调用协议；生产 API 应明确记录这项差异，或者把身份信息移到上下文而不是伪装成原签名的一部分。

unwrap() 会绕过包装层，因此不能作为授权后的普通调用路径。测试可用它核对原对象，框架和业务代码则应调用装饰后的公开名称。

归约记录并适配旧比较函数

reduce() 用显式初始值构造统计结果，cmp_to_key() 则把现有的三路比较函数交给 sorted()。两个适配器都保留原函数的职责边界。

from functools import cmp_to_key, reduce


def add_record(summary, record):
    kinds, total = summary
    return kinds | {record["kind"]}, total + record["cents"]


records = [
    {"kind": "sale", "cents": 2400},
    {"kind": "refund", "cents": -450},
]
kinds, total = reduce(add_record, records, (set(), 0))

priority_order = {"high": 0, "normal": 1}


def compare_ticket(left, right):
    left_key = priority_order[left["priority"]], left["id"]
    right_key = priority_order[right["priority"]], right["id"]
    return (left_key > right_key) - (left_key < right_key)


tickets = [
    {"id": 9, "priority": "normal"},
    {"id": 5, "priority": "high"},
    {"id": 2, "priority": "high"},
]
ordered = sorted(tickets, key=cmp_to_key(compare_ticket))

print(f"kinds: {', '.join(sorted(kinds))}")
print(f"total: {total}")
print("order:", ", ".join(str(ticket["id"]) for ticket in ordered))

kinds: refund, sale
total: 1950
order: 2, 5, 9

初始值 (set(), 0) 同时定义累积器形状和空输入结果。add_record() 每一步都返回新元组；它没有在调用方传入的容器上偷偷积累状态。

若比较规则可以直接表示为 priority_order[ticket["priority"]], ticket["id"]，直接写键函数更短。cmp_to_key() 的价值在于接入已经存在且经过测试的比较函数，而不是把本来简单的键逻辑改写成两两比较。

陷阱

把预填关键字当成不可覆盖配置

修复： 明确默认值与强制值的区别。默认值可以使用 partial()；强制值应由具名包装器在转发前拒绝冲突实参，或从调用接口中完全移除该选项。

在类体中用 partial() 代替 partialmethod()

修复： 类定义中的方法特化使用 partialmethod()，并通过实例测试所得属性。若绑定规则已经难以从签名读出，写一个普通方法，显式调用共享实现。

认为 wraps() 会修复包装器行为

修复： 把元数据检查与行为检查分开。对包装器测试原函数的各种参数形状、返回值、异常路径；装饰异步函数时，确保异步包装器在正确边界内执行 await。

省略 reduce() 的空输入契约

修复： 若运算存在真实单位元，显式传入它，并测试空输入。若空输入应是错误，提前给出领域化错误；若意图只是求和、全真、任一为真或连接序列，优先使用对应内置函数或清晰循环。

返回布尔值的比较函数

修复： 比较等价键，并返回 (left_key > right_key) - (left_key < right_key)，同时测试小于、相等和大于三种情况。能直接返回键时，省掉比较函数和适配层。

让相等与排序依据不同字段

修复： 让相等与排序从同一规范键导出，对不支持的类型返回 NotImplemented。用相同值、不同值和不相关类型验证所有比较关系，并在分析表明生成方法是热点时再考虑手写全部方法。

延伸阅读

• Python 3.14 functools 模块
• Python 3.14 partial() 与 Placeholder
• Python 3.14 wraps() 与 update_wrapper()
• Python 3.14 reduce()
• Python 排序指南：比较函数