New submission from Patrick Reader <pxe...@protonmail.com>:
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. ---------- assignee: docs@python components: Documentation messages: 403085 nosy: docs@python, pxeger priority: normal severity: normal status: open title: Move documentation for typed generic forms of standard collections to collections.abc type: enhancement _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue45352> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
