Python中的声明式重载，overload

非常好，这个问题问得很有深度！🎯
@overload 是 Python 里一个类型提示（type hinting）工具，主要用于 静态类型检查，而不是在运行时真的改变函数行为。

我们来系统讲清楚 👇

🧠 一句话总结

@overload 用来声明一个函数有多个不同的调用签名（signature）， 方便像 mypy 或 Pyright 这样的类型检查器进行静态类型推断。 👉 它不会在运行时生效，只是给类型检查器看的。

🧩 举个例子说明

比如我们写一个函数 read_data，

既可以接受 str（文件名），也可以接受 bytes（二进制数据）：

from typing import overload, Union

@overload
def read_data(data: str) -> str: ...
@overload
def read_data(data: bytes) -> bytes: ...

def read_data(data: Union[str, bytes]):
    if isinstance(data, str):
        print("reading from file name")
        return data  # 实际上你可能会去打开文件
    elif isinstance(data, bytes):
        print("reading from bytes")
        return data
    else:
        raise TypeError("Unsupported type")

✅ 调用时的类型推断（在 IDE 或类型检查工具里）

x = read_data("test.txt")   # 类型推断为 str
y = read_data(b"binary")    # 类型推断为 bytes

类型检查器能“看懂”这两个重载签名，因此知道不同输入对应不同输出类型。

👉 这让 IDE 自动补全、类型检测更准确。

🚫 注意：@overload 不会真的重载函数！

Python 在运行时只会看到最后一个非 @overload 修饰的实现：

def read_data(data: Union[str, bytes]):
    ...

所有上面的 @overload 函数只是“声明”，没有实际代码（用 ... 或 pass）。

🧠 和真正的函数重载（如 C++、Java）不同

✅ 再看一个例子：list.__getitem__

Python 标准库本身就用 @overload 描述不同的调用方式：

from typing import overload, Any

@overload
def __getitem__(self, i: int) -> Any: ...
@overload
def __getitem__(self, s: slice) -> list[Any]: ...

def __getitem__(self, index):
    # 实际实现
    ...

所以类型检查器知道：

• my_list[0] → 返回一个元素；
• my_list[0:2] → 返回一个子列表。

✅ 总结