`TypeError` when omitting a `Protocol` type argument with default

[jorenham]

Bug report

Bug description:

This is as minimal as I was able to get the repro. I'm suppose it speaks for itself:

from typing import Generic, Protocol, TypeVar

T1 = TypeVar("T1")
T2 = TypeVar("T2", default=object)

class A(Protocol[T1]): ...
class B1(A[T2], Protocol, Generic[T1, T2]): ... # the workaround
class B2(A[T2], Protocol[T1, T2]): ... # the problem

B1[str] # ok
B2[str] # TypeError

on 3.13.5:

Traceback (most recent call last):
 File "/home/joren/huh.py", line 11, in <module>
 B2[str] # TypeError
 ~~^^^^^
 File "/home/joren/.pyenv/versions/3.13.5/lib/python3.13/typing.py", line 432, in inner
 return func(*args, **kwds)
 File "/home/joren/.pyenv/versions/3.13.5/lib/python3.13/typing.py", line 1242, in _generic_class_getitem
 args = prepare(cls, args)
TypeError: Too few arguments for <class '__main__.B2'>; actual 1, expected at least 2

on 3.14.0rc1:

Traceback (most recent call last):
 File "/home/joren/huh.py", line 11, in <module>
 B2[str] # TypeError
 ~~^^^^^
 File "/home/joren/.pyenv/versions/3.14.0rc1/lib/python3.14/typing.py", line 401, in inner
 return func(*args, **kwds)
 File "/home/joren/.pyenv/versions/3.14.0rc1/lib/python3.14/typing.py", line 1133, in _generic_class_getitem
 args = prepare(cls, args)
TypeError: Too few arguments for <class '__main__.B2'>; actual 1, expected at least 2

As the repro shows, the workaround is to parametrize an additional Generic instead of Protocol.

CPython versions tested on:

3.13, 3.14

Operating systems tested on:

Linux

Linked PRs

• gh-137191: Fix how type parameters are collected from Protocol and Generic bases with parameters #137281

[brianschubert]

cc @JelleZijlstra

[sobolevn]

This still happens on main. Thanks a lot for the report, I will take a look.

[sobolevn]

First debug findings:

from typing import Generic, Protocol, TypeVar

T1 = TypeVar("T1")
T2 = TypeVar("T2", default=object)

class A(Protocol[T1]): ...
class B2(A[T2], Protocol[T1, T2]): ... # the problem

print(B2.__parameters__) # (~T2, ~T1)

This looks like the main reason for this problem: T2 begins to be the first parameter and since we treat cases like this as impossible (parameter without a default can't follow a parameter with a default):

>>> from typing import Generic, Protocol, TypeVar
... 
... T1 = TypeVar("T1")
... T2 = TypeVar("T2", default=object)
... 
>>> class A(Generic[T2, T1]): ...
... 
Traceback (most recent call last):
 File "<python-input-1>", line 1, in <module>
 class A(Generic[T2, T1]): ...
 ~~~~~~~^^^^^^^^
TypeError: Type parameter ~T1 without a default follows type parameter with a default

We fail to do the propoper substitution.

There might be 2 possible solutions to this at least:

1. To reorder __parameters__ to be (T1, T2) and not (T2, T1) (my preference)
2. Raise TypeError in this case (we need a strong reasoning on why, though)

What do others think?

[jorenham]

I think it should not matter whether you're using subscripted Generic + Protocol or a subscripted protocol, so I suppose that'll be option 1 for me then.

[JelleZijlstra]

Thanks for the report and investigation!

This is a tough one because both options seem to break compatibility: we must either reorder the type parameters on the class or raise a TypeError where we currently don't.

What is the right behavior? The typing spec isn't very clear here, but the relevant rules are:

• If a class inherits from other generics, the order of the type parameter is the order in which they appear syntactically in the base class list (spec link: "Type variables are applied to the defined class in the order in which they first appear in any generic base classes")
• If Generic is present as a base class, the order of the arguments to Generic determines the order of the type parameters. I don't think the spec explicitly says this but it's how everything works. The mypy docs do say this explicitly.
• For Protocols, the spec says "Protocol[T, S, ...] is allowed as a shorthand for Protocol, Generic[T, S, ...]." That doesn't say anything about parameter order but it implies that if you inherit directly from Protocol[...], the arguments to Protocol determine the type parameter order.

So that strongly suggests that if there is an explicit Protocol[...] base class, the order of the arguments to Protocol should determine the type parameter order. Indeed, that's how type checkers behave (I tried mypy, pyright, and pyrefly):

from typing import ParamSpec, Protocol, TypeVar

T = TypeVar("T")
P = ParamSpec("P")

class P1(Protocol[T]):
 x: T

class P2(P1[T], Protocol[P, T]):
 y: T

x: P2[[], int] # OK
y: P2[int, []] # expect errors

This is how things should ideally work, but it's not how things work in CPython right now; the __parameters__ for the class above are (~T, ~P).

Is there any code that works right now (in the sense of not throwing errors at runtime) that would be broken if we fixed the parameter order?

[jorenham]

Thanks for the report and investigation!

Glad to be of help :)

---

Is there any code that works right now (in the sense of not throwing errors at runtime) that would be broken if we fixed the parameter order?

Hyrum's Law has an answer to that:

With a sufficient number of users of an API,
it does not matter what you promise in the contract:
all observable behaviors of your system
will be depended on by somebody.

Anyway, jokes aside, if such code were to exist I would expect to find it a project like beartype or pydantic.
So @leycec, @Viicos, do you expect that the change to __parameters__ that @JelleZijlstra suggested will break anything?

[leycec]

Fascinating! Sudoku has nothing on Python generics. If this isn't the Leibniz calculus of the QA world, I don't know what is.

@sobolevn and @JelleZijlstra have the right of it, as always. Please do reorder __parameters__ so as to reflect the spirit of the spec. If this breaks @beartype, that's absolutely fine. I never knew that users could explicitly order type parameters by intentionally re-subclassing Generic[...] and Protocol[...] in nested subclasses. That's... pretty clever API design, honestly.

It would be wonderful if somebody (who is not me, because nobody wants that kind of writing) could explicitly document this use case at the official typing module's documentation: e.g.,

class typing.Generic
Generic classes may explicitly order type parameters by intentionally re-subclassing Generic[...], for example:

class typing.Protocol(Generic)
Protocol classes may explicitly order type parameters by intentionally re-subclassing Protocol[...], for example:

Thanks so much for the hard investigative work, @jorenham. May your summer be blessed with no further bugs.

[Viicos]

do you expect that the change to __parameters__ that JelleZijlstra suggested will break anything?

It might be that it could break, but my personal take on such changes is that Pydantic is expecting them, and I'm generally sympathetic to any of these changes. If necessary, we can handle them downstream.

[JelleZijlstra]

Sounds like we should just fix it (though at this point, only in 3.15).