Python泛型类自引用触发NameError，但通过mypy类型检查的问题

问题场景 #

编写泛型类时，若方法参数或类属性使用自身类作为类型注解，代码能通过mypy静态类型检查，但直接运行Python解释器时会抛出NameError: name 'MyTestClass' is not defined。

最小复现代码 #

from typing import Generic, TypeVar

T = TypeVar("T")


class MyTestClass(Generic[T]):
    def __init__(self, val: T) -> None:
        self.val = val

    def self_referential_method(self, other: MyTestClass[T]) -> bool:
        return self.val == other.val


if __name__ == "__main__":
    print("Hello")
    a = MyTestClass[int](3)
    b = MyTestClass[int](2)
    print(a.self_referential_method(b))

检查与运行结果 #

• mypy类型检查：

mypy mydatastructure/
Success: no issues found in 2 source files

• Python运行报错：

python mydatastructure/mydatastructure.py 
Traceback (most recent call last):
  File "/home/jan/toy_projects/DataStructuresAndAlgorithms/python/mydatastructure/mydatastructure.py", line 7, in <module>
    class MyTestClass(Generic[T]):
  File "/home/jan/toy_projects/DataStructuresAndAlgorithms/python/mydatastructure/mydatastructure.py", line 11, in MyTestClass
    def self_referential_method(self, other: MyTestClass[T]) -> bool:
NameError: name 'MyTestClass' is not defined

期望兼容的扩展代码 #

用户同时需要支持包含自身类指针的场景：

class MyTestClass(Generic[T]):
    def __init__(self, val: T, next: Optional[MyTestClass[T]]) -> None:
        self.val = val
        self.next : Optional[MyTestClass[T]] = next

    def self_referential_method(self, other: MyTestClass[T]) -> bool:
        return self.val == other.val

错误原因 #

Python解释器在类定义过程中，类名MyTestClass还未被绑定到当前作用域，此时直接在方法参数或属性注解中使用该类名会触发NameError。而mypy作为静态类型检查器，支持前向引用（即允许引用尚未定义的名称），因此能通过检查。

解决方案 #

方案1：使用字符串字面量作为类型注解（兼容所有Python版本） #

将自引用的类型注解用字符串包裹，Python会在类定义完成后再解析该字符串：

from typing import Generic, TypeVar, Optional

T = TypeVar("T")


class MyTestClass(Generic[T]):
    def __init__(self, val: T, next: "Optional[MyTestClass[T]]") -> None:
        self.val = val
        self.next : "Optional[MyTestClass[T]]" = next

    def self_referential_method(self, other: "MyTestClass[T]") -> bool:
        return self.val == other.val

方案2：导入from __future__ import annotations（Python 3.7+） #

该导入会让Python延迟所有类型注解的求值，直到整个类定义完成后再处理，此时类名已经绑定到作用域：

from __future__ import annotations
from typing import Generic, TypeVar, Optional

T = TypeVar("T")


class MyTestClass(Generic[T]):
    def __init__(self, val: T, next: Optional[MyTestClass[T]]) -> None:
        self.val = val
        self.next : Optional[MyTestClass[T]] = next

    def self_referential_method(self, other: MyTestClass[T]) -> bool:
        return self.val == other.val

验证结果 #

修改后的代码运行不再报错，同时mypy类型检查依然能通过。

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