PEP 503 – 簡易儲存庫 API
- 作者:
- Donald Stufft <donald at stufft.io>
- BDFL-Delegate:
- Donald Stufft <donald at stufft.io>
- 討論於:
- Distutils-SIG 郵件列表
- 狀態:
- 最終 (Final)
- 類型:
- 標準軌跡 (Standards Track)
- 主題:
- 套件封裝 (Packaging)
- 建立日期:
- 2015年9月4日
- 公告歷史:
- 2015年9月4日
- 決議:
- Distutils-SIG 訊息
摘要
Python 套件儲存庫（repository）有許多實作方式，也有許多工具會消耗這些儲存庫。其中，定義「簡易（simple）」儲存庫 API 外觀的標準實作，正是驅動 PyPI 的實作。本文件將規範該 API，記錄任何簡易儲存庫 API 實作應具備的正確行為。
規範
實作簡易 API 的儲存庫由其「基礎 URL（base URL）」定義，這是所有其他 URL 所在的頂層 URL。此 API 之所以稱為「簡易」儲存庫，是因為 PyPI 的基礎 URL 為 https://pypi.org/simple/。
附註
本文件後續提及的所有 URL 皆為相對於此基礎 URL（因此，以 PyPI 的 URL 為例，/foo/ 的 URL 即為 https://pypi.org/simple/foo/）。
在儲存庫內，根 URL（本 PEP 中代表基礎 URL 的 /）必須是一個有效的 HTML5 頁面，且針對儲存庫中的每個專案提供一個錨點（anchor）元素。錨點標籤的文字必須為專案名稱，且 href 屬性必須連結至該特定專案的 URL。範例如下：
<!DOCTYPE html>
<html>
<body>
<a href="/frob/">frob</a>
<a href="/spamspamspam/">spamspamspam</a>
</body>
</html>
在根 URL 之下，儲存庫內包含的每個個別專案都有另一個 URL。此 URL 的格式為 /<project>/，其中 <project> 應替換為該專案的「正規化名稱（normalized name）」。例如，名為“HolyGrail”的專案其 URL 將會是 /holygrail/。此 URL 必須回傳一個有效的 HTML5 頁面，並針對該專案的每個檔案提供一個錨點元素。href 屬性必須為連結至檔案下載位置的 URL，且錨點標籤的文字必須符合 URL 的最終路徑組件（即檔名）。URL 應包含一個以 URL 片段形式存在的雜湊值，語法如下：#<hashname>=<hashvalue>，其中 <hashname> 為雜湊函數的小寫名稱（如 sha256），而 <hashvalue> 則為十六進位編碼的摘要。
除上述內容外，該 API 還受以下規範限制：
- 所有回傳 HTML5 頁面的 URL 必須以
/結尾，且儲存庫應將未以/結尾的 URL 重新導向至結尾包含/的路徑。 - URL 可以是絕對路徑或相對路徑，只要它們指向正確的位置即可。
- 關於檔案相對於儲存庫應託管在何處，並無任何限制。
- 只要 API 頁面上存在必要的錨點元素，頁面中可包含任何其他 HTML 元素。
- 儲存庫可以將未正規化的 URL 重新導向至標準的正規化 URL（例如
/Foobar/可能會重新導向至/foobar/），然而客戶端不得依賴此重新導向行為，且必須直接請求正規化後的 URL。 - 儲存庫應從 Python 標準函式庫
hashlib模組保證可用的雜湊函數中選擇一種（目前為md5,sha1,sha224,sha256,sha384,sha512）。目前的建議是使用sha256。 - 如果特定發行版檔案有 GPG 簽章，該簽章必須與檔案放置在一起，並在檔名後加上
.asc。例如，若存在檔案/packages/HolyGrail-1.0.tar.gz且有相關聯的簽章，則該簽章應位於/packages/HolyGrail-1.0.tar.gz.asc。 - 儲存庫可以在檔案連結中包含
data-gpg-sig屬性，並將值設為true或false，以指示是否有 GPG 簽章。若儲存庫採取此做法，則應在每個連結上都包含此屬性。 - 儲存庫可以在檔案連結中包含
data-requires-python屬性。此屬性會公開 PEP 345 中指定的 Requires-Python 中繼資料欄位。若此屬性存在，安裝工具在安裝至不符合該需求的 Python 版本時，應忽略此下載項目。範例如下：<a href="..." data-requires-python=">=3">...</a>
在屬性值中，< 和 > 必須分別以 HTML 編碼表示為
<和>。
正規化名稱
本 PEP 引用了「正規化」專案名稱的概念。根據 PEP 426，名稱中僅允許使用 ASCII 字母、ASCII 數字、.、- 以及 _。名稱應轉換為小寫，並將所有連續的 .、- 或 _ 字元替換為單一 - 字元。這可以使用 Python 的 re 模組來實作：
import re
def normalize(name):
return re.sub(r"[-_.]+", "-", name).lower()
變更
- 選用的
data-requires-python屬性於 2016 年 7 月加入。
版權
此文件已歸入公有領域 (public domain)。
來源：https://github.com/python/peps/blob/main/peps/pep-0503.rst