Zusammenfassung

PEP 484 führte Typ-Hinweise in Python ein, mit dem Ziel, die Typisierung schrittweise und einfach umsetzbar zu machen. Derzeit müssen Typinformationen manuell verteilt werden. Diese PEP bietet ein standardisiertes Mittel, vorhandene Werkzeuge zu nutzen, um Typinformationen mit minimalem Aufwand zu verpacken und zu verteilen, sowie eine Reihenfolge für Typüberprüfer, um Module aufzulösen und diese Informationen für die Typüberprüfung zu sammeln.

Begründung

Derzeit möchten Paketautoren Code verteilen, der Inline-Typinformationen enthält. Zusätzlich möchten Wartende Stub-Dateien verteilen, um die Kompatibilität mit Python 2 zu erhalten und gleichzeitig neuere Annotationssyntax zu verwenden. Es gibt jedoch keine Standardmethode, um Pakete mit Typinformationen zu verteilen. Wenn man Stub-Dateien privat versenden wollte, wäre die einzige verfügbare Methode das Setzen von MYPYPATH oder einem Äquivalent, um manuell auf Stubs zu verweisen. Wenn das Paket öffentlich veröffentlicht werden kann, kann es zu typeshed hinzugefügt werden [1]. Dies skaliert jedoch nicht und wird zur Belastung für die Wartenden von typeshed. Zusätzlich bindet es Fehlerkorrekturen in Stubs an die Veröffentlichungen des Tools, das typeshed verwendet.

PEP 484 enthält einen kurzen Abschnitt über die Verteilung von Typinformationen. In diesem Abschnitt empfiehlt die PEP die Verwendung von shared/typehints/pythonX.Y/ zum Versenden von Stub-Dateien. Das manuelle Hinzufügen eines Pfades zu Stub-Dateien für jede Drittanbieterbibliothek skaliert jedoch nicht. Der einfachste Ansatz, den Leute verfolgt haben, ist das Hinzufügen von site-packages zu ihrem MYPYPATH, aber dies führt dazu, dass Typüberprüfer bei stark dynamischen Paketen (z. B. SQLAlchemy und Django) fehlschlagen.

Begriffsbestimmungen

Die Definition von „MUSS“, „SOLLTE“ und „SOLLTE NICHT“ ist so zu interpretieren, wie sie in RFC 2119 beschrieben sind.

„inline“ – die Typen sind Teil des Laufzeitcodes unter Verwendung der Syntax von PEP 526 und PEP 3107 (der Dateiname endet auf .py).

„stubs“ – Dateien, die nur Typinformationen enthalten und keinen Laufzeitcode (der Dateiname endet auf .pyi).

„Distributionen“ sind die verpackten Dateien, die zur Veröffentlichung und Verbreitung einer Veröffentlichung verwendet werden. (PEP 426)

„Modul“ eine Datei, die Python-Laufzeitcode oder Stub-Typinformationen enthält.

„Paket“ ein Verzeichnis oder Verzeichnisse, die Python-Module benennen. (Beachten Sie die Unterscheidung zwischen Paketen und Distributionen. Während die meisten Distributionen nach dem einen Paket benannt sind, das sie installieren, installieren einige Distributionen mehrere Pakete.)

Spezifikation

Es gibt mehrere Motivationen und Methoden zur Unterstützung der Typisierung in einem Paket. Diese PEP erkennt drei Arten von Paketen an, die Benutzer der Typisierung erstellen möchten:

1. Der Paketwart möchte Typinformationen inline hinzufügen.
2. Der Paketwart möchte Typinformationen über Stubs hinzufügen.
3. Ein Drittanbieter oder Paketwart möchte Stub-Dateien für ein Paket teilen, der Wartende möchte sie jedoch nicht in den Quellcode des Pakets aufnehmen.

Diese PEP zielt darauf ab, alle drei Szenarien zu unterstützen und sie einfach in Verpackung und Bereitstellung zu integrieren.

Die beiden Hauptteile dieser Spezifikation sind die Verpackungsspezifikationen und die Auflösungsreihenfolge für die Auflösung von Modultypinformationen. Die Typüberprüfungsspezifikation soll die shared/typehints/pythonX.Y/ Spezifikation von PEP 484 ersetzen.

Neue Drittanbieter-Stub-Bibliotheken SOLLTEN Stubs über die in dieser PEP vorgeschlagenen Drittanbieter-Verpackungsmethoden verteilen, anstatt sie an typeshed anzuhängen. Typeshed wird weiterhin verwendet, aber wenn Wartende gefunden werden, SOLLTEN Drittanbieter-Stubs in typeshed in eigene Pakete aufgeteilt werden.

setup(
    ...,
    package_data = {
        'foopkg': ['py.typed'],
    },
    ...,
    )

shapes-stubs
└── polygons
    └── pentagon
        └── __init__.pyi

shapes-stubs
└── polygons
    └── hexagon
        └── __init__.pyi

Implementierung

Das vorgeschlagene Schema zur Kennzeichnung der Unterstützung für Typisierung ist vollständig abwärtskompatibel und erfordert keine Änderungen an den Paketwerkzeugen. Ein Beispielpaket mit Inline-Typen ist verfügbar [typed_package], ebenso wie ein [stub_package]. Ein Beispiel für einen Paketprüfer [pkg_checker], der die Metadaten installierter Pakete liest und ihren Status als untypisiert, inline typisiert oder als Stub-Paket meldet.

Der mypy-Typüberprüfer verfügt über eine Implementierung der PEP 561-Suche, über die in der mypy-Dokumentation gelesen werden kann [4].

[numpy-stubs] ist ein Beispiel für ein reales reines Stub-Paket für die numpy-Distribution.

Danksagungen

Diese PEP wäre ohne die Ideen, das Feedback und die Unterstützung von Ivan Levkivskyi, Jelle Zijlstra, Alyssa Coghlan, Daniel F Moisset, Andrey Vlasovskikh, Nathaniel Smith und Guido van Rossum nicht möglich gewesen.

Versionshistorie

• 2023-01-13

  • Klarstellung, dass der 4. Schritt der Modulauflösungsreihenfolge für jedes Paket mit einer py.typed-Markierungsdatei gilt (und nicht nur für Inline-Pakete).

• 2021-09-20

  • Klarstellung der Erwartungen und des Typüberprüferverhaltens für reine Stub-Namespace-Pakete
  • Klarstellung der Behandlung von Einzeldatei-Modulen innerhalb von Namespace-Paketen.

• 2018-07-09

  • Links zu Beispiel-Stub-Paketen hinzufügen

• 2018-06-19

  • Partielle Stub-Pakete können typeshed sowie Laufzeitpakete betrachten

• 2018-05-15

  • Spezifikation für partielle Stub-Pakete hinzufügen.

• 2018-04-09

  • Referenz zur mypy-Implementierung hinzufügen
  • Stub-Paket-Priorität klären.

• 2018-02-02

  • Suffix für reine Stub-Pakete von _stubs in -stubs ändern.
  • Anmerkung, dass py.typed für reine Stub-Pakete nicht benötigt wird.
  • Hinweis zu pip und der Aktualisierung von Stub-Paketen hinzufügen.

• 2017-11-12

  • Umgeschrieben, um ausschließlich vorhandene Werkzeuge zu verwenden
  • Keine Notwendigkeit, die Art der Typinformationen in Metadaten anzugeben
  • Name der Markierungsdatei von .typeinfo in py.typed geändert

• 2017-11-10

  • Spezifikation umgeschrieben, um Paketmetadaten anstelle von Distributionsmetadaten zu verwenden.
  • Reine Stub-Pakete entfernt und in die Spezifikation für Drittanbieter-Pakete integriert.
  • Vorschlag für Typüberprüfer, Laufzeitversionen zu berücksichtigen, entfernt
  • Implementierungen aktualisiert, um PEP-Änderungen widerzuspiegeln.

• 2017-10-26

  • Implementierungsreferenzen hinzugefügt.
  • Danksagungen und Versionshistorie hinzugefügt.

• 2017-10-06

  • Umgeschrieben, um .distinfo/METADATA anstelle eines distutils-spezifischen Befehls zu verwenden.
  • Versionierung von Drittanbieter-Stub-Paketen klären.

• 2017-09-11

  • Informationen über aktuelle Lösungen und typeshed hinzugefügt.
  • Begründung klären.

Referenzen

Urheberrecht

Dieses Dokument wurde gemeinfrei erklärt.