如何在Python类中实现单分派方法@singledispatchmethod？

@singledispatchmethod不能直接用于普通的实例方法，因为它只根据第一个非self参数的运行类型进行分配；如果参数位置错误或方法在类别中没有正确定义，则不会触发注册分支，导致默认实现。

因为 @singledispatchmethod 第一个只作用于方法的**非 self 参数**，本质上是以参数类型为分配依据。如果你把它写成 def process(self, data):，那 self 它是第一个参数，但它的类型（类本身）总是固定的，根本无法“分配”。因此，我们必须把多态参数放在首位（self 之后)，否则注册类型分支不会触发。

常见的错误：singledispatchmethod 注册了 int 和 str 但调用时总是采用默认方法 —— 很可能是参数顺序错了，或者没有添加 self 装饰装置绑定失败。

• 必须在类别内部定义，方法签名形式如 def method(self, arg)，arg 是分配目标
• 装饰器只能添加到未绑定的装饰器中 self 实例法；不能添加到实例法中； @staticmethod 或 @classmethod 上
• 再次绑定类外定义(如赋值给类属性)会失效 —— @singledispatchmethod 依赖 Python 只有在类体中声明描述符协议，才能正确初始化

每种类型的分支必须通过 .register() 显式注册，而不是重复添加相同的方法名称 @singledispatchmethod。后者将覆盖前者，只保留最后一次注册。

from functools import singledispatchmethod
<p>class Processor:
@singledispatchmethod
def handle(self, data):
raise NotImplementedError(f"Cannot handle {type(data)}")</p><pre class="brush:php;toolbar:false;">@handle.register
def _(self, data: int):
    return f"Handling int: {data * 2}"

@handle.register
def _(self, data: str):
    return f"Handling str: {data.upper()}"

@handle.register
def _(self, data: list):
    return f"Handling list: {len(data)} items"

立即学习“Python免费学习笔记(深入)；

注：注册函数名用 _ 是惯例，不是必须的；但是名字不重要，关键在于 @handle.register 这个调用链。如果错过了。 @handle.register，函数只是一种普通的方法，不会参与分配。

Python 3.14.2

Python 3.14.2是2025年12月5日发布的Python编程语言的稳定版本，属于3.14系列的第二次维护更新。该版本包含18个修复项目，重点解决模块的回归问题，如多进程、数据和正则表达式，并修复CVE-2025-12084等安全漏洞。这个版本标志着Python发展的重要里程碑——免费线程模式(GIL除外)正式得到官方支持。

• @handle.register 具体类型(如 int），也可以注释传输类型(如 data: float），两者等效
• 注册顺序无关，运行时根据实际参数类型匹配最具体的(支持继承:传递 Child 实例会优先匹配 @register(Child)，其次 @register(Parent)）
• 不能用 Union 或 Optional 注册 —— 比如 @handle.register(int | str) 会议报错时，必须拆开单独注册

这个错误通常发生在你试图把它放在一边 @singledispatchmethod 在不支持的上下文中使用，如：Python 版本低于 3.8(装饰器 3.8 引入）、或方法意外包裹(例如设置了自定义装饰器，但没有正确处理描述符)。

• 确认 Python ≥ 3.8：import sys; print(sys.version)
• 避免在 @singledispatchmethod 外层覆盖其他装饰(尤其是那些没有实现的) __get__ 的）；必要时，把 @singledispatchmethod 放最内层
• 别在 __init__ 或 __new__ 里用 —— 它们不是传统的方法，分配逻辑也不适用
• 如果类继承来自某个框架基类(如某些) ORM 模型)，检查基类是否重写 __getattribute__ 对描述符行为的干扰

当您需要访问实例状态时，当您需要访问实例状态时（self.xxx）时，只能选 @singledispatchmethod。全局 @singledispatch 是函数，没有 self，无法读写实例属性或调用其他实例方法。

例如，您必须根据输入类型来决定如何序列化对象，但序列化逻辑取决于当前的实例 self.format_style 配置 —— 在这种情况下，硬塞必须插入全局函数 self 当参数传输破坏包装时，也容易泄漏。

• @singledispatchmethod 分配表是**各类实例独立维护的**，不同类别不共享，适合包装行为差异
• 性能几乎没有差异，底层检查类型 MRO；但 @singledispatchmethod 属性搜索多一次（self.handle），可忽略
• 若方法完全不依赖实例状态，则采用全局 @singledispatch 单元测试更轻、更容易(不需要结构实例)

真正容易被忽视的是，分配只看运行时的类型，而不是静态注释；即使你写了 data: Any，只要是传进来的 dict，就会匹配到 @handle.register(dict) 分支 —— 这与类型检查器有关（mypy）行为是分离的。