__class_getitem__

__class_getitem__(cls, item)

Returns: Any · Added in vPython 3.7 · Updated March 23, 2026 · Dunder Methods

class-method subscription generic-types typing

__class_getitem__ is a class method that gets called when you use a class object as a subscript, such as SomeClass[param]. It was introduced in Python 3.7 as part of the implementation of generic type aliases in the typing module.

How it differs from `getitem`

__getitem__ handles subscription on instances of a class, while __class_getitem__ handles subscription on the class itself. This distinction matters:

class MyContainer:
    def __getitem__(self, key):
        return f"instance getitem: {key}"

    def __class_getitem__(cls, item):
        return f"class getitem: {item}"

obj = MyContainer()
print(obj["key"])         # instance getitem: key
print(MyContainer["key"])  # class getitem: key

Calling MyContainer["key"] invokes __class_getitem__, while obj["key"] invokes __getitem__.

The typing module and GenericAlias

The most common use of __class_getitem__ is in the typing module, which uses it to create GenericAlias objects. When you write list[int] or dict[str, int], Python calls list.__class_getitem__(int) and dict.__class_getitem__((str, int)), which return generic alias objects.

# list[int] returns a GenericAlias
alias = list[int]
print(alias)
# Output: list[int]
print(alias.__origin__)
# Output: <class 'list'>
print(alias.__args__)
# Output: (int,)

Implementing custom generic classes

You can define __class_getitem__ in your own classes to create type-level subscription behavior. Note that __class_getitem__ is implicitly a classmethod — you do not need the @classmethod decorator.

class Repository:
    def __class_getitem__(cls, item):
        # Return a configured class or descriptor
        return f"{cls.__name__}[{item.__name__}]"

result = Repository[dict]
print(result)
# Output: Repository[dict]

If your implementation cannot handle a given type, return NotImplemented to allow Python to continue the method resolution chain.

Return value behavior

__class_getitem__ does not require that the returned object be an instance of the class. The method can return any value, including instances of other types, strings, or descriptors. The return value depends entirely on the intended semantics of your class.

Availability note

__class_getitem__ is defined on object and returns NotImplemented by default. This means all classes inherit a basic implementation. Subclasses only need to define it if they want custom subscription behavior at the class level.

Relationship with `getitem`

When an instance is subscripted, Python first calls __getitem__ on the instance. __class_getitem__ is completely separate and only participates when the class itself appears in the subscript expression. Mixing both in a class does not cause ambiguity because they operate on different targets.

class Dual:
    def __getitem__(self, key):
        return "instance path"

    def __class_getitem__(cls, item):
        return "class path"

print(Dual()["x"])     # instance path
print(Dual["x"])       # class path

Summary

Aspect	`__class_getitem__`	`__getitem__`
Operates on	Class (`cls`)	Instance (`self`)
Triggered by	`MyClass[param]`	`instance[param]`
Added in	Python 3.7	Python 1.0
Default behavior	Returns `NotImplemented`	Raises `TypeError`

How it differs from __getitem__