python / python/cpython

`Protocol` should be documented as using `ABCMeta` as metaclass

Offen
#127,677 1 Kommentar 2 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

docs topic-typing
Vorherrschende Sprache
Python
Sterne
77.2k
Forks
35.9k
PR-Merge-Kennzahlen
PR-Kennzahlen ausstehend

Beschreibung

Documentation

Came up in #127648.

Currently the documentation for typing.Protocol doesn't mention that Protocol has ABCMeta in its metaclasses (indirectly via _ProtocolMeta) and that its methods can (should?) be marked with @abstractmethod. In fact, neither the string "ABCMeta" nor "abstractmethod" appear in the documentation for the typing module.

I also suggest to add @abstractmethod to the examples using a Protocol as that is probably a best practice.

Finally, the documentation for Protocol suggests to see PEP 544 for more details. I don't think this is particularly helpful. All information relevant for users should be in the main documentation. PEP 544 should only be suggested as a historical document. (And I don't suggest to directly link to the typing spec, either, although a general link at the top of the page would be useful.)

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

Beginne mit der im Issue verlinkten Dokumentation zu typing.Protocol und vergleiche ihre Hinweise mit PEP 544. Überprüfe die Protocol-Beispiele und -Erklärungen hinsichtlich der angeforderten Abdeckung von ABCMeta, abstractmethod und Referenzen. Die Aufgabe gilt als erledigt, wenn die relevanten nutzerseitigen Details dokumentiert sind und die PEP-Referenz als historischer Kontext eingeordnet ist.

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
45/100

Neue Issues direkt in Ihr Postfach

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