Document that `inspect.isclass` returns False for `GenericAlias` instances

[RobertoPrevato]

Bug report

Bug description:

Hi
I am not sure if this is a bug, but I use the bug template because I couldn't find a better one to submit questions like this one.

The documentation says, "User-defined generic classes can be instantiated.".

import inspect
from typing import TypeVar, Generic

T = TypeVar("T")


class Node(Generic[T]):
    x: T  # Instance attribute (see below)

    def __init__(self, label: T | None = None) -> None:
        self.label = label


x = Node("")  # Inferred type is Node[str]
y = Node(0)  # Inferred type is Node[int]
z = Node()  # Inferred type is Node[Any]


# Also OK:
y = Node[int](0)


print(inspect.isclass(Node))  # True
print(inspect.isclass(Node[int]))  # False  (shouldn't this be True?)
print(inspect.isclass(Node[str]))  # False  (shouldn't this be True?)

In the example above, shouldn't calls such as inspect.isclass(Node[int]) return True, since they can be instantiated and used like normal classes?

CPython versions tested on:

3.13

Operating systems tested on:

Linux

[picnixz]

I would regard Node[int] as the specialization of a generic class (similar to specialization of a C++ template class or Java/TypeScript generics), hence a class. The docs also say (emphasis mine):

Note that the runtime type (class) of p and q is still just Node – Node[int] and Node[str] are distinguishable class objects, but the runtime class of the objects created by instantiating them doesn’t record the distinction.

So according to this, inspect.isclass() should indeed return True. However, at runtime, Node[int] is a GenericAlias instance so should it still be considered a class? I don't have an answer to this question but I'd like to point that changing the behavior of inspect.isclass may cause downstream issues where one would not expect to filter GenericAlias objects.

cc @JelleZijlstra

[AlexWaygood]

The behaviour here is correct. You can see #89828, and its many linked sub-issues, for the various bugs that can be caused if GenericAlias instances are considered exactly equivalent to classes at runtime.

I'd be open to making an improvement to the docs somewhere if the current docs are confusing, however!

[sobolevn]

I also agree that changing anything in inspect.is* can break a lot of code. And it is easier to adapt any checks in your own code: inspect.isclass(obj) or isinstance(obj, GenericAlias) - for example.

[picnixz]

I think we should improve the docs by saying that GenericAlias instances are not considered to be classes by inspect.isclass, although they behave as a class.

Note

For newcomers, they should update both the online docs (rst) and the docstring. If possible (and if this is not already the case), they could also add a test for that.