Repository navigation
List generic arguments for collections.abc base classes in documentation #123583
Description
Documentation
When #123544 lands, we'll have PEP585-related documentation spread even further than before. Deprecated aliases in typing correctly list the generic arguments, but are otherwise undocumented - all such entries boil down to "deprecated in favour of collections.abc.X".
Several relevant changes were discussed along #123523.
There's no direct way for a user to find generic parameters of collections.abc.Generator - they are listed for typing.Generator and in "annotating generators and coroutines" section in typing docs (the latter linked from collections.abc.Generator, though).
I'm certain that generic arguments represent an essential part of class' "signature" - basic amount of information we need to see to use it somehow.
However, collections.abc is not really a type-hinting module, hence providing those signatures there directly can add too much cognitive load.
As of now, my best suggestion is to introduce "Type parameters" section for each generic alias there, like this:
.. class:: Mapping
MutableMapping
ABCs for read-only and mutable :term:`mappings <mapping>`.
Type arguments:
* ``Mapping[KT, VT_co](Collection[KT])``
* ``MutableMapping[KT, VT](Mapping[KT, VT])``cc @AA-Turner and @AlexWaygood - we started this discussion in the PR above.
Activity
AlexWaygood commentedon Sep 6, 2024
From a typing perspective, I fully agree -- but I'm still a little uncertain about including so many complex type signatures directly in the
collections.abcdocs. It might be good to open a discussion on Discourse and see if we can brainstorm ways of presenting this information in an accessible way, so that people who aren't interested in typing (or, if they're beginners, possibly aren't even aware of typing) don't get terrified by all this information in thecollections.abcdocs.JelleZijlstra commentedon Sep 25, 2024
I feel we should add this information to the
collections.abcdocs. While not all users of thecollections.abcclasses need the type information, a large proportion of users do. The collections.abc docs are fairly brief and a mention of the type parameters would not be overwhelming.AlexWaygood commentedon Sep 25, 2024
To be clear, I don't strongly object to adding this information to the
collections.abcdocs... I'm more worried that this might end up being a controversial change that other people might object to, which is why I suggested increasing the visibility of the proposed change before doing it :-)