Python typing重载Dict参数时mypy报重载实现未接受所有参数错误

mypy对@overload装饰的重载函数有强制校验规则：不带装饰器的实际实现函数的参数类型，必须兼容所有重载签名声明的可接受参数类型，否则就会抛出你看到的不兼容错误。
你的代码触发报错的核心原因是忽略了Dict类型的类型不变（invariant）特性：

1. 你声明的两个重载签名，接受的入参分别是Dict[int, int]和Dict[int, float]
2. 实际实现的入参标注为Dict[int, Union[int, float]]，由于Dict是可变容器，mypy不会将Dict[int, int]判定为Dict[int, Union[int, float]]的子类型——如果允许这种转换，实现函数内部完全可以向字典中写入float值，会污染外部传入的纯int类型字典，破坏类型安全。
3. 这就导致实现函数的入参类型，无法兼容第一个重载签名要求接受的Dict[int,int]类型参数，最终抛出参数不匹配的错误。

你的函数内部仅对传入的字典做读操作，没有修改内容，最合理的修复是将实现的入参类型替换为只读的Mapping类型：Mapping是只读字典协议，支持类型协变，Dict[int,int]、Dict[int,float]都属于Mapping[int, Union[int,float]]的合法子类型，完全满足类型兼容要求。
修复后的完整可通过校验的代码如下：

import random
from typing import overload, Dict, Union, Mapping

@overload
def get_random(
        d: Dict[int, int]
) -> int:
    ...

@overload
def get_random(
        d: Dict[int, float]
) -> float:
    ...

def get_random(
        d: Mapping[int, Union[int, float]]
) -> Union[int, float]:
    key = random.choice(list(d.keys()))
    return d[key]


a: int = get_random({1:1})
b: float = get_random({1:1.0})

如果你确实需要在实现中修改传入的字典（当前场景无此需求），也可以将实现入参标注为两个重载入参类型的联合：d: Union[Dict[int,int], Dict[int,float]]，这种写法同样可以通过校验，但写法冗余，不符合只读场景的语义。

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