Python Dataclass处理不符合命名规则的特殊键名实现方案

Python 原生类属性名必须为合法标识符，>、/ 属于语法保留符号，不能直接作为标准库 dataclass 的属性名写在类定义里，直接书写会触发语法错误。针对你的需求，有两种成熟实现方案：

方案1：TypedDict 正确用法 #

首先明确核心规则：TypedDict 仅用于静态类型检查，运行时和普通字典完全一致，不存在独立的构造函数，你之前写的 SBS_Mutations(my_data) 属于无效调用。
它的正确使用方式如下：

• 类型定义阶段：Python 3.12+ 支持直接在类体中用字符串作为键定义特殊字符键的类型；更低版本可以用你之前写的函数式定义，通过字典传参绑定键和对应类型。
• 静态校验阶段：只需要把YAML加载得到的字典标注为对应TypedDict类型，mypy、pyright等静态检查工具就会自动校验键是否缺失、值类型是否匹配，不需要额外运行逻辑。

示例代码：

from typing import TypedDict
import yaml

# Python 3.12+ 类式定义，低版本替换为你之前写的函数式定义即可
class SBS_Mutations(TypedDict):
    "C>A/G>T": str
    "C>G/G>C": str
    "C>T/G>A": str
    "T>A/A>T": str
    "T>C/A>G": str
    "T>G/A>C": str

# 加载YAML文件
with open("mutations.yaml", "r", encoding="utf-8") as f:
    raw_data = yaml.safe_load(f)

# 赋值时加类型标注，静态检查器会自动完成类型校验
sbs_data: SBS_Mutations = raw_data["items"]

# 数据访问方式和普通字典完全一致
print(sbs_data["C>A/G>T"])

如果需要运行时校验数据是否符合TypedDict定义，TypedDict本身不提供该能力，可以搭配轻量校验库实现，比如typeguard：

from typeguard import check_type

# 校验不通过会直接抛出TypeError，校验通过无返回
check_type(sbs_data, SBS_Mutations)

方案2：dataclass 实现方案 #

如果一定要用dataclass，标准库dataclass既不支持特殊字符作为属性名，也不支持键别名映射，推荐用Pydantic实现的dataclass，原生支持别名配置、自动运行时校验，不需要手写重复的转换逻辑：

from pydantic.dataclasses import dataclass
from pydantic import Field
import yaml

@dataclass
class SBSMutation:
    # 定义合法标识符作为属性名，通过alias绑定YAML中的特殊字符键
    c_agt: str = Field(alias="C>A/G>T")
    c_ggc: str = Field(alias="C>G/G>C")
    c_tga: str = Field(alias="C>T/G>A")
    t_aat: str = Field(alias="T>A/A>T")
    t_cag: str = Field(alias="T>C/A>G")
    t_gac: str = Field(alias="T>G/A>C")

@dataclass
class YamlConfig:
    items: SBSMutation

# 加载YAML后直接传入原始字典即可自动完成解析、类型校验
with open("mutations.yaml", "r", encoding="utf-8") as f:
    raw_data = yaml.safe_load(f)
config = YamlConfig(**raw_data)

# 访问时用提前定义的合法属性名即可
print(config.items.c_agt)

如果不想引入第三方依赖，就需要手动在标准库dataclass的__init__方法中实现键名映射和类型校验，代码冗余度很高，不推荐使用。

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