Python嵌套类互相引用报错：NameError: DatasetController未定义

问题原因 #

在定义DatasetInfoStructure时，外层类DatasetController还未完成定义，直接使用DatasetController.DatasetItemStructure会触发NameError——Python解释器此时还不认识DatasetController这个名字。

解决方案 #

方法1：使用字符串字面量做前向引用 #

Python 3.7+支持用字符串形式的类型提示解决前向引用问题，3.11版本可直接使用：

from typing import TypedDict, List, Dict

class DatasetController:
    class DatasetItemStructure(TypedDict):
        files: List[str]
        concatenated: str

    class DatasetInfoStructure(TypedDict):
        base_path: str
        qr_code_samplerate: int
        items: Dict[str, "DatasetItemStructure"]  # 用字符串引用同层级嵌套类

也可以写全路径字符串"DatasetController.DatasetItemStructure"，效果一致。

方法2：将TypedDict移到外层类定义 #

若不需要严格嵌套结构，可把两个TypedDict移到外层，引用更直接：

from typing import TypedDict, List, Dict

class DatasetItemStructure(TypedDict):
    files: List[str]
    concatenated: str

class DatasetInfoStructure(TypedDict):
    base_path: str
    qr_code_samplerate: int
    items: Dict[str, DatasetItemStructure]

class DatasetController:
    # 编写类的其他逻辑
    pass

方法3：使用__future__注解（兼容旧版本可选） #

如果需要兼容Python 3.7之前的版本（3.11版本可忽略），可导入annotations：

from __future__ import annotations
from typing import TypedDict, List, Dict

class DatasetController:
    class DatasetItemStructure(TypedDict):
        files: List[str]
        concatenated: str

    class DatasetInfoStructure(TypedDict):
        base_path: str
        qr_code_samplerate: int
        items: Dict[str, DatasetController.DatasetItemStructure]

导入后所有类型注解会被当作字符串处理，直到运行时才解析，避免定义时的NameError。

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