带默认参数的方法结合关键字参数字典的mypy类型检查问题

mypy报错是因为它无法确定你通过**kwargs传递的字典里是否包含opt_arg键——如果字典里有这个键，对应的值是str类型，和f_with_opt中opt_arg要求的bool | None类型完全不兼容，所以会抛出类型不匹配的错误。

根据你的实际需求，有几种可行的注解方式：

1. 精确限定kwargs的允许键（推荐，用到PEP612） #

如果f_with_opt的**kwargs只会接收特定的键（比如例子里的foo），不会包含opt_arg，可以用TypedDict结合PEP612的Unpack来精确注解：

from typing import TypedDict, Unpack, Optional

class FAllowedKwargs(TypedDict):
    foo: str
    # 可以添加其他允许的键值对类型

def f_with_opt(opt_arg: Optional[bool] = None, **kwargs: Unpack[FAllowedKwargs]):
    print(f"{opt_arg=}, {kwargs=}")

def function() -> None:
    kwargs = {"foo": "bar"}
    f_with_opt(**kwargs)  # 不再报错

这种方式让mypy明确知道**kwargs的键范围，不会担心和opt_arg冲突，同时保留了类型检查的严格性。

2. 允许kwargs包含opt_arg（可选场景） #

如果f_with_opt允许通过**kwargs传递opt_arg，可以把opt_arg纳入TypedDict并标记为可选：

from typing import TypedDict, Unpack, Optional, NotRequired

class FAllowedKwargs(TypedDict):
    opt_arg: NotRequired[Optional[bool]]
    foo: str

def f_with_opt(**kwargs: Unpack[FAllowedKwargs]):
    opt_arg = kwargs.get("opt_arg")
    print(f"{opt_arg=}, {kwargs=}")

def function() -> None:
    kwargs = {"foo": "bar"}
    f_with_opt(**kwargs)  # 不再报错

这种写法会把opt_arg从位置参数转为kwargs的可选参数，适合需要灵活传递参数的场景。

3. 宽松注解kwargs（快速解决） #

如果不需要精确限定kwargs的类型，只是想让mypy停止报错，可以直接给**kwargs指定一个宽泛的类型：

def f_with_opt(opt_arg: bool | None = None, **kwargs: object):
    print(f"{opt_arg=}, {kwargs=}")

def function() -> None:
    kwargs = {"foo": "bar"}
    f_with_opt(**kwargs)  # 不再报错

这种方式牺牲了部分类型检查的严格性，但实现起来最简单。

PEP612正是为解决这类**kwargs的类型注解痛点而生的——它引入的Unpack类型能让你精确描述可变关键字参数的结构，避免mypy因为不确定kwargs内容而抛出错误。上面的前两种方案都用到了PEP612的特性，完全适配你的场景，是更规范的解决方式。

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