本文介绍在使用 mypy 类型检查时，如何正确注解类级别的静态变量（而非实例变量），避免出现 “Access to generic instance variables via class is ambiguous” 报错，推荐使用 ClassVar 配合前向引用。
本文介绍在使用 mypy 类型检查时，如何正确注解类级别的静态变量（而非实例变量），避免出现 “access to generic instance variables via class is ambiguous” 报错，推荐使用 `classvar` 配合前向引用。
当在类中定义一个需在类层级直接赋值的静态变量（如 A.B = A()），并尝试用 Self 作为其类型注解时，mypy 会报错：
Access to generic instance variables via class is ambiguous
这是因为 Self 是为实例方法和实例属性设计的类型变量，语义上代表“当前实例的类型”，而静态变量属于类对象本身，与具体实例无关——Self 在此上下文中缺乏明确绑定目标，导致类型检查器无法推断。
✅ 正确做法：使用 ClassVar + 前向引用
最规范、语义清晰且被 mypy 完全支持的方式是：
from typing import ClassVar
class A:
B: ClassVar['A'] # 明确声明为类变量，类型为 A（前向引用）
A.B = A() # ✅ 合法赋值-
'A'是前向引用（forward reference）：因类A尚未完全定义完毕，直接写A会导致 NameError，故用字符串字面量形式延迟解析； -
ClassVar['A']明确告诉类型检查器：-
B是类变量（不可通过实例修改，如a = A(); a.B = ...会被 mypy 报错）； - 其类型为
A，且该类型在运行时可通过A.B访问。
-
⚠️ 其他可行但不推荐的方式
-
仅用字符串前向引用（无
ClassVar）：class A: B: 'A' A.B = A()虽能通过 mypy 检查，但失去了“静态性”语义约束：此时
A().B = ...不会报错，易引发逻辑错误。 避免使用
Self注解静态变量Self应严格用于实例方法返回值、__new__/__init__参数或实例属性（如链式调用def clone(self) -> Self:）。将其用于类变量属于类型语义误用。
? 验证效果
在 mypy playground 中测试上述 ClassVar 方案，mypy 将静默通过；若尝试 A().B = A()，则会提示：
error: Cannot assign to class variable "B" through instance
这正是我们期望的强约束行为。
✅ 总结：对类级静态变量，请始终优先使用 ClassVar[...] 并配合前向引用（字符串形式），既满足类型安全，又准确表达设计意图。
