当类属性的类型注解使用 A | None 且属性名与外部类名同为 A 时，Python 会因作用域绑定顺序错误将 A 解析为尚未完成赋值的局部变量（即 None），导致 None | None 运行时报错。
当类属性的类型注解使用 `a | none` 且属性名与外部类名同为 `a` 时，python 会因作用域绑定顺序错误将 `a` 解析为尚未完成赋值的局部变量（即 `none`），导致 `none | none` 运行时报错。
在 Python 中，类定义体是一个独立的作用域（namespace），其内部的赋值语句会按顺序执行，并在类命名空间中动态绑定名称。关键在于：类型注解本身不参与运行时求值，但当注解中出现名称且该名称恰好在当前类作用域中已被声明（即使尚未完成赋值），Python 会优先解析为当前作用域的局部绑定。
考虑如下复现代码：
class A:
pass
class B:
A: A | None = None # ❌ TypeError: unsupported operand type(s) for |: 'NoneType' and 'NoneType'表面上看，A | None 是一个类型表达式（PEP 604 风格联合类型），理应引用全局定义的类 A。但实际执行流程是：
- 解析 A: 时，A 被注册为类 B 的局部变量名；
- 在对 A | None 求值前，A 已被绑定到右侧默认值 None（因为赋值语句尚未完成，但名称已提前声明）；
- 因此 A | None 实际等价于 None | None，而 NoneType 不支持 | 运算符，触发 TypeError。
✅ 正确写法有以下几种：
立即学习“Python免费学习笔记（深入）”；
-
重命名属性（推荐）：避免与外部类名冲突
class B: a_instance: A | None = None # ✅ 清晰、无歧义 -
显式使用模块限定名：强制引用全局作用域
class B: A: __main__.A | None = None # ✅ 假设 A 定义在 __main__ 模块中 # 或（更通用）： from typing import TYPE_CHECKING if TYPE_CHECKING: from __main__ import A # 仅用于类型检查，不影响运行时 class B: A: A | None = None # ✅ 在 TYPE_CHECKING 下安全解析 -
延迟注解（字符串字面量）：完全规避运行时求值
class B: A: "A | None" = None # ✅ 注解作为字符串，不触发 `|` 运算
⚠️ 注意事项：
- 此问题仅在属性名与外部类型名完全相同时触发，与 Union[A, None] 写法无关（Union 是函数调用，不涉及 | 运算符重载）；
- Python 3.12+ 引入了 typing.Required/typing.NotRequired 等新特性，但该作用域规则未改变；
- 使用 from __future__ import annotations（PEP 563）可全局启用延迟注解，是现代 Python 项目的最佳实践，能彻底避免此类问题并提升启动性能。
总结：这不是类型系统的缺陷，而是 Python 作用域与赋值语义的自然结果。理解“类体即执行上下文”这一本质，就能预见并规避此类陷阱——永远避免在类内使用与外部类型同名的属性标识符，或主动采用字符串化注解与 __future__ 导入。
