在 Python 类定义中，若属性名与外部已定义的类名相同，且其类型注解使用 | 运算符（如 A | None）并赋予默认值（如 = None），会导致 TypeError: unsupported operand type(s) for |: 'NoneType' and 'NoneType' —— 根本原因是名称绑定发生在类体执行时，属性名会提前遮蔽外部同名类，使类型表达式误将 None 当作左操作数参与 | 运算。
在 python 类定义中，若属性名与外部已定义的类名相同，且其类型注解使用 `|` 运算符（如 `a | none`）并赋予默认值（如 `= none`），会导致 `typeerror: unsupported operand type(s) for |: 'nonetype' and 'nonetype'` —— 根本原因是名称绑定发生在类体执行时，属性名会提前遮蔽外部同名类，使类型表达式误将 `none` 当作左操作数参与 `|` 运算。
这是 Python 类作用域与名称解析机制共同作用下的一个典型“陷阱”。关键在于：类体（class body）是一个可执行的作用域，其中所有赋值语句（包括带类型注解的属性声明）都会在类创建过程中实时执行，并立即绑定名称到当前类命名空间中。
考虑如下复现代码：
class A:
pass
class B:
A: A | None = None # ❌ 触发 TypeError表面看，A: A | None = None 是一条“类型注解 + 默认值”的声明。但 Python 解释器在执行 class B: 时，会逐行执行类体内的语句。当遇到 A: A | None = None 时，它实际按以下顺序处理：
- 先解析右侧表达式 A | None（为类型检查或运行时求值做准备）；
- 此时，A 尚未在 B 的局部命名空间中定义（因该行尚未完成执行），但 Python 会尝试在当前作用域链中查找 A；
- 然而——由于左侧标识符 A 出现在同一行的赋值目标位置，Python 的编译器（在 AST 构建阶段）已将 A 标记为 即将被定义的局部名，导致名称查找行为发生微妙变化；
- 更准确地说：在类体执行期间，对 A 的引用会优先匹配“正在被赋值的同名目标”，而此时该名尚未绑定到外部类 A，而是处于“未定义但已声明”的模糊状态；某些 Python 版本（尤其是 3.10+ 引入 | 作为类型联合运算符后）在求值 A | None 时，会错误地将 A 解析为 None（因后续 = None 赋值已隐式影响符号表），从而计算 None | None，最终触发 TypeError。
✅ 正确写法有多种，核心原则是避免名称冲突，确保类型表达式中的 A 明确指向模块级类：
立即学习“Python免费学习笔记（深入）”；
class A:
pass
class B:
# 方案1：重命名属性（推荐，语义清晰）
a_instance: A | None = None
# 方案2：使用字符串字面量延迟解析（PEP 563 启用后更安全）
A: "A | None" = None # ✅ 字符串注解不触发运行时求值
# 方案3：显式使用模块限定（适用于复杂嵌套）
from __future__ import annotations # 启用延迟注解求值（Python 3.7+）
A: A | None = None # ✅ 在启用了 annotations 的模块中，此写法安全⚠️ 注意事项：
- 此问题仅在启用运行时类型表达式求值时出现（如未启用 from __future__ import annotations，且 Python 版本
- 即使使用 typing.Union[A, None]，若 A 名称被遮蔽，同样可能出错（尽管 Union 是函数调用，行为略有不同）；
- 永远不要依赖“类型注解不执行”的假设：在未启用延迟注解的环境中，X | Y 是真实运算，会触发 __or__ 方法调用；
- 使用 mypy 或 pyright 等静态检查器时，它们通常基于 AST 分析，不受此运行时错误影响，但仍建议保持命名清晰以提升可维护性。
总结：这不是类型系统的缺陷，而是 Python 作用域规则与新语法（| 作为类型联合）相遇时的合理行为。解决方案很简单——遵守命名隔离原则：类属性名不应与所引用的类型名完全相同；或统一启用 from __future__ import annotations，让所有注解惰性化，从根本上规避运行时求值风险。
