如何解决mypy中Callable与NamedArg的类型不兼容错误？

问题背景 #

我需要存储/转发仅接受命名参数的Callable对象，但修改函数为仅接受命名参数后，mypy抛出类型不兼容错误。

初始代码（可正常运行且通过mypy --strict检查）：

from collections.abc import Callable, MutableSequence

functions: MutableSequence[Callable[[int], None]] = []

def foo(val: int) -> None:
    print(val)

functions.append(foo)

将foo改为仅接受命名参数后：

def foo(*, val: int) -> None:
    print(val)

mypy报错：

./foo.py:11: error: Argument 1 to "append" of "MutableSequence" has incompatible type "Callable[[NamedArg(int, 'val')], None]"; expected "Callable[[int], None]"  [arg-type]

需求是：保留命名参数的类型提示，同时让列表仅接受带特定命名参数（如val）的Callable对象。

解决方案1：Python 3.10+ 原生支持的Callable关键字参数语法 #

Python 3.10及以上版本的Callable支持直接标注命名参数，语法为Callable[[*, 参数名: 类型], 返回值类型]。直接修改列表的类型注解即可解决：

from collections.abc import Callable, MutableSequence

# 明确标注Callable仅接受命名参数val: int
functions: MutableSequence[Callable[[*, val: int], None]] = []

def foo(*, val: int) -> None:
    print(val)

functions.append(foo)  # mypy检查通过

这种方案无需额外依赖，语法简洁，是最优选择。

解决方案2：用Protocol定义严格可调用类型 #

如果需要兼容Python 3.10以下版本，或者需要更复杂的调用签名约束，可以使用Protocol（Python 3.8+ 原生支持，更低版本用typing_extensions.Protocol）来定义专属的可调用协议：

from collections.abc import MutableSequence
from typing import Protocol

# 定义仅接受命名参数val: int的可调用协议
class ValCallable(Protocol):
    def __call__(self, *, val: int) -> None:
        ...

functions: MutableSequence[ValCallable] = []

def foo(*, val: int) -> None:
    print(val)

functions.append(foo)  # mypy检查通过

这种方式可以定义更精细的约束，比如多个命名参数、带默认值的参数等，类型检查更严格。

不推荐使用mypy_extensions.NamedArg的原因 #

NamedArg是mypy专属的扩展类型，不属于Python标准库，只能通过mypy_extensions导入，且它不是泛型类型，无法灵活适配不同参数场景，不利于项目的跨环境兼容和长期维护。

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