摘要

本PEP概述了Python的向後相容性策略。

基本原理

作為當今使用最廣泛的程式語言之一[1]，Python核心語言及其標準庫在數百萬應用程式和庫中發揮著關鍵作用。這非常棒。然而，這意味著開發團隊必須非常小心，以免新版本破壞這些現有的第三方程式碼。

本PEP認為“向後不相容性”意味著在更改後，現有程式碼停止相對正常地執行。我們承認這並非一個具體的定義，但期望人們普遍理解“向後不相容性”的含義，如果他們不確定，可以向Python開發團隊和/或指導委員會尋求指導。

向後相容性規則

此策略適用於所有公共API。這些包括：

• 參考手冊中定義的這些構造的語法和行為。
• C-API。
• 函式、類、模組、屬性和方法的名稱和型別。
• 給定一組引數時，函式的返回值、副作用和引發的異常。這不排除合理錯誤修復導致的更改。
• 引數和返回值的位置和預期型別。
• 類在子類方面的行為：何時呼叫被覆蓋的方法的條件。
• 已記錄的異常以及導致其引發的語義。
• 在EAFP場景中通常引發的異常。

其他明確不屬於公共API的部分。它們可以在任何時間以任何方式更改或刪除。這些包括：

• 以“_”為字首的函式、類、模組、屬性、方法和C-API名稱和型別（特殊名稱除外）。
• 任何公開文件中宣告為私有的內容。請注意，如果某項內容完全未被記錄，它不會自動被視為私有。
• 匯入的模組（除非明確文件化為公共API的一部分；例如，在spam模組中匯入bacon模組並不自動意味著spam.bacon是公共API的一部分，除非它被如此文件化）。
• 內部類的繼承模式。
• 測試套件。（Lib/test目錄或包的測試子目錄中的任何內容。）
• 向後相容性規則不適用於任何根據PEP 411明確標記為試用版的模組或API。

軟棄用

當API不再用於編寫新程式碼，但在現有程式碼中繼續使用仍然安全時，可以使用軟棄用。API仍然有文件和測試，但不會進一步開發（不進行增強）。

“軟”棄用與（常規的）“硬”棄用之間的主要區別在於，軟棄用不意味著安排廢棄API的移除。

另一個區別是軟棄用不會發出警告：它僅在文件中提及，而通常“硬”棄用會在執行時發出DeprecationWarning警告。軟棄用的文件應解釋為何應避免使用該API，並儘可能提出替代方案。

如果決定棄用（在常規意義上）目前處於軟棄用狀態的功能，則棄用必須遵循向後相容性規則（即，不因為該功能已處於軟棄用狀態而存在例外）。

進行不相容的更改

進行不相容更改是一個逐步的過程，需要透過多個版本完成：

1. 討論更改。根據不相容的程度，這可能在bug追蹤器、python-dev、python-list或適當的SIG上進行。可能會編寫PEP或類似文件。希望受影響API的使用者能積極發表評論。
2. 在當前的main分支中新增警告。如果行為正在改變，API可能會增加一個新函式或方法來執行新行為；舊用法應引發警告。如果API正在被移除，則只要進入該API就發出警告。DeprecationWarning是常用的警告類別，但在舊版本和新版本API將共存多個版本的特殊情況下，可以使用PendingDeprecationWarning[2]。警告訊息應包含預計不相容性將成為預設值的版本以及使用者可以提交反饋問題的連結。如果可行，還應更改typeshed以向已棄用的API新增@deprecated裝飾器（參見PEP 702），以便靜態型別檢查器的使用者有另一種方式瞭解棄用。

   對於C API，Py_DEPRECATED宏生成的編譯器警告也是可以接受的。

3. 等待警告在至少兩個相同主版本的次要Python版本中出現，或者在一個較舊主版本的一個次要版本中出現（例如，對於Python 3.10.0中的警告，你需要等到至少Python 3.12或Python 4.0才能進行更改）。然而，最好等待5年再移除（例如，從Python 3.10開始警告，在3.15中移除；這恰好與Python當前次要版本的生命週期一致）。
   • 如果棄用行為的預期維護開銷和安全風險很小（例如，一箇舊函式以一個新的、更通用的函式重新實現），它可以無限期保留（或者直到情況改變）。
   • 如果已棄用的功能被新功能取代，通常應在不包含新功能的最後一個 Python 版本停止支援後才能移除。
4. 看看是否有任何反饋。未參與最初討論的使用者在看到警告後可能會發表評論。也許可以重新考慮。
5. 行為更改或功能移除現在可以在達到宣告的版本後成為預設或永久更改。移除舊版本和警告。
6. 如果無法向用戶提供警告，請諮詢指導委員會。

更新日誌

• 2025年1月27日：更新為優先採用5年棄用期再移除。
• 2023年11月14日：根據PEP 702添加了@deprecated裝飾器。
• 2023年7月3日：添加了軟棄用部分，如https://discuss.python.org/t/27957中所討論。
• 2023年6月26日：多項小更新和澄清，如https://discuss.python.org/t/22042中所討論。
• 2022年4月4日：在幾個特殊情況下明確指出應諮詢指導委員會。
• 2021年4月16日：澄清了在進行更改之前必須發出警告的時長。
• 2020年7月20日：初始接受版本。

參考資料

版權

本文件已置於公共領域。