Python单文件两类互相类型注解报NameError解法及future注解弊端

这个报错的核心原因是Python执行类定义代码时，会立刻求值类体内的类型注解，当执行到BotData类里的__bots_data: BotsData行时，BotsData类还未完成定义，名字不存在于当前作用域，因此抛出NameError。由于两个类是循环引用关系，调换类的定义顺序无法解决问题，可通过以下两种方式修复：

• 方式1：文件顶部添加延迟注解导入
  在Python文件所有业务代码最前面加入from __future__ import annotations，该语句会让当前文件内所有类型注解不在定义时立刻求值，而是以字符串形式存储，待类型检查、手动解析时再匹配对应类对象，可直接解决循环引用的前向注解问题。
  注意需要补全原代码缺失的依赖导入，完整可运行代码如下：

  from __future__ import annotations
  from dataclasses import dataclass
  from typing import Dict, Union, Optional
  
  
  class BotData:
      """Class holding data of one specific bot"""
      common: dict
      users: Dict[Union[int, str], dict]
      __bots_data: BotsData
  
  
  @dataclass
  class BotsData:
      """Data of needed entities, None for no data or not used"""
      telegram: Optional[BotData]
      viber: Optional[BotData]
      vk: Optional[BotData]
      whatsapp: Optional[BotData]
      inter: Optional[dict]
  

• 方式2：将前向引用的类型注解写为字符串字面量
  如果不想引入全局的延迟注解配置，可以直接把还未定义的类型用引号包裹，Python识别到字符串形式的类型注解时，不会立刻在作用域查找对应名字，也能解决报错。仅需把BotData类里的对应行修改为：

  __bots_data: "BotsData"
  

  该方式仅修改单个注解的求值逻辑，不会影响文件内其他注解的行为，适合少量前向引用的场景。

这个方案虽然写起来简单，但存在几个实际使用中需要注意的问题：

• 运行时注解读取行为改变：添加该导入后，直接访问类或函数的__annotations__属性拿到的所有注解都是字符串，而非实际的类型对象。如果代码中有自定义的运行时类型校验、序列化/反序列化、参数自动转换逻辑，直接读取注解会拿到字符串导致逻辑失效，必须调用typing.get_type_hints()方法手动解析才能拿到真实类型对象。
• 第三方库兼容性风险：部分依赖运行时注解做逻辑处理的旧版本第三方库（比如早期v1版本的pydantic、部分老版本ORM、序列化插件）没有适配字符串形式的注解，直接读取__annotations__做逻辑判断时会出现识别失败、抛出异常的问题。
• 低版本Python存在边缘缺陷：Python 3.10之前的版本对延迟注解的支持不完全，在处理嵌套泛型、复杂类型别名、跨模块前向引用的场景时，偶尔会出现类型解析错误、和实际类型不匹配的bug，在3.10版本后相关逻辑才逐步稳定。
• 直接用注解做实例判断会报错：如果代码中直接拿注解里的类型作为isinstance()、issubclass()的判断参数，会因为传入的是字符串直接抛出类型错误，必须先完成类型解析才能正常使用。

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