Python原生不支持方法重载，因运行时确定类型且无类型声明，同名方法定义会覆盖；singledispatch仅支持模块级函数，不适用实例方法；singledispatchmethod（3.8+）专为实例方法设计，按首参数类型分发。
为什么Python原生不支持方法重载
Python在运行时才确定对象类型，函数签名里没有类型声明，所以像def foo(x):和def foo(x: int):在解释器眼里是同一个名字、同一份覆盖逻辑。类中同名方法只会保留最后一个定义，不会像Java或C++那样按参数类型自动分发。这不是缺陷，而是设计取舍——但真需要按类型差异化行为时，得靠其他机制补足。
singledispatch只能装饰普通函数，不能直接用于实例方法
这是最常踩的坑：@singledispatch要求被装饰对象是模块级函数，它内部靠注册的类型到函数的映射表工作，而实例方法绑定在self上，第一个参数固定为实例，无法对后续参数做统一类型分发。
可行方案是把逻辑抽到模块级函数，再在方法里调用：
from functools import singledispatch
<p>@singledispatch
def handle_data(data):
raise TypeError(f"Unsupported type: {type(data)}")</p><p>@handle<em>data.register
def </em>(data: str):
return f"string: {data.upper()}"</p><p>@handle<em>data.register
def </em>(data: int):
return f"int: {data * 2}"</p><p>class Processor:
def process(self, data):
return handle_data(data) # 这里转发
注意@handle_data.register后面用了匿名函数_，这是约定俗成写法，避免污染命名空间。
立即学习“Python免费学习笔记（深入）”；
register时指定类型要小心继承关系
singledispatch默认只匹配精确类型，子类不会自动触发父类注册的处理函数，除非显式调用@func.register(ParentClass)或启用dispatch的__mro__查找（需手动实现）。
- 若注册了
@handle_data.register(list)，传入MyList()（继承自list）不会命中 - 想支持子类，要么注册
MyList本身，要么改用singledispatchmethod（Python 3.8+，专为方法设计） - 或者在注册时用
isinstance兜底：@handle_data.register(object)作为最后 fallback
singledispatchmethod更适合类内多态场景
如果目标是让一个类的方法能根据某个参数类型自动切换行为，优先用singledispatchmethod——它专为解决“实例方法重载”而生，底层原理类似，但会自动绑定self，且支持classmethod和staticmethod。
from functools import singledispatchmethod
<p>class Calculator:
@singledispatchmethod
def add(self, value):
raise TypeError(f"Cannot add {type(value)}")</p><pre class="brush:php;toolbar:false;">@add.register
def _(self, value: int):
return self._add_int(value)
@add.register
def _(self, value: str):
return self._add_str(value)
关键点：@singledispatchmethod必须装饰在实例方法上，且所有@register变体也必须是实例方法（不能是静态函数），否则self会丢失。
容易忽略的是：它只对**第一个非self参数**做类型分发，其余参数不参与匹配——这点和singledispatch一致，但初学者常误以为能按多个参数组合分发。
