深入理解 Python 的 __class_getitem__ 方法（打造支持泛型的自定义类）

为什么需要 __class_getitem__？

随着 Python 类型提示（Type Hints）在现代 Python 开发中的普及，开发者希望自己的自定义类也能像内置容器（如 list、dict）一样支持泛型标注。例如：

from typing import Listdef process(items: List[int]) -> None:    ...

在 Python 3.9+ 中，甚至可以直接写成 list[int]。为了让自定义类也能这样写（如 MyContainer[str]），就需要实现 __class_getitem__。

基础示例：让你的类支持下标

下面是一个最简单的例子，展示如何为自定义类添加 __class_getitem__ 方法：

class MyList:    def __class_getitem__(cls, key):        print(f"类 {cls.__name__} 被索引，参数为: {key}")        return cls  # 通常返回自身或一个新的泛型版本# 使用方式MyList[int]  # 输出: 类 MyList 被索引，参数为: <class 'int'>

注意：__class_getitem__ 是一个类方法，第一个参数是 cls（代表类本身），第二个参数是方括号中的内容（可以是单个类型，也可以是元组）。

实战：构建一个泛型容器类

现在我们来创建一个更实用的例子——一个支持类型提示的栈（Stack）类：

from typing import TypeVar, GenericT = TypeVar('T')class Stack(Generic[T]):    def __init__(self) -> None:        self._items: list[T] = []    def push(self, item: T) -> None:        self._items.append(item)    def pop(self) -> T:        return self._items.pop()    def __class_getitem__(cls, key):        # 实际上，继承 Generic 后，__class_getitem__ 已自动提供        # 但我们可以自定义行为        print(f"创建泛型栈: Stack[{key}]")        return super().__class_getitem__(key)# 使用stack: Stack[int] = Stack()stack.push(42)# stack.push("hello")  # 类型检查器会报错

在这个例子中，我们通过继承 Generic[T] 自动获得了对泛型的支持。但如果你不想依赖 typing.Generic，也可以手动实现 __class_getitem__ 来模拟类似行为（虽然不推荐用于生产环境，因为会失去静态类型检查的优势）。

注意事项与最佳实践

• ✅ 不要混淆：__class_getitem__ 用于类，__getitem__ 用于实例。
• ✅ 在大多数情况下，应优先使用 typing.Generic 来实现泛型，而不是手动实现 __class_getitem__。
• ✅ __class_getitem__ 主要用于**类型提示和注解**，不会影响运行时行为（除非你显式利用它）。
• ✅ 如果你正在开发库（library），为你的容器类添加 __class_getitem__ 可以提升用户体验，使其符合 Python 的惯用法。

总结

通过本文，你应该已经掌握了 Python __class_getitem__ 方法的核心概念和使用方式。它是实现 Python 泛型类 的关键一环，也是现代 Python 类型系统的重要组成部分。无论你是初学者还是有经验的开发者，理解这个魔术方法都能帮助你写出更清晰、更安全、更具表达力的代码。

记住：类型提示不是强制的，但它们能极大提升代码可读性和可维护性。而 __class_getitem__ 正是让自定义类融入这一生态的桥梁。