如何在字典抽象的配置类中正确使用Typehints/mypy？

问题场景 #

你的config.yaml内容：

attr1: some_string
attr2: some_int
attr3:
  subkey1: some_string
  subkey2: some_string
attr4:
  - item1
  - item2

封装配置的Config类：

from typing import Any
import yaml

class Config:

    def __init__(self):
        with open("config.yaml", "r") as f:
            self.config_dict: dict[str, Any] = yaml.safe_load(f)

    @property
    def attr1(self) -> str:
        return self.config_dict["attr1"]

    @property
    def attr2(self) -> int:
        return self.config_dict["attr2"]

    # ... 其他属性定义

mypy报错：

error: Returning Any from function declared to return "str"
error: Returning Any from function declared to return "int"

解决方案 #

1. 基础方案：类型断言（cast） #

直接用typing.cast告诉mypy返回值的实际类型，这是最简洁的方式，但仅在你能确保配置值类型正确时使用，运行时不会做校验：

from typing import Any, cast
import yaml

class Config:

    def __init__(self):
        with open("config.yaml", "r") as f:
            self.config_dict: dict[str, Any] = yaml.safe_load(f)

    @property
    def attr1(self) -> str:
        return cast(str, self.config_dict["attr1"])

    @property
    def attr2(self) -> int:
        return cast(int, self.config_dict["attr2"])

2. 安全方案：运行时校验+类型推导 #

用assert做运行时类型检查，mypy会自动推断出通过断言后的值类型，既满足类型检查，又能在运行时捕获配置错误：

from typing import Any
import yaml

class Config:

    def __init__(self):
        with open("config.yaml", "r") as f:
            self.config_dict: dict[str, Any] = yaml.safe_load(f)

    @property
    def attr1(self) -> str:
        value = self.config_dict["attr1"]
        assert isinstance(value, str), f"配置项attr1类型错误：预期str，实际{type(value)}"
        return value

    @property
    def attr2(self) -> int:
        value = self.config_dict["attr2"]
        assert isinstance(value, int), f"配置项attr2类型错误：预期int，实际{type(value)}"
        return value

3. 推荐方案：使用Pydantic自动处理类型 #

用pydantic的BaseModel定义配置结构，它会自动完成yaml解析、类型校验、类型推导，代码更简洁且健壮：

from pydantic import BaseModel
import yaml

# 定义子配置结构
class SubConfig(BaseModel):
    subkey1: str
    subkey2: str

# 定义完整配置结构
class Config(BaseModel):
    attr1: str
    attr2: int
    attr3: SubConfig
    attr4: list[str]

    @classmethod
    def from_yaml(cls, file_path: str) -> "Config":
        with open(file_path, "r") as f:
            config_data = yaml.safe_load(f)
        return cls(**config_data)

# 使用方式
config = Config.from_yaml("config.yaml")
print(config.attr1)  # mypy能正确识别类型为str

Pydantic会在初始化时自动校验配置值的类型，如果配置不符合定义，会直接抛出清晰的错误提示，同时mypy能完美识别所有属性的类型。

关于类型断言的疑问 #

如果是手动封装配置类，需要通过类型断言（cast）或运行时校验（assert）让mypy明确返回值的类型；如果使用Pydantic这类专门的配置校验库，则不需要手动编写类型断言，库已经帮你处理了类型推导和校验逻辑。

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