Python如何实现包含自身类型的递归列表类，导入annotations仍无效？

现有代码的运行时可用性 #

你贴出的代码在运行时本身是可以正常工作的：继承List[Union[A, AList]]本质还是继承了Python内置的list类，所有append、extend、__iter__等原生方法都可以正常调用，你也可以直接在类中添加自定义方法，样例运行代码如下：

from __future__ import annotations
from typing import Union, List

class A:
    pass

class AList(List[Union[A, AList]]):
    # 自定义递归统计A实例数量的方法示例
    def count_a(self) -> int:
        total = 0
        for item in self:
            if isinstance(item, A):
                total += 1
            else:
                total += item.count_a()
        return total

# 功能测试
a1 = A()
sub_alist = AList([A(), A()])
main_alist = AList([a1, sub_alist])

print(main_alist.count_a()) # 输出3，自定义方法正常运行
main_alist.append(A())
print(main_alist.count_a()) # 输出4，原生append方法正常生效

你遇到的"无法生效"问题，大概率是静态类型检查器（如mypy、pyright）没有正确识别递归类型，无法提供类型提示和校验。

支持静态类型检查的正确写法 #

如果需要让类型检查器正确识别递归的元素类型规则，需要显式声明递归类型变量，写法如下：

from __future__ import annotations
from typing import TypeVar, Union, List

class A:
    pass

# 声明递归类型变量
AListItem = TypeVar("AListItem", bound=Union[A, "AList"])

class AList(List[AListItem]):
    def count_a(self) -> int:
        total = 0
        for item in self:
            if isinstance(item, A):
                total += 1
            else:
                # 类型检查器会正确识别item为AList类型，推导count_a方法存在
                total += item.count_a()
        return total

如果使用Python 3.10+，可以用更简洁的并集符号替代Union：

AListItem = TypeVar("AListItem", bound=A | "AList")

Python 3.9+也可以直接用内置list替代typing.List做基类。

泛型类型标注的作用 #

你问的List[Union[A, AList]]写法的实际作用，分两种场景：

• 运行时场景：无任何实际作用。Python的泛型参数属于类型标注范畴，运行时会被完全擦除，List[Union[A, AList]]和普通list的运行时行为完全一致，不会自动做元素类型校验，你往实例中插入任意类型的元素都不会触发运行时报错。
• 静态检查场景：有明确实际作用。配合类型检查器和IDE，可以实现：
  • 调用append、insert、extend等修改方法时，自动校验传入参数的类型，非A/AList类型的参数会被标记为类型错误
  • 遍历元素时，IDE会自动提示元素的可选类型和对应方法，提升编码效率
  • 自定义方法的类型推导更准确，提前避免类型相关的隐性bug

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