Mypy中如何为除特定值外的字符串参数正确编写重载类型提示

报错原因 #

两个重载签名的入参范围存在覆盖冲突：Literal["some_value"]属于str的子类型，第二个重载的param: str完全包含了第一个重载的合法入参，且二者返回类型不一致，MyPy严格模式下会判定这种歧义性重叠为非法写法。

修复方案 #

通过否定类型+交叉类型明确划分两个重载的入参边界，让第二个重载仅匹配「不等于"some_value"的字符串」，从根源上消除入参范围重叠：

from typing import Literal, overload
# Python 3.13+ 可直接从typing导入Not，低版本先执行 pip install typing-extensions，再从typing_extensions导入Not
from typing import Not

class A: ...
class B: ...

@overload
def build(param: Literal["some_value"], **kwargs) -> "A": ...

@overload
def build(param: Not[Literal["some_value"]] & str, **kwargs) -> "B": ...

# 实际运行逻辑写在无@overload装饰器的实现函数中
def build(param: str, **kwargs) -> "A | B":
    if param == "some_value":
        return A()
    return B()

类型推导验证 #

用MyPy检查如下测试代码，可得到符合预期的推导结果：

reveal_type(build("some_value"))  # 推导结果为 "A"
reveal_type(build("test"))        # 推导结果为 "B"
reveal_type(build("any_other"))   # 推导结果为 "B"

注意事项 #

• 不要通过关闭strict-overload配置绕过报错，该规则会拦截其他存在逻辑漏洞的错误重载写法
• 若MyPy版本低于1.10，需先升级版本才能正确识别Not类型，低版本无原生方式实现“排除特定字面量的字符串”类型标注，强行用str作为第二个重载的param类型会导致类型推导失效
• 所有带@overload装饰器的函数仅为类型检查的签名占位，不能写实际逻辑，运行时代码必须放在最后一个无装饰器的实现函数中，实现函数的参数、返回类型需要覆盖所有重载的类型范围

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