Python Callback Protocol：何时需要为__call__方法参数添加双下划线前缀？

问题背景 #

根据Mypy对Callback Protocol的类型检查规则：

• Callback Protocol与typing.Callable类型可做类型互换
• 默认规则下，__call__方法的关键字参数名必须完全一致，才算满足类型兼容
• 官方文档说明，给__call__的参数加双下划线前缀（比如__origin），可以不受这个参数名完全匹配的规则约束

但实际做最小验证时会发现：哪怕把示例里__origin的双下划线前缀去掉，最简的变量赋值场景依然能正常通过类型检查，完全感受不到文档描述的规则差异，这也是很多人困惑这个前缀到底有啥用的核心原因。

规则的核心逻辑 #

首先要明确：之前的简单测试没有触发参数名校验，本质是因为纯位置传参的场景下，Mypy从不会校验参数名。
参数名的匹配检查，只会在代码存在「以关键字形式调用回调函数」的逻辑时才会触发。之前的测试用例只做了不同类型的变量赋值，根本没有走到实际调用的校验环节，自然不会出现报错。

必须添加双下划线前缀的场景 #

当你的Callback Protocol符合以下任意一种情况时，必须给__call__的参数加双下划线前缀，才能让检查逻辑和设计预期对齐：

• 你的Protocol定义的回调，预期只会被以纯位置传参的方式调用，不要求实现这个协议的函数必须使用和Protocol完全一致的参数名
  这类通用协议的典型场景就是示例里的Copy：本质是定义「接收一个同类型参数、返回同类型结果」的函数能力，根本不关心实现者把这个参数命名为origin、input还是source。加双下划线前缀就是明确告诉Mypy：这个参数是纯位置传递的，不需要校验和实现者的参数名匹配度。
• 你需要明确禁止调用方以关键字形式给这个参数传值，避免因为参数名不匹配引发运行时错误
  双下划线前缀的参数，对应Python本身支持的「仅位置参数」语义，Mypy会识别这种标记，只要检测到调用方给这类参数传了关键字，就会直接抛出类型错误，从类型层面杜绝不兼容的传参方式。

举个会触发校验差异的对比示例：

# 不带双下划线的Protocol
class Copy(Protocol):
    def __call__(self, origin: T) -> T: ...

# 实际的实现函数，参数名和Protocol不一致
def duplicate(input: T) -> T:
    return input

copy_b: Copy = duplicate
# 下面这行代码会触发Mypy报错：Copy类型的__call__方法不接受origin作为关键字参数
copy_b(origin=123)

如果把Protocol里的参数改成__origin: T，Mypy会自动忽略实现函数的参数名差异，同时会在检测到上述关键字调用代码时，直接提示该参数为仅位置参数，不能以关键字形式传入。

反向注意事项 #

如果你的Callback Protocol需要支持调用方以关键字形式传参，那不仅不能给参数加双下划线前缀，还必须保证Protocol里的参数名，和所有可能实现这个协议的函数参数名完全一致——否则一旦出现关键字调用，Mypy就会抛出“意外关键字参数”的类型错误。 #

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