如何为可变参数函数标注「至少一个参数为指定类型」的类型注解？

要实现「只要参数里有一个Dangerous就返回Dangerous，全Safe（包括空参）返回Safe」的类型推导，直接写重叠的重载会因为参数范围冲突报错。核心思路是拆分重载签名，让「全Safe」和「含至少一个Dangerous」的场景完全不重叠。

可行实现代码 #

from typing import overload, Union

class Safe:
    pass

class Dangerous:
    pass

# 全Safe参数（包括空参），返回Safe
@overload
def combine(*args: Safe) -> Safe: ...

# 首参数是Dangerous，后续任意参数，返回Dangerous
@overload
def combine(first: Dangerous, *rest: Union[Safe, Dangerous]) -> Dangerous: ...

# 首参数是Safe，但末参数是Dangerous（覆盖中间夹着Dangerous的情况），返回Dangerous
@overload
def combine(first: Safe, *rest: Union[Safe, Dangerous], last: Dangerous) -> Dangerous: ...

# 实际业务逻辑实现
def combine(*args: Union[Safe, Dangerous]) -> Union[Safe, Dangerous]:
    if all(isinstance(arg, Safe) for arg in args):
        return Safe()
    else:
        return Dangerous()

# 类型验证
reveal_type(combine())                  # 推导结果：Safe
reveal_type(combine(Safe()))            # 推导结果：Safe
reveal_type(combine(Dangerous()))       # 推导结果：Dangerous
reveal_type(combine(Safe(), Safe()))    # 推导结果：Safe
reveal_type(combine(Safe(), Dangerous())) # 推导结果：Dangerous
reveal_type(combine(Dangerous(), Safe())) # 推导结果：Dangerous

为什么这样可行？ #

• 第一个重载严格匹配**仅含Safe**的参数（包括空参），和其他重载的参数范围完全不重叠，避免了类型冲突。
• 后两个重载覆盖了所有包含Dangerous的情况：要么首参数就是Dangerous，要么首参数是Safe但末尾有Dangerous——类型检查器会自动匹配最具体的签名，确保所有带Dangerous的调用都返回Dangerous类型。

这种方式没有依赖额外库，兼容主流类型检查器（mypy、pyright），完全满足需求。

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