Mypy对重载函数报签名重叠错误？签名不同却类型冲突

报错原因 #

Mypy 0.991的重载匹配逻辑和Pylance存在差异：当你将a: None作为独立重载签名时，Mypy会认为它和a: Literal[False]、a: Literal[True]的签名存在潜在重叠。这是因为None属于Optional[Literal[True, False]]的范畴，Mypy无法像Pylance那样精准区分这三种字面量类型的独立分支，反而会将None与另外两个字面量的可选场景视为可能的匹配冲突，从而抛出返回类型不兼容的重叠错误。

修复方案 #

由于func_a(a=False)和func_a(a=None)（包括默认调用func_a()）的返回类型都是str，可以将这两个重载签名合并，消除Mypy认为的重叠：

from typing import overload, Literal, Optional

@overload
def func_a(a: Literal[False] | None) -> str: ...

@overload
def func_a(a: Literal[True]) -> int: ...

def func_a(a: Optional[Literal[True, False]] = None) -> str | int:
    if a is True:
        return 1
    return "hello"

合并后，Mypy能清晰识别两种不同返回类型的分支，不会再触发重叠错误，同时也能保留原有的类型推断逻辑——func_a()、func_a(a=False)返回str，func_a(a=True)返回int。

内容的提问来源于stack exchange，提问作者Pedro Perpétua