Python functools.Placeholder 怎样组合非首位参数

如果一个函数的参数是 prefix, name, suffix，但业务只想提前固定 prefix 和 suffix，普通的 functools.partial 不够用：它默认从位置参数左侧开始冻结。Python 3.14 新增的 functools.Placeholder 正是为这个场景准备的，可以把中间位置留给调用者。

先记结论：用 Placeholder 标记需要延后填写的位置，调用时按位置传入值；所有占位符都必须被填满，不能把 Placeholder 当关键字参数传入。

官方文档：https://docs.python.org/3.14/library/functools.html

先看现象：为什么普通 partial 只能固定前面的参数

先把问题缩小到一个三参数函数。我们想复用同一个格式化函数，只提前确定前缀和后缀，让每次调用只提供中间的名称。

from functools import partial


def label(prefix, name, suffix):
    # 把三个位置参数拼成一条可读标签。
    return f"{prefix}{name}{suffix}"


# 普通 partial 会从左侧开始固定位置参数。
with_prefix = partial(label, "用户：")
print(with_prefix("小林", "（已登记）"))

# 如果先传后缀，它会占据 name，而不是 suffix。
with_suffix = partial(label, "用户：", "（已登记）")
print(with_suffix("小林"))

第二个包装器并没有表达“固定 suffix”。它实际把两个字符串依次放进 prefix 和 name，所以最后一次调用传入的“小林”才会落到 suffix。这就是普通 partial 的位置限制：可以固定开头的一段位置参数，却不能直接跳过中间位置。

用 Placeholder 预留非首位位置

Python 3.14 可以从 functools 导入 Placeholder。它是一个哨兵对象，不是业务值；放在 partial 的位置参数中，就代表这个位置要等调用时再填。

from functools import Placeholder as _, partial


def label(prefix, name, suffix):
    # 让 name 由调用方决定，prefix 和 suffix 由包装器提供。
    return f"{prefix}{name}{suffix}"


# 下划线只是本地别名；它指向 functools.Placeholder。
label_user = partial(label, "用户：", _, "（已登记）")

# 调用时提供的第一个位置参数会填入 Placeholder。
print(label_user("小林"))

这里的参数槽位关系是：prefix 固定为“用户：”，name 暂时由占位符保留，suffix 固定为“（已登记）”。调用 label_user("小林") 时，小林被放入 name，因此包装函数同时满足了“固定首尾、延迟中间值”。

嵌套 partial 怎样保留占位符

占位符的价值不只在一次包装。对已经含有占位符的 partial 再包装时，新的位置参数会优先填充旧占位符；如果希望某个位置继续空着，可以在同一位置再次放入 Placeholder。

from functools import Placeholder as _, partial


# str.replace(text, old, new) 的 text 和 old 都延后提供。
remove = partial(str.replace, _, _, "")

# 第一个参数填入 text，第二个参数填入 old。
remove_dear = partial(remove, _, " dear")
message = "Hello, dear dear world!"

# 新的 Placeholder 让 text 继续保留为空位，old 则已经固定。
print(remove_dear(message))

# 再固定次数时，仍然只把参数放到正文已经定义的位置。
remove_first_dear = partial(remove_dear, _, 1)
print(remove_first_dear(message))

这个例子要抓住两点。第一，内层 partial 的 " dear" 会填入旧的第二个占位符；第二，新的 _ 不是装饰，而是明确告诉 partial“这个槽位仍然留给下一次调用”。因此嵌套包装可以逐层收窄参数，但要把每个槽位的含义写清楚。

三个容易踩坑的调用边界

占位符没有全部填满会怎样

如果包装器里有两个 Placeholder，调用时只提供一个位置参数，调用就不完整，会抛出 TypeError。这不是默认值机制，也不会自动把缺失位置变成 None。

from functools import Placeholder as _, partial


def pair(left, right):
    # 两个位置都必须得到实际值，函数才有完整输入。
    return f"{left} / {right}"


make_pair = partial(pair, _, _)
# 这里故意只传一个值，用于说明未填完占位符的失败边界。
make_pair("左值")

Placeholder 不能放进关键字参数

Placeholder 只用于位置参数槽位。若业务参数本身是关键字参数，应直接用普通关键字固定或在函数内部显式处理，不要尝试写成 partial(func, name=Placeholder)。

旧 Python 版本不能直接导入

Placeholder 是 Python 3.14 新增能力。部署环境如果还是 Python 3.13 或更早版本，导入阶段就会失败。兼容旧版本时，优先保留一个普通函数包装器，或者调整函数签名把需要延迟的参数移到可由 partial 固定的后方；不要只在标题或依赖文件中写 3.14，却让运行时继续使用旧解释器。

partialmethod 放进类里怎么设计

partialmethod 适合把固定调用方式声明成类的方法。它和 partial 共享占位符语义，同时保留描述器对实例 self 的绑定。

from functools import Placeholder as _, partialmethod


class EventFormatter:
    def format_event(self, level, event, suffix):
        # self 由实例绑定，三个业务位置参数仍按方法定义排列。
        return f"{level}:{event}{suffix}"

    # 预留 event，让实例方法只需要接收事件名。
    info = partialmethod(format_event, "INFO", _, "\n")


formatter = EventFormatter()
# 访问 formatter.info 时，self 仍然属于 formatter。
print(formatter.info("started"))

这里不要把 self 当成需要手动填的占位符。partialmethod 通过方法描述器完成实例绑定，Placeholder 只描述业务参数中的空位。若把普通函数先做成 partial 再随意赋给类属性，可能改变描述器行为，调试时应优先使用 partialmethod 表达意图。

上线前的排查与迁移清单

把下面几项放进代码评审或部署检查，就能快速判断这项迁移是否安全：

最终可以把文章中的示例改成项目自己的函数名，并为“全部填满”“少填一个”“旧版本导入”各留一个回归用例。这样测试关注的是参数槽位契约，而不是某次调用碰巧返回了字符串。

总结

普通 partial 适合固定开头参数；Python 3.14 的 Placeholder 把非首位位置变成可延迟填充的槽位。一次包装看填充顺序，嵌套包装看旧占位符是否被消费，类方法则把 partialmethod 与 self 绑定语义分开考虑。只要同时守住解释器版本、占位符数量和位置参数三条边界，就能把这项能力用在格式化器、适配器和方法快捷入口中。

相关问题

• Placeholder 和普通默认参数有什么区别？
• partial 嵌套后怎样确认参数填充顺序？
• Python 3.13 项目怎样兼容非首位参数预填？