overload 函数重载

在 Python 中，`overload` 主要是用于函数重载（`function overloading`）的类型提示（`type hinting`）。它来自于 `typing` 模块。函数重载允许你为同一个函数名定义不同的参数类型和返回类型。在 Python 的动态类型系统中，overload 并不会像静态类型语言（例如 C++ 或 Java）那样在运行时实际执行不同的函数版本，而是提供了类型检查工具（如 mypy）在静态分析时检查不同的函数签名。

### 基本使用
要使用 overload，你需要导入 typing.overload 装饰器，并为同一个函数定义多个类型提示版本。注意，实际的函数定义只有一个，它应该匹配最通用的签名。装饰过的函数不会被真正调用，它们只是为了类型检查工具服务。
```
from typing import overload, Union

# 这里定义了三个不同的类型提示版本
@overload
def greet(name: str) -> str:
    ...

@overload
def greet(name: str, age: int) -> str:
    ...

@overload
def greet(name: str, age: int, height: float) -> str:
    ...

# 实际的函数实现
def greet(name: str, age: int = None, height: float = None) -> str:
    if age is not None and height is not None:
        return f"Hello, {name}. You are {age} years old and {height} meters tall."
    elif age is not None:
        return f"Hello, {name}. You are {age} years old."
    else:
        return f"Hello, {name}."

# 示例调用
print(greet("Alice"))  # 输出: Hello, Alice.
print(greet("Bob", 30))  # 输出: Hello, Bob. You are 30 years old.
print(greet("Charlie", 25, 1.75))  # 输出: Hello, Charlie. You are 25 years old and 1.75 meters tall.
```

### 解释
- `@overload 装饰器`：每个使用 `@overload` 装饰器定义的函数并不会真正实现任何功能，而是用来定义不同的参数类型和返回类型组合。装饰器后面的函数体用省略号 ... 来表示，这些函数体是不会被实际调用的。

- `实际实现`：实际的 greet 函数是唯一一个会被调用的函数。它包含了最通用的参数集，并根据参数的存在与否进行不同的逻辑处理。

- `类型检查`：使用 mypy 或其他类型检查工具时，它会根据 @overload 提供的签名进行类型匹配和检查。这个功能在大型代码库中尤其有用，因为它可以在不牺牲动态行为的情况下提高代码的可读性和可靠性。

### 使用注意事项
- @overload 装饰的函数体必须是空的，只能使用省略号 ... 或 pass。

- 必须有一个实际的函数实现来处理所有可能的参数组合。

- @overload 仅用于类型检查，不会在运行时实际执行多个函数版本。因此，实际的函数实现必须能够处理所有重载签名的情况。

### 什么时候使用 overload
- 当一个函数可以接受不同类型或数量的参数，并且返回值可能随参数类型或数量变化时。

- 当你想为动态类型的函数提供静态类型提示，以便更好地利用类型检查工具。

- 当你想在大型代码库中维护更严格的类型安全，而又不想牺牲函数的灵活性时。

### 总结
总的来说，overload 是 Python 类型提示系统中的一个工具，可以帮助你定义复杂的函数签名，同时提供灵活的动态行为。