Python标注单一类型列表函数时mypy未检出混合类型错误是何原因？

核心原因 #

你编写的类型注解本身是完全正确的，未触发预期报错是因为对Python泛型的类型推导逻辑存在认知偏差：

• list[T]的约束含义是列表内所有元素的类型统一为T，这里的T可以是任意合法类型，包括联合类型
• 你传入的异构列表字面量["hello", 5]会被mypy自动推导为list[str | int]类型，代入泛型签名时T会被推导为str | int，完全符合类型约束，因此不会报错

你可以添加reveal_type验证推导结果：

my_list = ["hello", 5]
reveal_type(my_list)
# mypy输出：Revealed type is "list[Union[str, int]]"

实现预期校验的方案 #

如果需要让传入混合类型元素的场景触发报错，可以用以下两种常用方案：

方案1：显式标注传入列表的类型 #

强制指定列表的元素类型，不让mypy自动推导为联合类型：

# 这一步就会触发mypy报错：Item "int" of "list[Union[str, int]]" is not assignable to list item type "str"
str_list: list[str] = ["hello", 5]
print(first(str_list))

方案2：调用函数时显式指定泛型参数 #

调用泛型函数时手动绑定T的具体类型，避免自动推导为联合：

# 会触发mypy报错：List item 1 has incompatible type "int"; expected "str"
print(first[str](["hello", 5]))

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