typing.overload 是用于为同一函数名声明多个类型签名的装饰器，仅供类型检查器使用，不执行逻辑；真实实现由后续未装饰的同名函数承担，且必须严格遵循先重载声明、后具体实现的结构。
typing.overload 是 Python 中用于为**同一个函数名**声明多个**类型签名（type signatures）** 的装饰器，它本身**不实现逻辑**，只供类型检查器（如 mypy、PyCharm、VS Code 的 Pylance）使用。真正的运行时逻辑仍由一个**未装饰的、具体的实现函数**承担。
核心机制：重载声明 + 单一实现
必须严格遵循“先声明、后实现”的结构：
- 用
@overload装饰多个函数定义（仅含...或pass，无实际代码）； - 这些声明必须连续排列，中间不能插入其他语句；
- 最后必须有一个**未被
@overload装饰的同名函数**，它包含真实逻辑； - 类型检查器会根据调用时的参数类型，从重载声明中选择最匹配的一个进行校验。
基本写法示例
比如实现一个支持 str 或 bytes 输入、返回对应类型的大写函数：
from typing import overload <p>@overload def uppercase(s: str) -> str: ...</p><p>@overload def uppercase(s: bytes) -> bytes: ...</p><p>def uppercase(s: str | bytes) -> str | bytes: if isinstance(s, str): return s.upper() else: return s.upper()
调用时：
-
uppercase("hello")→ 类型检查器推断返回str； -
uppercase(b"hello")→ 推断返回bytes； - 传入
int会报错，因为没有匹配的重载签名。
常见使用场景
-
可选参数组合不同导致返回类型不同：例如
json.loads(s, *, parse_float=None)，当parse_float是Callable[[str], float]时，可能影响返回中数字的类型表现（虽实际中较少严格建模，但原理类似）； -
泛型参数影响返回类型：配合
TypeVar，让输入容器类型决定输出类型（如def first[T](lst: list[T]) -> T）； -
区分就地修改与返回副本：例如
pandas.DataFrame.copy()，deep=True时返回新对象，deep=False可能返回视图（类型上可建模为不同返回类型）。
注意事项
- 重载声明本身在运行时不生效，
help(uppercase)或uppercase.__doc__只显示最终实现函数的文档； - 所有重载签名必须能被最终实现函数的类型所“覆盖”（即实现函数的参数和返回类型需是所有重载签名的并集或超集）；
- 不要在重载声明里写 docstring 或逻辑，否则类型检查器可能报错或忽略；
- Python 3.12+ 支持更简洁的
case语法（PEP 692），但@overload仍是主流兼容方式。
