Mypy类型兼容性困惑：字面量与变量报错差异及PyArrow适配问题

一、字典参数类型不匹配问题 #

示例代码 #

def foo(bar: dict[int | float, int | float]) -> None:
    pass

foo({1: 1})
bas = {1: 1}
foo(bas)

触发的Mypy错误 #

6: error: Argument 1 to "foo" has incompatible type "dict[int, int]"; expected "dict[int | float, int | float]"  [arg-type]

疑问解答 #

1. 为何字面量传入正常，变量传入报错？

Mypy对字面量会做类型拓宽（type widening）的反向操作——也就是字面量类型窄化。当直接传入{1:1}时，Mypy会推断这个字典的类型是dict[int | float, int | float]，刚好匹配函数参数的要求；但当把字面量赋值给变量bas时，Mypy会默认将变量类型推断为最具体的dict[int, int]，因为它要保证变量后续赋值的安全性（比如之后给bas添加{2.5:3}就会触发类型错误），所以这个具体类型和函数期望的宽泛类型不兼容，导致报错。

2. 为什么dict[int, int]和dict[int | float, int | float]不兼容？

Python的dict是*可变（mutable）*容器，Mypy对可变容器的类型遵循严格的协变/逆变规则：

• 对于可变容器，它的键和值类型都要求精确匹配，不支持协变。因为如果允许dict[int, int]传入期望dict[int | float, int | float]的函数，函数内部可能会往字典里添加float类型的键或值（比如bar[2.5] = 3.0），但原变量bas的实际类型是dict[int, int]，这会破坏类型安全。

二、PyArrow replace_schema_metadata类型问题 #

示例代码 #

metadata = table.schema.metadata
assert metadata is not None
metadata[b'my-metadata'] = b'interesting stuff'
table = table.replace_schema_metadata(metadata)

PyArrow存根定义 #

class Schema(_Weakrefable):
    metadata: dict[bytes, bytes] | None
    ...
class Table(_PandasConvertible):
    ...   
def replace_schema_metadata(
        self: _Self, metadata: dict[str | bytes, str | bytes] | None = ...
    ) -> _Self: ...

疑问解答 #

3. 除了# type: ignore[arg-type]，还有哪些规避方法？

有几种更优雅的方式：

• 显式类型注解：给metadata变量加上函数期望的类型注解，强制Mypy认可类型兼容：

  metadata: dict[str | bytes, str | bytes] = table.schema.metadata
  assert metadata is not None
  

• 类型转换：使用typing.cast明确告诉Mypy变量的类型：

  from typing import cast
  metadata = cast(dict[str | bytes, str | bytes], table.schema.metadata)
  assert metadata is not None
  

• 调整参数传递方式：直接在调用时转换类型，避免修改变量注解：

  table = table.replace_schema_metadata(cast(dict[str | bytes, str | bytes], metadata))
  

4. 这是Mypy的问题还是PyArrow的问题？

两者都有关联，但核心是PyArrow存根定义不够严谨：

• Mypy的行为符合可变容器类型安全规则，它拒绝把更具体的dict[bytes, bytes]传给期望更宽泛的dict[str | bytes, str | bytes]，因为可变容器不支持协变，这是为了保证类型安全。
• PyArrow的存根设计存在矛盾：Schema.metadata的类型是dict[bytes, bytes] | None，但replace_schema_metadata却要求dict[str | bytes, str | bytes] | None，从业务逻辑来看，元数据通常使用字节键值对，存根应该允许传入dict[bytes, bytes]类型的参数。

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