如何为含布尔参数的Python函数标注条件化返回类型？

你可以通过typing.overload为函数定义多个类型签名，让类型检查器（如mypy、pyright）根据传入的布尔字面量，自动识别对应的返回类型。

方法一：结合Literal使用重载 #

这种方式最直观，明确指定布尔参数的字面量值对应的返回类型：

from typing import overload, Union, Literal

# 为ret_str=True的情况定义类型签名
@overload
def fn(x: int, ret_str: Literal[True]) -> str:
    ...

# 为ret_str=False的情况定义类型签名
@overload
def fn(x: int, ret_str: Literal[False]) -> int:
    ...

# 函数实际实现，返回类型用Union覆盖所有情况
def fn(x: int, ret_str: bool) -> Union[int, str]:
    if ret_str:
        return str(x)
    else:
        return x

调用时，类型检查器会正确推导返回类型：

out_int = fn(8, ret_str=False)  # 类型检查器识别为int
out_str = fn(8, ret_str=True)   # 类型检查器识别为str

方法二：直接通过重载指定参数值 #

如果不需要显式用Literal，也可以直接在重载签名里指定布尔参数的取值：

from typing import overload, Union

@overload
def fn(x: int, ret_str: bool = True) -> str:
    ...

@overload
def fn(x: int, ret_str: bool = False) -> int:
    ...

def fn(x: int, ret_str: bool) -> Union[int, str]:
    if ret_str:
        return str(x)
    else:
        return x

这种写法同样能让类型检查器根据传入的字面量True/False推导返回类型。

注意：@overload定义的签名仅用于类型检查，实际运行时不会执行，函数的逻辑依然由最后那个实际实现的函数体处理。如果使用Python 3.7及以下版本，需要安装typing_extensions库来导入Literal和overload。

内容的提问来源于stack exchange，提问作者Tetheras