From c53e2337b9d0eccca5dc9ce8b82ccf2d6d2b734f Mon Sep 17 00:00:00 2001 From: Matt Bogosian Date: Sun, 23 Jan 2022 14:31:46 -0600 Subject: [PATCH] Explain generic `Protocol[T1, T2, ...]` shorthand in Mypy docs As far as I can tell, the nugget exposed by this commit lives only in PEP 544. This copies that nugget closer to where it is likely to be spotted by the intended audience. PEPs may not be accessible to customers who reasonably expect relevant information to be surfaced in featured documentation. Even if customers are aware of PEPs, they may not think to look there, and don't likely consider them primary sources. It is reasonable to assume that is the job of the docs, with PEPs capturing more esoteric nuances, rationales and other then-relevant details of decision-making, etc. It's also reasonable to expect that where further study may be helpful, links from relevant sections of primary sources to secondary materials like PEPs should exist. This commit fills in both gaps for the subject shorthand. --- docs/source/generics.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/generics.rst b/docs/source/generics.rst index 7e64aa181403..7730bd0e5c10 100644 --- a/docs/source/generics.rst +++ b/docs/source/generics.rst @@ -673,6 +673,10 @@ protocols mostly follow the normal rules for generic classes. Example: y: Box[int] = ... x = y # Error -- Box is invariant +Per :pep:`PEP 544: Generic protocols <544#generic-protocols>`, ``class +ClassName(Protocol[T])`` is allowed as a shorthand for ``class +ClassName(Protocol, Generic[T])``. + The main difference between generic protocols and ordinary generic classes is that mypy checks that the declared variances of generic type variables in a protocol match how they are used in the protocol