Python3.12+PEP695泛型子类方法注解检查报'T'未定义错误

核心原因 #

PEP 695 引入的新泛型语法（class Box[T]:）和旧版 TypeVar+Generic 存在本质的作用域差异：

• 旧版 TypeVar 是模块级全局变量，整个模块范围内都能访问；
• PEP 695 的泛型参数（比如 T）是类内部的局部作用域变量，仅在类定义的上下文里有效，装饰器所在的外部模块作用域根本看不到这个 T。

当父类用自定义装饰器包装方法时，装饰器生成的包装函数会保留原始方法的注解，但包装函数的定义作用域是装饰器所在模块，而非泛型类内部。调用 typing.get_type_hints 时，默认会在包装函数的作用域中查找 T，自然找不到，触发 NameError。

而移除装饰器时，get_type_hints 直接访问原始方法的作用域（泛型类内部），能正确找到 T；换回旧泛型语法时，TypeVar 是模块级的，装饰器所在作用域能访问到，所以不会报错。

解决方案 #

1. 调用 get_type_hints 时指定正确的作用域

用 functools.wraps 装饰包装函数（确保继承原始方法的注解），调用 get_type_hints 时显式传入泛型子类的作用域作为 globals 参数：

from typing import get_type_hints

# 传入子类的__dict__作为globals，让解析器在子类作用域找T
hints = get_type_hints(StringService.process, globals=StringService.__dict__)

子类已经将泛型参数 T 绑定为具体类型（比如 str），这样就能正确解析注解。

2. 修改装饰器，保留原始方法的作用域关联

不要手动复制或覆盖包装函数的 __annotations__，让 functools.wraps 自动继承原始方法的注解和作用域上下文：

import functools

def my_decorator(func):
    @functools.wraps(func)
    def wrapper(self, *args, **kwargs):
        return func(self, *args, **kwargs)
    # 不要手动修改__annotations__，依赖wraps自动处理
    return wrapper

这样包装函数的注解会和原始方法保持关联，get_type_hints 能正确追溯到泛型类的作用域。

3. 临时兼容方案：绑定泛型参数到模块作用域

如果暂时无法修改装饰器或调用逻辑，可以在泛型类定义时，把类内部的泛型参数显式赋值到模块作用域（不推荐长期使用，会污染全局作用域）：

from typing import TypeVar
# 模块级定义占位TypeVar
T = TypeVar('T')

class BaseService[T]:
    # 用类内部的T覆盖模块级T，兼容装饰器的作用域查找
    T = T
    @my_decorator
    def process(self, data: T) -> T:
        return data

这种方法本质是退回到旧泛型的作用域逻辑，仅作为临时过渡方案。

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