如何让Mypy接受带空字典默认值的泛型Dict类型？

问题根源 #

你遇到的报错核心原因有两个：一是Mypy无法确认默认值{}的类型能匹配泛型类型变量T的所有可能绑定类型；二是你的ScriptArgs类未继承Generic[T]，导致泛型参数无法被Mypy正确识别。

可行解决方法 #

方法1：用Optional默认值并内部处理 #

将参数类型设为Optional[T]，默认值设为None，在方法内部把None替换为空字典，同时让类继承Generic[T]以关联泛型：

from collections.abc import Hashable
from typing import Any, Never, TypeVar, Optional, Generic

K = TypeVar("K", bound=Hashable)
V = TypeVar("V")

StrKeyDict = dict[str, Any]
EmptyDict = dict[str, Never]

T = TypeVar("T", bound=StrKeyDict | EmptyDict)

class ScriptArgs(Generic[T]):
    def __init__(self, overrides: Optional[T] = None):
        self.overrides = overrides if overrides is not None else {}

方法2：给TypeVar指定默认类型并强制转换 #

给T设置默认类型，并用cast告诉Mypy默认值符合该类型约束：

from collections.abc import Hashable
from typing import Any, Never, TypeVar, cast, Generic

K = TypeVar("K", bound=Hashable)
V = TypeVar("V")

StrKeyDict = dict[str, Any]
EmptyDict = dict[str, Never]

# 给T指定默认类型为EmptyDict
T = TypeVar("T", bound=StrKeyDict | EmptyDict, default=EmptyDict)

class ScriptArgs(Generic[T]):
    def __init__(self, overrides: T = cast(T, {})):
        self.overrides = overrides

方法3：用重载定义多构造签名 #

通过@overload提供两个构造签名，分别对应带参数和不带参数的场景，让Mypy能准确推断类型：

from collections.abc import Hashable
from typing import Any, Never, TypeVar, overload, Generic

K = TypeVar("K", bound=Hashable)
V = TypeVar("V")

StrKeyDict = dict[str, Any]
EmptyDict = dict[str, Never]

T = TypeVar("T", bound=StrKeyDict | EmptyDict)

class ScriptArgs(Generic[T]):
    @overload
    def __init__(self) -> None: ...
    
    @overload
    def __init__(self, overrides: T) -> None: ...
    
    def __init__(self, overrides: T | None = None):
        self.overrides = overrides if overrides is not None else {}

关键注意点 #

• 必须让ScriptArgs继承Generic[T]，否则Mypy无法将泛型参数T与类关联。
• 空字典{}的默认类型是dict[Any, Any]，需要通过类型转换或内部逻辑让它匹配T的约束。

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