List generic arguments for `collections.abc` base classes in documentation
Personne n'a encore pris cette issue.
- Langage dominant
- Python
- Étoiles
- 77.2k
- Forks
- 35.9k
- Métriques de merge des PR
- Métriques de PR en attente
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.
Guide de contribution
Ouvrir le guide de contribution
Par où commencer
- Lisez l'issue en entier, puis le guide de contribution du projet.
- Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
- Forkez le dépôt et travaillez sur une branche.
- Ouvrez une pull request qui référence le numéro de l'issue.
Piste de recherche
Commencez par examiner la documentation existante de collections.abc, les listes d’arguments génériques pour les alias typing obsolètes et les discussions associées dans #123544 et #123523. Ajoutez des sections Type parameters cohérentes pour les alias génériques concernés, avec leurs arguments et leurs relations, et vérifiez que les utilisateurs peuvent trouver les informations à partir des entrées collections.abc.
Rédigé par le modèle d'indexation à partir du texte de l'issue.
Évaluation
- Stack technique
- python
- Domaine
- documentation
- Type d'issue
- Documentation
- Difficulté
- 3/5
- Temps estimé
- 1-2 jours
- Activité
- À l'abandon
- Clarté
- Plutôt claire
- Accessibilité débutants
- 35/100