python / python/cpython

Clarifying documentation of typing.Set

Offen
#93,579 4 Kommentare 1 Reaktion 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

3.10 3.11 3.12 docs topic-typing
Vorherrschende Sprache
Python
Sterne
77.2k
Forks
36k
PR-Merge-Kennzahlen
PR-Kennzahlen ausstehend

Beschreibung

Documentation

Edit: I added some more clarification.

Documentation of typing.Set is not entirely clear

The typing module's documentation currently requires two hops when the reader looks up typing.Set.

  1. In the docstring of typing.Set it states "To annotate arguments it is preferred to use an abstract collection type such as AbstractSet." This is referring to typing.AbstractSet
  2. Docstring of typing.AbstractSet says that it is deprecated and refers the reader to collections.abc.Set, which has no docstring of its own (it is grouped together with the docstring of collections.abc.MutableSet.
    I feel we can prevent these two hops i.e. typing.Set --> typing.AbstractSet --> collections.abc.Set and direct the reader to the final destination i.e. typing.Set -> collections.abc.Set.

Suggested change

  1. typing.Set should say something like --

"To annotate arguments it is preferred to use an abstract collection type such as collections.abc.Set.
"To annotate everything else, the use of typing.Set is deprecated since version 3.9: builtins.set now supports []. See PEP 585 and Generic Alias Type"

  1. Docstring of typing.AbstractSet is fine as it is.
  2. collections.abc.Set should say something like --

"Use this to annotate arguments. For all other annotations, use builtins.set, which now supported []. See PEP 585 ...

Other generic alias types like List, Tuple, FrozenSet etc. probably could use a similar change (IF others agree that this is something that needs to changed at all.)

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Beginnen Sie mit den Docstrings für typing.Set und collections.abc.Set und vergleichen Sie anschließend die zugehörige Dokumentation zu generischen Aliasen sowie die Hinweise in PEP 585. Als erledigt gilt die Aufgabe, wenn die Dokumentation Leser von typing.Set ohne den zusätzlichen Zwischenschritt zu collections.abc.Set weiterleitet und klar erklärt, wann builtins.set verwendet werden sollte.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
2/5
Geschätzter Aufwand
1-3 Stunden
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.