python / python/mypy

Documentation needs a glossary

Offen
#12,888 1 Kommentar 5 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

documentation feature
Vorherrschende Sprache
Python
Sterne
20.6k
Forks
3.3k
PR-Merge-Kennzahlen
PR-Kennzahlen ausstehend

Beschreibung

Feature

I've realized lately that I lack a clear set of terms to discuss many typing concepts with my team, and I think the community as a whole suffers from this as well.

examples:

  1. how do we describe a generic class with a type var instead of a concrete type? e.g. Foo[T]. abstract generic? unparameterized generic? just plain "generic"?
  2. how do we describe a generic class with a concrete type? e.g. Foo[int] concrete generic? parameterized generic?
  3. what is the verb used to describe the act of converting a generic between these two states? parameterizing?
  4. how do we describe a generic class with more than one TypeVar?
  5. I think it's clear that TypeVar('T', bound=...) can be described as a "bound type var", but how do we describe a TypeVar of the form TypeVar('T', int, float)?

We should be able to combine terms to form a clear taxonomy, for example:

T = TypeVar("T", bound=A)

class Foo(Generic[T]):
     pass

FooB = Foo[B]

Foo is a "bound unparameterized user generic".
FooB is a "parameterized user type alias".

etc.

Pitch

I've looked around in the mypy documentation for clues to these questions and not found anything very definitive. In the absence of an authoritative source on this subject, members of the community stumble over these concepts in team meetings, github issues, and in the names and documentation of our python functions.

Thanks for reading!

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 damit, die mypy-Dokumentation auf bestehende Terminologie zu Generics und TypeVars zu prüfen, und vergleiche sie anschließend mit den Beispielen im Issue. Die Arbeit ist abgeschlossen, wenn ein maßgebliches Glossar konsistente Begriffe für die aufgeführten Generic- und TypeVar-Fälle definiert und im gesamten Dokumentationsbestand des Projekts verwendet werden kann.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Ruhig
Klarheit
Muss geklärt werden
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

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