版本

除了 PEP 691 中定義的 name、files 和 meta 鍵之外，頂層必須存在一個附加鍵 versions。此鍵必須包含一個版本字串列表，指定為此專案上傳的所有專案版本。該值在邏輯上是一個集合，因此不能包含重複項，並且值的順序不重要。

files 鍵中列出的所有檔案都必須與 versions 鍵中的某個版本相關聯。versions 鍵可以包含沒有相關檔案的版本（如果伺服器有此類概念，則表示沒有檔案上傳的版本）。

請注意，由於伺服器可能保留在採用 PEP 440 之前形成的“遺留”資料，目前不能要求版本字串是有效的 PEP 440 版本，因此不能假定可以使用 PEP 440 規則進行排序。但是，伺服器應儘可能使用規範化的 PEP 440 版本。

附加檔案資訊

在 files 鍵中添加了兩個新鍵。

• size：此欄位是強制性的。它必須包含一個整數，表示檔案大小（以位元組為單位）。
• upload-time：此欄位是可選的。如果存在，它必須包含一個有效的 ISO 8601 日期/時間字串，格式為 yyyy-mm-ddThh:mm:ss.ffffffZ，表示檔案上傳到索引的時間。如 Z 字尾所示，上傳時間必須使用 UTC 時區。時間戳的小數秒部分（.ffffff 部分）是可選的，如果存在，最多可以包含 6 位精度數字。如果伺服器不記錄檔案的上傳時間資訊，則可以省略 upload-time 鍵。

為什麼不也將此資料新增到 HTML API？

可以將資料新增到 HTML API，但絕大多數消費者目前可能都是從 PyPI JSON API 獲取此資料，因此已經期望解析 JSON。HTML API 的傳統消費者以前從未需要此資料。

這是否意味著 HTML API 已過時？

不。PEP 691 的常見問題解答明確指出 HTML API 並未被棄用，本 PEP 並未改變這一立場。但是，希望訪問本 PEP 引入的新資料的客戶端將需要使用 JSON API 獲取它。希望提供它的索引將需要提供 JSON 格式。

簡單 API 是否正在取代 Warehouse JSON 和 XML-RPC API？

在可能的情況下，客戶端應優先使用簡單 API 而非 JSON 或 XML-RPC API，因為前者是標準化的，可以假定可從任何索引獲取，而後者是 Warehouse 專案獨有的。

然而，儘管本 PEP 使簡單 API 更接近於能夠取代 JSON API，但沒有正式的政策規定簡單 API 將複製現有 Warehouse API 涵蓋的所有功能。對簡單 API 的擬議新增仍將根據其各自的優點進行考慮，並且 API 應該簡單且快速地用於定位專案檔案的主要用例仍將是首要考慮因素。

為什麼不允許其他日期格式？

ISO 8601 標準很複雜，要求客戶端處理它似乎沒什麼價值。標準庫 datetime 模組提供瞭解析 ISO 8601 字串的方法，但使用者可能希望在不使用 Python 的情況下訪問索引資料（例如，將 curl 的輸出透過管道傳輸到 jq）。擁有一個單一、明確定義的格式使其更容易，並且沒有任何顯著的缺點。

如果檔案大小對於 JSON 數字來說太大怎麼辦？

JSON 標準沒有指定如何解釋數字。Python 可以在 JSON 檔案中讀寫任意長度的整數，因此對於用 Python 編寫的程式碼來說這不應該是一個問題。非 Python 實現可能需要注意正確處理大整數，但這預計不會成為一個顯著問題。

為什麼不要求 PEP 440 版本？

在編寫本 PEP 時，PyPI 仍然包含（並提供）帶有“遺留”版本的專案和檔案。要求 PEP 440 版本將使 PyPI 無法在遵循此規範的同時提供現有內容。

理想情況下，在未來的某個時候，簡單索引 API 將更新以要求 PEP 440 版本，屆時本規範也應進行更新以反映這一點。然而，這一更改將需要與包括 PyPI 在內的現有索引提供者協調，以取消支援和刪除不符合要求的專案和/或檔案。

為什麼不提供“最新版本”值？

對於 PEP 440 版本，客戶端很容易做到這一點（使用 packaging 庫，latest = max(Version(s) for s in proj["versions"])）。對於非標準版本，沒有明確的排序，客戶端需要根據自己的需求決定合適的規則。要求伺服器提供最新版本值將選擇權從客戶端手中奪走。

如果伺服器有一個明確的“最新”版本概念，並且無法從客戶端可用的資料中計算出來，它們可以提供一個非標準、帶下劃線字首的鍵來向客戶端傳達該資訊。