如何为满足特定输出规则的Python函数添加正确类型注解？

AI 小北

2026-8-21

正确的Python函数类型注解方案

针对你给出的函数，原Union写法无法精准约束输入输出的对应关系，要满足「输入int返回int、输入float返回float、输入str返回None」的规则，推荐两种方案：

方案一：使用函数重载（`@overload`）

这是最直观且类型检查器支持最好的方式，通过定义多个函数签名来明确不同输入对应的输出类型：

from typing import overload

# 定义三种输入输出的重载签名
@overload
def f(value: int) -> int:
    ...

@overload
def f(value: float) -> float:
    ...

@overload
def f(value: str) -> None:
    ...

# 函数本体实现
def f(value: int | float | str) -> int | float | None:
    if isinstance(value, str):
        return None
    return value

说明

每个@overload装饰的函数只定义签名，用...代替实现
类型检查器（如mypy、pyright）会根据传入参数的类型，匹配对应的重载签名，精准推断返回值类型
Python 3.10+支持用|替代Union，旧版本需改为Union[int, float, str]和Union[int, float, None]

方案二：使用`TypeVar`约束泛型类型

如果想通过泛型简化写法，可以定义一个限定为int/float的类型变量，结合Union实现：

from typing import TypeVar, Union

# 定义只能是int或float的类型变量T
T = TypeVar('T', int, float)

def f(value: Union[T, str]) -> Union[T, None]:
    if isinstance(value, str):
        return None
    return value