mypy无法推断字典值类型：如何优雅地将其用作函数参数？

问题场景 #

你用字典作为不可变配置，但mypy无法推断字典内具体键的类型，导致传入函数时抛出类型不兼容错误：

Argument "arg" to "my_function" has incompatible type "Union[int, float, str]"; expected "int"

示例代码：

from typing import Union

my_config: dict[str, Union[int, float, str]] = {
    "timeout": 60,
    "precision": 3.14,
    "greeting": "Hello",
}

def my_function(arg: int):
    print(f"The value is: {arg}")

my_function(arg=my_config["timeout"])  # mypy报错

你已经尝试了两种处理方式：

from typing import cast
# 运行时类型转换
my_function(arg=int(my_config["timeout"]))
# 静态类型断言
my_function(arg=cast(int, my_config["timeout"]))

以下是其他可选方案、方案对比及推荐实践：

一、更优的类型标注方案：TypedDict #

用TypedDict精确描述字典的键值对应类型，让mypy能准确推断每个键的类型，无需额外转换：

from typing import TypedDict

class MyConfig(TypedDict):
    timeout: int
    precision: float
    greeting: str

# 配置仍以字典形式存在，但类型被精确约束
my_config: MyConfig = {
    "timeout": 60,
    "precision": 3.14,
    "greeting": "Hello",
}

def my_function(arg: int):
    print(f"The value is: {arg}")

my_function(arg=my_config["timeout"])  # mypy无报错

优势：无需修改原有字典的使用方式，静态类型检查精准，代码侵入性极低。

二、不可变配置的最佳实践：Frozen Dataclass #

如果需要严格保证配置不可变性，推荐使用frozen=True的dataclass，同时获得更清晰的属性访问方式：

from dataclasses import dataclass

@dataclass(frozen=True)
class MyConfig:
    timeout: int
    precision: float
    greeting: str

# 初始化后无法修改任何属性
my_config = MyConfig(timeout=60, precision=3.14, greeting="Hello")

def my_function(arg: int):
    print(f"The value is: {arg}")

my_function(arg=my_config.timeout)  # mypy完美推断类型

优势：

• 天然不可变，从根源避免配置被意外修改
• 属性访问比字典索引更直观，键名错误会直接在静态检查阶段暴露
• 类型约束严格，mypy能完全校验所有属性类型

三、现有方案的对比与推荐 #

1. int(my_config["timeout"])（运行时转换）

   • 会在运行时强制转换类型，如果配置值类型错误（比如误写为字符串），会抛出ValueError
   • 适合需要运行时类型校验的场景，但如果配置是你可控且确定类型的，会增加不必要的运行时开销

2. cast(int, my_config["timeout"])（静态断言）

   • 仅告诉mypy该值是int，运行时无任何检查
   • 风险较高：如果配置被意外修改为非int值，运行时会引发隐性错误
   • 仅推荐在你100%确定配置值类型正确的极端场景使用

优先推荐顺序：Frozen Dataclass > TypedDict > 运行时转换 > 静态断言

四、是否需要改用不可变数据类型？ #

如果你的配置确实不需要被修改，强烈建议改用不可变类型（如frozen dataclass、collections.namedtuple）：

• 普通字典是可变的，即使你自己不修改，也无法阻止其他代码意外修改配置值
• 不可变类型能从语法层面保证配置的一致性，避免因配置被篡改导致的难以排查的bug
• 同时能获得更精准的静态类型支持，减少类型检查错误

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