类变量嵌套引用TypeAlias时mypy报'Name未定义'错误求助

你遇到的问题是：代码在Python运行时可正常执行，但mypy静态检查时会报错Sub.sub.alias未定义，替换为Sub.alias则能通过检查。核心原因是mypy对类型注解中链式类属性的解析逻辑和Python运行时的动态属性查找不一致。

具体原因 #

1. Python运行时是动态解析属性：Sub.sub指向Top类，后续访问Top.alias自然能拿到int，因此运行无问题。
2. mypy静态检查的局限性：对于Sub.sub.alias这种嵌套类属性访问，它不会自动追踪Sub.sub对应的类对象，也就无法识别alias是一个TypeAlias。而Sub.alias是子类继承自父类的类属性，mypy能直接识别其作为类型别名的身份。

可行解决办法 #

• 方案1：直接使用Top.alias
  既然Sub.sub本质就是Top类，直接写Top.alias更直观，mypy也能正确识别：

  # pkg/module.py
  from .types import Sub, Top
  
  def func(a: Top.alias):
      pass
  

• 方案2：使用字符串形式的延迟注解
  mypy支持字符串类型注解，会在后期解析阶段处理，可绕过静态检查的限制：

  # pkg/module.py
  from .types import Sub
  
  def func(a: "Sub.sub.alias"):
      pass
  

• 方案3：给Sub.sub添加明确类型标注
  在types.py中为sub属性标注类型，让mypy明确它指向Top类：

  # pkg/types.py
  from typing import TypeAlias, Type
  
  class Top:
      alias: TypeAlias = int
  
  class Sub(Top):
      sub: Type[Top] = Top  # 添加Type[Top]类型标注
  

  完成后再使用Sub.sub.alias，mypy就能正确识别该类型别名。

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