This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author pxeger
Recipients docs@python, pxeger
Date 2021-10-03.13:12:32
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1633266753.15.0.403359406575.issue45352@roundup.psfhosted.org>
In-reply-to
Content
Currently the documentation for the generic forms (e.g. what the parameters in square brackets mean) of standard collections (e.g. collections.abc.Generator), is still on the typing page (https://docs.python.org/3.10/library/typing.html#typing.Generator).

This is from before PEP 585 was implemented, which deprecated the ones in typing in favour of the aliases in collections.abc. The documentation for these should be moved, or at least linked to, in the collections.abc page. The same applies to builtin types like list which can now also be directly parameterised.

In the case of Generator, for example, the text at https://docs.python.org/3.10/library/typing.html#typing.Generator, "A generator can be annotated...", should be moved to 
https://docs.python.org/3.10/library/collections.abc.html#collections.abc.Generator.

I chose Generator as an example, because it has three parameters YieldType, SendType, ReturnType whose order I can't remember and need to look up. For some types, such as Iterable, the meaning of the parameter is quite straightforward, so little documentation is needed (so https://docs.python.org/3.10/library/typing.html#typing.Iterable just says "A generic form of https://docs.python.org/3.10/library/collections.abc.html#collections.abc.Iterable"), but there should still be a note on the collections.abc page that it can be parameterised.

Perhaps there should also be a message saying "new in version 3.9: this can now be parameterised" on each ABC collection.

I can see that it might not be desirable to have this information scattered across other pages, because it is fundamentally about typing and pretty unrelated to builtin documentation, so it may be preferable to just link to the typing page rather than move the text. But since the old generics are deprecated, if they are removed, the documentation must be preserved.
History
Date User Action Args
2021-10-03 13:12:33pxegersetrecipients: + pxeger, docs@python
2021-10-03 13:12:33pxegersetmessageid: <1633266753.15.0.403359406575.issue45352@roundup.psfhosted.org>
2021-10-03 13:12:33pxegerlinkissue45352 messages
2021-10-03 13:12:32pxegercreate