Skip to content

Explain generic Protocol[T1, T2, ...] shorthand in Mypy docs #12047

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

Conversation

posita
Copy link
Contributor

@posita posita commented Jan 23, 2022

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.

@posita
Copy link
Contributor Author

posita commented Jan 23, 2022

make -C docs clean linkcheck returns no errors for generics. Screenshot of updated section built with make -C docs clean html:

Screen Shot 2022-01-23 at 14 30 20

FWIW, I'm not married to the wording. I'm open to truncating the example syntax as well. (The source material from PEP 544 is shorter.)

@JelleZijlstra
Copy link
Member

Yes, I'd suggest removing all the ... and using only a single TypeVar. The ... makes it look like this is about variadics.

@posita
Copy link
Contributor Author

posita commented Jan 23, 2022

I tried three variants, for fun:

Screen Shot 2022-01-23 at 15 08 47

Screen Shot 2022-01-23 at 15 09 18

Screen Shot 2022-01-23 at 15 09 50

@JelleZijlstra
Copy link
Member

Thanks! I like the second one best: it makes it explicit that this applies to class declarations, but without the distracting ....

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.
@posita posita force-pushed the posita/0/fix-generic-protocols-docs branch from a9dce49 to c53e233 Compare January 24, 2022 00:22
@posita
Copy link
Contributor Author

posita commented Jan 24, 2022

Done.

@97littleleaf11 97littleleaf11 merged commit af366c0 into python:master Jan 24, 2022
@posita posita deleted the posita/0/fix-generic-protocols-docs branch January 24, 2022 14:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants