Inference bug when subclassing a parameter?

[Chris Wesseling (CharString)]

Code sample in pyright playground

def decorate_cls[T](cls: type[T]) -> type[T]:
    class SubClass(cls):
        pass
    # assert issubclass(SubClass, cls)  # reportReturnType without this guard
    return SubClass

Is this a bug? Or is this because cls is a term?

[Aymen Hmaidi (aymenhmaidiwastaken)]

Your own guess is the answer — it's because cls is a value, not a static type. Not a bug so much as an unavoidable consequence of that.

When the base in a class statement is a variable, pyright still creates a nominal class for SubClass, but it has no way to put T in its MRO. So:

def decorate_cls[T](cls: type[T]) -> type[T]:
    class SubClass(cls):
        pass
    reveal_type(SubClass)      # type[SubClass]
    return SubClass            # error: type[SubClass] not assignable to type[T@decorate_cls]

SubClass is just type[SubClass]. There's no recorded relationship to T at all, so the return can't check. Contrast a static base, which does carry the relationship and needs no help:

class Concrete: pass

def concrete_case() -> type[Concrete]:
    class Sub(Concrete):
        pass
    return Sub                 # fine

And the reason your issubclass guard fixes it is that it's doing real narrowing rather than just silencing something:

assert issubclass(SubClass, cls)
reveal_type(SubClass)          # type[<subclass of SubClass and object*>]*

issubclass() narrowing synthesizes an intersection, and that synthesized type does satisfy type[T]. So the assert isn't a workaround bolted on — it supplies the fact pyright couldn't derive, and it's checked at runtime, which is more than you get from the alternative:

return cast(type[T], SubClass)   # also silences it, but proves nothing

Between the two I'd keep the assert. It costs one cheap call per decoration, and if someone later passes something that breaks the assumption you get a real failure instead of a wrong type quietly propagating.

Worth knowing the type() form has the same problem, in case you were considering it as a way around:

def decorate_type_call[T](cls: type[T]) -> type[T]:
    return type("SubClass", (cls,), {})   # error: type[SubClass] not assignable to type[T]

Same cause — the bases are a runtime tuple, so there's nothing static to record.

The general shape of it: a class statement with a dynamic base is one of the places where the static model genuinely can't follow what the runtime does, so the type system needs you to assert the connection. issubclass is the honest way to do that.