PEP 629 – PyPI Simple API 版本控制
- 作者:
- Donald Stufft <donald at stufft.io>
- BDFL 委託：
- Brett Cannon <brett at python.org>
- 討論至:
- Discourse 帖子
- 狀態:
- 最終版
- 型別:
- 標準跟蹤
- 主題:
- 打包
- 建立日期:
- 2020年7月16日
- 釋出歷史:
- 2020年7月16日
注意
此 PEP 已於 2020年8月20日被接受。PyPI 於 2020年1月28日 合併了一個實現，標誌著此 PEP 為“最終”。
摘要
本 PEP 提議為 simple API 新增一種版本控制方法，以便客戶端可以確定特定倉庫支援 simple API 的哪些功能。
基本原理
在發展 simple API 時，客戶端希望能夠確定倉庫支援哪些功能。目前沒有機制可以做到這一點，除了透過檢視響應中的資料來嘗試檢測新功能，並檢視是否似乎正在使用特定功能。
這對於現代版本的客戶端來說，可以很好地確定倉庫是否支援它想要實現的所有功能，但它無法告訴舊版本客戶端倉庫支援它可能無法理解的功能，也無法允許訊息傳遞來表明它可能無法正確理解倉庫的輸出。
一個發生這種情況的場景是 `python-requires` 元資料逐步推出，雖然現有客戶端仍然可以成功使用倉庫，但它們缺乏理解這塊新資料的能力，而這些資料本可以指導它們的行為，為終端使用者選擇更好的檔案。
概述
本 PEP 提議在對 simple API 頁面的每個成功請求的響應中包含一個 meta 標籤，其中包含一個 `name` 屬性為“pypi:repository-version”，以及一個內容是 PEP 440 相容的版本號，並且進一步限制為僅為 Major.Minor，不包含 PEP 440 支援的任何附加功能。
這看起來會像
<meta name="pypi:repository-version" content="1.0">
在解釋倉庫版本時
- 增加主版本號用於表示向後不相容的更改，這意味著現有客戶端將不再能有意義地使用該 API。
- 增加次版本號用於表示向後相容的更改，這意味著現有客戶端仍然可以有意義地使用該 API。
至於具體構成向後不相容還是相容的更改，除了現有客戶端將能夠“有意義地”繼續使用 API 的廣泛建議之外，將由任何未來的 PEP 自行決定，並且可以包括新增、修改或刪除現有功能。
本 PEP 期望主版本號永遠不會增加，並且任何未來的主要 API 演進都將利用不同的 API 演進機制。然而，包含主版本號是為了與未來版本區分開來（例如，一個假設的 simple API v2 存在於 `/v2/`，但如果 `repository-version` 設定為 >= 2 的版本，則會令人困惑）。
本 PEP 將當前的 API 版本設定為“1.0”，並期望未來進一步發展 simple API 的 PEP 將增加次版本號。
客戶端
與 simple API 互動的客戶端 **應該** 檢查每個響應中的倉庫版本，如果該資料不存在，則 **必須** 假定其版本為 1.0。
當遇到大於預期版本的主版本號時，客戶端 **必須** 帶著適當的錯誤資訊硬失敗（立即中止）。
當遇到大於預期的次版本號時，客戶端 **應該** 向用戶發出適當的警告訊息。
客戶端 **可以** 仍然繼續使用功能檢測來確定倉庫使用了哪些功能。
被拒絕的想法
使用 HTTP 頭部
除了將此資訊嵌入到實際的 HTML 中，另一種選擇是使用 HTTP 頭部。這個想法被考慮過，但最終被拒絕，因為它會使映象不得不開始修改頭部，而不是能夠充當“傻瓜式”的檔案 HTTP 伺服器。
使用 URL
另一種傳統的 API 版本控制機制是將其嵌入到 URL 中，例如 /1.0/simple/ 等。這對於主要版本更改非常有效，因為舊的客戶端預計無法繼續使用它，但它不適用於次要版本升級，特別是當版本號在很大程度上可以被視為對終端使用者的建議時。
版權
本文件置於公共領域或 CC0-1.0-Universal 許可證下，以更寬鬆者為準。
來源：https://github.com/python/peps/blob/main/peps/pep-0629.rst