Typeshed enthält externe Typanmerkungen für die Python-Standardbibliothek und Python-Builtins sowie Pakete von Drittanbietern, die von Personen außerhalb dieser Projekte beigesteuert wurden.
Diese Daten können beispielsweise für statische Analysen, Typprüfung, Typinferenz und Autovervollständigung verwendet werden.
Informationen zur Verwendung von Typeshed finden Sie weiter unten. Informationen für Mitwirkende finden Sie unter CONTRIBUTING.md. Bitte lesen Sie es, bevor Sie Pull-Anfragen einreichen. Melden Sie Probleme mit Anmerkungen nicht dem Projekt, für das die Stubs bestimmt sind, sondern melden Sie sie stattdessen hier an typeshed.
Weitere Dokumentation zu Stub-Dateien, Typeshed und dem Typisierungssystem von Python im Allgemeinen finden Sie auch unter https://typing.readthedocs.io/en/latest/.
Typeshed unterstützt die Python-Versionen 3.8 bis 3.13.
Wenn Sie nur einen Typprüfer (mypy, pyright, pytype, PyCharm, ...) verwenden, anstatt ihn zu entwickeln, müssen Sie überhaupt nicht mit dem Typeshed-Repo interagieren: einer Kopie des Standardbibliotheksteils von Typeshed ist mit Typprüfern gebündelt. Und Typ-Stubs für Pakete und Module von Drittanbietern, die Sie verwenden, können über PyPI installiert werden. Wenn Sie beispielsweise html5lib
und requests
verwenden, können Sie die Typ-Stubs mit installieren
$ pip install types-html5lib types-requests
Diese PyPI-Pakete folgen PEP 561 und werden automatisch (bis zu einmal am Tag) durch interne Maschinen des Typeshed freigegeben.
Typprüfer sollten diese Stub-Pakete nach der Installation verwenden können. Weitere Einzelheiten finden Sie in der Dokumentation zu Ihrem Typprüfer.
Versionsnummern von Stub-Paketen von Drittanbietern bestehen aus mindestens vier Teilen. Alle Teile der Stub-Version, mit Ausnahme des letzten Teils, entsprechen der Version des Laufzeitpakets, für das ein Stub erstellt wird. Wenn das Paket types-foo
beispielsweise die Version 1.2.0.20240309
hat, garantiert dies, dass das Paket types-foo
Stubs enthält, die auf foo==1.2.*
abzielen und mit der neuesten Version von foo
getestet werden, die diesem Spezifizierer entspricht. In diesem Beispiel gibt das letzte Element der Versionsnummer (20240309) an, dass das Stub-Paket am 9. März 2024 gepusht wurde.
Bei typeshed versuchen wir, Breaking Changes auf ein Minimum zu beschränken. Aufgrund der Beschaffenheit von Stubs kann jedoch jeder Versionssprung zu Änderungen führen, die dazu führen können, dass die Typprüfung Ihres Codes fehlschlägt.
Es stehen mehrere Strategien zur Angabe der Version eines Stub-Pakets zur Verfügung, die Sie verwenden, jede mit ihren eigenen Kompromissen:
Verwenden Sie dieselben Grenzen, die Sie für das Paket verwenden, für das Stubs erstellt werden sollen. Wenn Sie beispielsweise requests>=2.30.0,<2.32
verwenden, können Sie types-requests>=2.30.0,<2.32
verwenden. Dadurch wird sichergestellt, dass die Stubs mit dem von Ihnen verwendeten Paket kompatibel sind, es besteht jedoch ein geringes Risiko, dass die Typprüfung aufgrund von Änderungen an den Stubs unterbrochen wird.
Ein weiteres Risiko dieser Strategie besteht darin, dass Stubs oft hinter dem Paket zurückbleiben, für das Stubs erstellt werden. Möglicherweise möchten Sie das Stuben des Pakets auf eine bestimmte Mindestversion erzwingen, da dadurch ein kritischer Fehler behoben wird. Wenn jedoch keine entsprechend aktualisierten Stubs veröffentlicht wurden, sind die Ergebnisse Ihrer Typprüfung möglicherweise nicht vollständig korrekt.
Stecken Sie die Stubs auf eine bekanntermaßen gute Version und aktualisieren Sie die Stecknadel von Zeit zu Zeit (entweder manuell oder mit einem Tool wie Dependabot oder Renovate).
Wenn Sie beispielsweise types-requests==2.31.0.1
verwenden, können Sie sicher sein, dass die Typüberprüfung durch das Aktualisieren von Abhängigkeiten nicht unterbrochen wird. Allerdings entgehen Ihnen Verbesserungen in den Stubs, die möglicherweise die Typprüfung verbessern könnten, bis Sie den Pin aktualisieren. Diese Strategie birgt auch das Risiko, dass die von Ihnen verwendeten Stubs mit dem Paket, für das Stubs erstellt werden, nicht mehr kompatibel sind.
Stecken Sie die Stubs nicht fest. Dies ist die Option, die Ihnen beim Aktualisieren der Versions-Pins am wenigsten Arbeit abverlangt und den Vorteil hat, dass Sie automatisch von verbesserten Stubs profitieren, wenn eine neue Version des Stubs-Pakets veröffentlicht wird. Es besteht jedoch das Risiko, dass die Stubs mit dem Paket, für das Stubs erstellt werden, nicht mehr kompatibel sind.
Wenn beispielsweise eine neue Hauptversion des Pakets veröffentlicht wird, besteht die Möglichkeit, dass die Stubs aktualisiert werden, um die neue Version des Laufzeitpakets widerzuspiegeln, bevor Sie das Paket aktualisieren, für das Stubs erstellt werden.
Sie können bei Bedarf auch zwischen den verschiedenen Strategien wechseln. Beispielsweise könnten Sie standardmäßig auf Strategie (1) zurückgreifen, aber auf Strategie (2) zurückgreifen, wenn ein Problem auftritt, das nicht einfach behoben werden kann.
_typeshed
Paket typeshed enthält ein Paket _typeshed
als Teil der Standardbibliothek. Dieses Paket und seine Submodule enthalten Dienstprogrammtypen, sind jedoch zur Laufzeit nicht verfügbar. Weitere Informationen zur Verwendung dieses Pakets finden Sie im Verzeichnis stdlib/_typeshed
.
Wenn Sie bei der Typprüfung auf ein Verhalten stoßen, das darauf hindeutet, dass die Typ-Stubs für eine bestimmte Bibliothek falsch oder unvollständig sind, möchten wir von Ihnen hören!
Unser Hauptdiskussionsforum ist der GitHub-Issue-Tracker des Projekts. Dies ist der richtige Ort, um eine Diskussion über eines der oben genannten oder die meisten anderen Themen im Zusammenhang mit dem Projekt zu beginnen.
Wenn Sie allgemeine Fragen zum Tippen mit Python haben oder eine Überprüfung Ihrer Typanmerkungen oder Stubs außerhalb von Typeshed benötigen, besuchen Sie unser Diskussionsforum. Versuchen Sie für weniger formelle Diskussionen den Tipp-Chatroom auf gitter.im. Einige Typeshed-Betreuer sind fast immer anwesend; Fühlen Sie sich frei, uns dort zu finden und wir unterhalten uns gerne. Inhaltliche technische Diskussionen werden an den Issue-Tracker weitergeleitet.