如何在Python类型注解中限制函数重载仅匹配非字面量参数？

问题背景 #

我通过枚举字面量实现了函数重载，让参数foo的类型与test的枚举值绑定：

from enum import Enum
from typing import overload, Literal

class Test(Enum):
    A = 'A'
    B = 'B'
 
@overload
def test(test: Literal[Test.A], foo: int) -> None: ...
 
@overload
def test(test: Literal[Test.B], foo: str) -> None: ...

def test(test: Test, foo: int | str) -> None:
    print(test)
    print(foo)

这套重载能在字面量传参时保证类型匹配，但传入变量作为test参数时，mypy会报错找不到匹配的重载。如果添加通用重载@overload def test(test: Test, foo: int | str) -> None: ...，变量调用能通过检查，但字面量传参错误（比如test(Test.A, 'abc')）也会被放行。

我需要实现的效果是：类型检查器能检测出字面量传参的错误，同时兼容变量传参（由调用者保证合法性），是否可以限制通用重载仅匹配非字面量参数？或者有其他可行方案？

可行解决方案 #

方案1：利用Not类型约束（需mypy 0.910+） #

通过typing_extensions.Not排除字面量类型，让通用重载仅匹配非字面量的Test变量。mypy会优先匹配更具体的字面量重载，只有当test是无法确定具体枚举值的变量时，才会匹配通用重载。

from enum import Enum
from typing import overload, Literal
from typing_extensions import Not

class Test(Enum):
    A = 'A'
    B = 'B'
 
@overload
def test(test: Literal[Test.A], foo: int) -> None: ...
 
@overload
def test(test: Literal[Test.B], foo: str) -> None: ...

# 仅匹配非字面量的Test类型参数
@overload
def test(test: Not[Literal[Test.A, Test.B]], foo: int | str) -> None: ...

def test(test: Test, foo: int | str) -> None:
    print(test)
    print(foo)

• 当传入Test.A/Test.B字面量时，会匹配前两个重载，若foo类型错误，mypy会直接报错。
• 当传入类型为Test的变量时，会匹配第三个重载，允许foo为int | str。

方案2：运行时类型断言+重载保留 #

如果不想依赖typing_extensions，可以在函数内部添加运行时类型断言，既保留字面量的类型检查，又兼容变量传参：

from enum import Enum
from typing import overload, Literal, assert_type

class Test(Enum):
    A = 'A'
    B = 'B'
 
@overload
def test(test: Literal[Test.A], foo: int) -> None: ...
 
@overload
def test(test: Literal[Test.B], foo: str) -> None: ...

@overload
def test(test: Test, foo: int | str) -> None: ...

def test(test: Test, foo: int | str) -> None:
    # 运行时校验参数合法性
    if test is Test.A:
        assert_type(foo, int)
    elif test is Test.B:
        assert_type(foo, str)
    print(test)
    print(foo)

• 字面量传参错误会被mypy在静态检查阶段检测到。
• 变量传参时，mypy会放行，但运行时若参数不合法会触发断言（可替换为自定义错误提示）。

方案3：拆分函数+统一入口 #

将不同枚举值的逻辑拆分为单独函数，通过统一入口分发，既保证类型严格性，又提升代码可读性：

from enum import Enum
from typing import Literal, overload

class Test(Enum):
    A = 'A'
    B = 'B'

def _test_a(foo: int) -> None:
    print(Test.A)
    print(foo)

def _test_b(foo: str) -> None:
    print(Test.B)
    print(foo)

@overload
def test(test: Literal[Test.A], foo: int) -> None: ...

@overload
def test(test: Literal[Test.B], foo: str) -> None: ...

@overload
def test(test: Test, foo: int | str) -> None: ...

def test(test: Test, foo: int | str) -> None:
    if test is Test.A:
        _test_a(foo)
    elif test is Test.B:
        _test_b(foo)

这种方式拆分了不同枚举值的业务逻辑，静态类型检查更严格，同时变量传参也能正常通过。

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