为何出现“Expected type 'int'...”类型提示警告？求解决办法

问题复现 #

先把你的操作步骤清晰列出来，方便对照：

• 步骤1：执行以下代码，无任何类型警告

  game_data = {'boats': [], }
  game_data['boats'].append({'name': None})
  

• 步骤2：给字典新增两个None类型的key，仍然没有警告

  game_data = {'boats': [], 'width': None, 'height': None, }
  game_data['boats'].append({'name': None})
  

• 步骤3：把height赋值为int变量w后，立刻弹出警告：Expected type 'int' (matched generic type '_T'), got 'Dict[str, None]' instead

  w = 12
  game_data = {'boats': [], 'width': None, 'height': w, }
  game_data['boats'].append({'name': None})
  

为什么会出现这个警告？ #

你真的不是独苗！这是Pyright、Mypy这类静态类型检查工具的推断逻辑“小偏差”：

• 前两步中，字典的value类型是混合的：空列表、None，工具会把game_data推断成dict[str, object]或者dict[str, Union[list, None]]，此时boats被识别为可以存任意类型的列表，append字典自然没问题。
• 第三步里，height用了int类型的变量，工具会尝试“统一”字典的value类型：它看到width是None、height是int，就会把这两个key的类型推断为Union[int, None]，但同时错误地把boats这个列表的元素类型也绑定成了int——于是当你往列表里塞字典时，就触发了类型不匹配的警告。

简单说就是工具太“较真”，试图让字典所有value的类型尽量统一，结果误伤了列表的类型推断。

怎么消除这个警告？ #

这里有几个实用的解决办法，按推荐程度排序：

1. 显式标注字典类型（最规范） #

直接告诉类型检查工具每个key对应的类型，从根源上避免推断错误：

# Python 3.10+ 可以用这个简洁语法
from typing import Dict, List, Optional

w = 12
game_data: Dict[str, Optional[int] | List[Dict[str, None]]] = {
    'boats': [], 
    'width': None, 
    'height': w, 
}
game_data['boats'].append({'name': None})

如果是Python 3.9及以下，把Optional[int] | List[...]换成Union[Optional[int], List[...]]就行。

2. 单独初始化boats列表 #

先创建boats列表再放进字典，让工具先识别列表的类型，避免被字典的其他value干扰：

w = 12
boats = []
game_data = {'boats': boats, 'width': None, 'height': w, }
game_data['boats'].append({'name': None})

这样工具会先把boats推断为list[dict[str, None]]，放进字典后也不会被错误覆盖类型。

3. 临时忽略警告（应急方案） #

如果只是想快速跳过这个警告，可以在append那一行加注释：

w = 12
game_data = {'boats': [], 'width': None, 'height': w, }
game_data['boats'].append({'name': None})  # type: ignore

不过这个方法不推荐长期用，显式标注类型才是更利于代码维护的做法。

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