Zusammenfassung

Dieses PEP beschreibt die Rückwärtskompatibilitätsrichtlinie von Python.

Begründung

Als eine der heute meistgenutzten Programmiersprachen [1] spielen die Python-Kernsprache und ihre Standardbibliothek eine entscheidende Rolle in Millionen von Anwendungen und Bibliotheken. Das ist fantastisch. Es bedeutet jedoch, dass das Entwicklungsteam sehr sorgfältig darauf achten muss, diesen bestehenden Drittanbieter-Code mit neuen Releases nicht zu brechen.

Dieses PEP vertritt die Ansicht, dass „Rückwärtsinkompatibilität“ bedeutet, dass vorbestehender Code nach einer Änderung nicht mehr vergleichbar funktioniert. Es wird anerkannt, dass dies keine konkrete Definition ist, aber die Erwartung ist, dass die Leute im Allgemeinen verstehen, was mit „Rückwärtsinkompatibilität“ gemeint ist, und dass sie, wenn sie unsicher sind, das Python-Entwicklungsteam und/oder den Lenkungsausschuss um Rat bitten können.

Regeln für Rückwärtskompatibilität

Diese Richtlinie gilt für alle öffentlichen APIs. Dazu gehören:

• Syntax und Verhalten dieser Konstrukte, wie im Referenzhandbuch definiert.
• Die C-API.
• Namen und Typen von Funktionen, Klassen, Modulen, Attributen und Methoden.
• Gegeben eine Reihe von Argumenten, der Rückgabewert, Nebeneffekte und ausgelöste Ausnahmen einer Funktion. Dies schließt Änderungen aufgrund vernünftiger Fehlerbehebungen nicht aus.
• Die Position und erwarteten Typen von Argumenten und Rückgabewerten.
• Verhalten von Klassen in Bezug auf Unterklassen: die Bedingungen, unter denen überschriebene Methoden aufgerufen werden.
• Dokumentierte Ausnahmen und die Semantik, die zu deren Auslösung führt.
• Ausnahmen, die üblicherweise in EAFP-Szenarien ausgelöst werden.

Andere sind ausdrücklich kein Teil der öffentlichen API. Sie können jederzeit und auf jede Weise geändert oder entfernt werden. Dazu gehören:

• Namen und Typen von Funktionen, Klassen, Modulen, Attributen, Methoden und C-APIs, die mit „_“ präfixiert sind (außer Sondernamen).
• Alles, was öffentlich als privat dokumentiert ist. Beachten Sie, dass, wenn etwas überhaupt nicht dokumentiert ist, es nicht automatisch als privat gilt.
• Importierte Module (es sei denn, sie sind ausdrücklich als Teil der öffentlichen API dokumentiert; z. B. bedeutet das Importieren des bacon-Moduls in spam nicht automatisch, dass spam.bacon Teil der öffentlichen API ist, es sei denn, es ist als solches dokumentiert).
• Vererbungsmuster von internen Klassen.
• Testsuiten. (Alles im Verzeichnis Lib/test oder in Testunterverzeichnissen von Paketen.)
• Regeln für Rückwärtskompatibilität gelten nicht für Module oder APIs, die gemäß PEP 411 ausdrücklich als Vorläufig dokumentiert sind.

Soft Deprecation

Eine Soft Deprecation kann verwendet werden, wenn eine API verwendet wird, die nicht mehr für das Schreiben neuer Codes verwendet werden sollte, aber die Fortsetzung der Verwendung in bestehendem Code sicher ist. Die API bleibt dokumentiert und getestet, wird aber nicht weiterentwickelt (keine Erweiterung).

Der Hauptunterschied zwischen einer „Soft“ und einer (regulären) „Hard“ Deprecation ist, dass die Soft Deprecation nicht die Planung der Entfernung der veralteten API impliziert.

Ein weiterer Unterschied ist, dass eine Soft Deprecation keine Warnung ausgibt: Sie wird nur in der Dokumentation erwähnt, während normalerweise eine „Hard“ Deprecation eine DeprecationWarning-Warnung zur Laufzeit ausgibt. Die Dokumentation einer Soft Deprecation sollte erklären, warum die API vermieden werden sollte, und wenn möglich eine Ersetzung vorschlagen.

Wenn die Entscheidung getroffen wird, ein Feature, das derzeit soft deprecated ist, zu deprecaten (im eigentlichen Sinne), muss die Deprecation den Regeln für Rückwärtskompatibilität folgen (d. h., es gibt keine Ausnahme, weil das Feature bereits soft deprecated ist).

Inkompatible Änderungen vornehmen

Das Vornehmen einer inkompatiblen Änderung ist ein schrittweiser Prozess, der über mehrere Releases durchgeführt wird

1. Diskutieren Sie die Änderung. Je nach Grad der Inkompatibilität kann dies im Bugtracker, auf python-dev, python-list oder im entsprechenden SIG erfolgen. Ein PEP oder ein ähnliches Dokument kann verfasst werden. Hoffentlich melden sich Benutzer der betroffenen API, um Kommentare abzugeben.
2. Fügen Sie der aktuellen main-Branch eine Warnung hinzu. Wenn sich das Verhalten ändert, kann die API eine neue Funktion oder Methode zur Ausführung des neuen Verhaltens erhalten; alte Verwendungen sollten die Warnung auslösen. Wenn eine API entfernt wird, warnen Sie einfach, wenn sie aufgerufen wird. DeprecationWarning ist die übliche Warnungskategorie, aber PendingDeprecationWarning kann in Sonderfällen verwendet werden, in denen die alten und neuen Versionen der API über viele Releases koexistieren werden [2]. Die Warnmeldung sollte das Release angeben, bei dem die Inkompatibilität zur Standardeinstellung wird, und einen Link zu einem Issue, an dem Benutzer Feedback posten können. Wenn möglich, ändern Sie auch typeshed, um den @deprecated-Decorator (siehe PEP 702) zur veralteten API hinzuzufügen, damit Benutzer statischer Typ-Checker eine weitere Möglichkeit haben, über die Veraltung informiert zu werden.

   Für die C-API ist auch eine Compiler-Warnung, die von der Py_DEPRECATED-Makro generiert wird, akzeptabel.

3. Warten Sie, bis die Warnung in mindestens zwei minor Python-Versionen derselben Major-Version oder einer minor-Version in einer älteren Major-Version erscheint (z. B. für eine Warnung in Python 3.10.0, warten Sie entweder bis mindestens Python 3.12 oder Python 4.0, um die Änderung vorzunehmen). Es wird jedoch bevorzugt, 5 Jahre vor der Entfernung zu warten (z. B. Warnung ab Python 3.10, Entfernung in 3.15; dies fällt zufällig mit der aktuellen Lebensdauer einer minor-Version von Python zusammen).
   • Wenn der erwartete Wartungsaufwand und das Sicherheitsrisiko des veralteten Verhaltens gering sind (z. B. eine alte Funktion wird neu implementiert, basierend auf einer neuen, allgemeineren), kann sie unbegrenzt bleiben (oder bis sich die Situation ändert).
   • Wenn das veraltete Feature durch ein neues ersetzt wird, sollte es im Allgemeinen erst entfernt werden, nachdem die letzte Python-Version *ohne* das neue Feature ihr Support-Ende erreicht hat.
4. Prüfen Sie, ob es Feedback gibt. Benutzer, die nicht an den ursprünglichen Diskussionen beteiligt waren, können jetzt kommentieren, nachdem sie die Warnung gesehen haben. Überdenken Sie es vielleicht.
5. Die Verhaltensänderung oder Feature-Entfernung kann nun standardmäßig oder dauerhaft erfolgen, nachdem die deklarierte Version erreicht wurde. Entfernen Sie die alte Version und die Warnung.
6. Wenn eine Warnung den Benutzern nicht zur Verfügung gestellt werden kann, konsultieren Sie den Lenkungsausschuss.

Änderungsprotokoll

• 2025-01-27: Aktualisiert, um eine 5-jährige Deprecationsperiode vor der Entfernung zu bevorzugen.
• 2023-11-14: Hinzufügen des @deprecated-Decorators gemäß PEP 702.
• 2023-07-03: Hinzufügen des Abschnitts "Soft Deprecation", wie in https://discuss.python.org/t/27957 diskutiert.
• 2023-06-26: Mehrere kleinere Updates und Klarstellungen, diskutiert in https://discuss.python.org/t/22042.
• 2022-04-04: Explizite Hinweise hinzugefügt, um den Lenkungsausschuss in mehreren Ausnahmefällen zu bitten.
• 2021-04-16: Klarstellung, wie lange eine Warnung ausgegeben werden muss, bevor eine Änderung vorgenommen werden kann.
• 2020-07-20: Erste akzeptierte Version.

Referenzen

Urheberrecht

Dieses Dokument wurde gemeinfrei erklärt.