python / python/cpython

List generic arguments for `collections.abc` base classes in documentation

Aperta
#123,583 3 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

docs topic-typing
Lingua principale
Python
Stelle
77.2k
Fork
35.9k
Metriche di merge delle PR
Metriche PR in attesa

Descrizione

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.

Guida per i contributori

Apri la guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Direzione di ricerca

Inizia esaminando la documentazione esistente di collections.abc, gli elenchi degli argomenti generici per gli alias typing deprecati e le discussioni correlate in #123544 e #123523. Aggiungi sezioni Type parameters coerenti per gli alias generici pertinenti, con i relativi argomenti e le relazioni, e verifica che gli utenti possano trovare le informazioni dalle voci di collections.abc.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
python
Ambito
documentation
Tipo di issue
Documentazione
Difficoltà
3/5
Tempo stimato
1-2 giorni
Stato di attività
Ferma
Chiarezza
Abbastanza chiara
Idoneità per principianti
35/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.