List generic arguments for `collections.abc` base classes in documentation
Dieses Issue hat noch niemand übernommen.
- Vorherrschende Sprache
- Python
- Sterne
- 77.2k
- Forks
- 35.9k
- PR-Merge-Kennzahlen
- PR-Kennzahlen ausstehend
Beschreibung
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.
Beitragsleitfaden
Erste Schritte
- Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
- Forke das Repository und arbeite in einem Branch.
- Öffne einen Pull Request, der die Issue-Nummer nennt.
Rechercherichtung
Beginne mit der Durchsicht der vorhandenen Dokumentation zu collections.abc, der Auflistungen generischer Argumente für veraltete typing-Aliase und der zugehörigen Diskussionen in #123544 und #123523. Füge für die relevanten generischen Aliase konsistente Type parameters-Abschnitte mit ihren Argumenten und Beziehungen hinzu und überprüfe, dass Benutzer die Informationen über die collections.abc-Einträge finden können.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- python
- Bereich
- documentation
- Issue-Typ
- Dokumentation
- Schwierigkeit
- 3/5
- Geschätzter Aufwand
- 1-2 Tage
- Aktivitätsstatus
- Veraltet
- Klarheit
- Größtenteils klar
- Anfängerfreundlichkeit
- 35/100