建立發佈工作階段

發行流程始於建立新的發佈工作階段。要建立工作階段，用戶端向根 URL 提交一個 POST 請求，如下所示：

{
  "meta": {
    "api-version": "2.0"
  },
  "name": "foo",
  "version": "1.0",
}

請求包含以下頂層鍵：

meta (必要)

描述負載本身的資訊。目前唯一定義的子鍵是 api-version，其值必須為字串 "2.0"。選用的子鍵可以定義索引特定行為。

name (必要)

此工作階段嘗試發佈新版本的專案名稱。名稱 必須 (MUST) 符合標準套件名稱格式，且伺服器 必須 (MUST) 對名稱進行正規化。

version (必要)

此工作階段嘗試添加檔案的專案版本。版本字串 必須 (MUST) 符合套件版本規範。

成功建立工作階段後，伺服器會傳回 201 Created 回應。回應 必須 (MUST) 包含一個 Location 標頭，其中包含與回應主體中 links.session 鍵相同的 URL。

如果是為先前無發行記錄的專案建立工作階段，索引 可以 (MAY) 在發佈工作階段之前預留專案名稱，但 直到 暫存內容發佈前，不得 (MUST NOT) 透過「常規」（即非暫存）存取協定導航到該專案。如果此首發暫存區被取消，索引 應該 (SHOULD) 刪除該專案記錄，視同從未上傳過。

工作階段由建立它的使用者擁有，所有後續請求 必須 (MUST) 使用相同的憑據執行，否則後續請求將傳回 403 Forbidden。

選用的索引特定中繼資料

索引可以選擇為索引特定行為定義自己的中繼資料。中繼資料鍵 必須 (MUST) 以底線開頭，其後的值應能輕鬆且唯一地識別該索引。例如，PyPI 可以透過使用以下索引特定中繼資料區段，允許在發佈者所屬的組織帳號中建立專案：

{
  "meta": {
    "api-version": "2.0",
    "_pypi.org": {
        "organization": "my-main-org"
    }
  },
  "name": "foo",
  "version": "1.0",
}

這僅是一個範例。本 PEP 並未定義或保留任何索引特定的鍵或中繼資料；這留給索引自行指定與記錄。索引特定中繼資料的語義（例如：錯誤的鍵或值是否會導致錯誤或被忽略）在此亦不作定義。

{
  "meta": {
    "api-version": "2.0"
  },
  "links": {
    "stage": "...",
    "upload": "...",
    "session": "...",
  },
  "mechanisms": ["http-post-bytes"],
  "session-token": "<token-string>",
  "expires-at": "2025-08-01T12:00:00Z",
  "status": "pending",
  "files": {},
  "notices": [
    "a notice to display to the user"
  ]
}

完成發佈工作階段

要完成工作階段並發佈包含在其中的檔案，用戶端向工作階段建立回應主體中提供的 session 連結發送一個 POST 請求。

請求如下所示：

{
  "meta": {
    "api-version": "2.0"
  },
  "action": "publish",
}

如果伺服器能夠立即完成發佈工作階段，則可以這樣做並傳回 201 Created 回應。如果無法立即完成（例如：如果需要進行可能超過單一 HTTP 請求合理時間的驗證），則可以傳回 202 Accepted 回應。

伺服器 必須 (MUST) 在回應中包含指向發佈工作階段狀態 URL 的 Location 標頭，該 URL 可用於查詢當前工作階段狀態。如果伺服器傳回 202 Accepted，則可以透過輪詢該 URL 來監控工作階段狀態的變化。

取消發佈工作階段

要取消發佈工作階段，用戶端向工作階段建立回應主體中提供的 session 連結發送一個 DELETE 請求。伺服器隨後將工作階段標記為已取消，且 應該 (SHOULD) 清除作為該工作階段一部分上傳的所有資料。未來任何存取該工作階段 URL 或任何發佈工作階段相關 URL 的嘗試 必須 (MUST) 傳回 404 Not Found。

為了防止出現懸置工作階段，伺服器也可以選擇自行取消超時的工作階段。建議伺服器在不短於一週的時間後清除工作階段，但每個伺服器可以選擇自己的排程。伺服器 可以 (MAY) 支援用戶端引導的工作階段延長。

發佈工作階段狀態

用戶端隨時可以透過向 links.session 中提供的 URL（亦提供於工作階段建立回應的 Location 標頭中）發送 GET 請求來查詢工作階段狀態。

伺服器將以與初始建立發佈工作階段時相同的發佈工作階段建立回應來回應此 GET 請求，但反映了 status、expires-at 或 files 的任何變化。

延長發佈工作階段

伺服器 可以 (MAY) 允許用戶端延長工作階段，但總存留期和允許的延長次數由伺服器決定。要延長工作階段，用戶端向 links.session URL（同上，亦為 Location 標頭）發送 POST 請求。

請求如下所示：

{
  "meta": {
    "api-version": "2.0"
  },
  "action": "extend",
  "extend-for": 3600
}

指定的秒數僅是用戶端對伺服器關於延長目前工作階段額外秒數的建議。例如，如果用戶端希望將目前工作階段再延長一小時，extend-for 將為 3600。成功延長後，伺服器將以與初始建立發佈工作階段時相同的發佈工作階段建立回應主體進行回應，但反映了 status、expires-at 或 files 的任何變化。

如果伺服器拒絕延長所請求的秒數，它 必須 (MUST) 仍然傳回成功回應，且 expires-at 鍵將僅反映工作階段當前的過期時間。

發佈工作階段權杖 (Token)

索引 應該 (SHOULD) 支援暫存預覽，以便在發佈前對上傳的檔案進行實機測試。例如：CI 用戶端可以使用預發佈的 wheel 檔執行安裝測試，以確保其新版本在公開發佈前能如預期運作。

索引透過在其發佈工作階段建立的回應中傳回兩項關鍵資訊來宣傳其對暫存預覽的支援。不支援暫存預覽的索引 不得 (MUST NOT) 在其回應中包含這些內容。

session-token 是一個短權杖，如果安裝工具想要透過命令列參數支援暫存預覽（例如：$TOOL install --staging $SESSION_TOKEN），則此權杖可作為一種便捷的使用者體驗。links.stage 鍵給出暫存區的完整 URL，可用於 CLI 中（例如：pip install --extra-index-url $STAGE_URL）。工作階段權杖和 URL 必須 (MUST) 在加密上不可推測，但產生權杖的演算法由索引自行決定。暫存區 URL 必須 (MUST) 能從工作階段權杖中計算出來（使用索引記錄的格式），但 URL 的確切格式也留給索引決定。

建立檔案上傳工作階段

建立發佈工作階段後，回應之工作階段連結映射中的 upload 端點將用於開始將新檔案上傳到該工作階段。用戶端 必須 (MUST) 使用提供的 upload URL，且 不得 (MUST NOT) 假設各個工作階段之間的這些 URL 具有任何規律或共通性。

要起始檔案上傳，用戶端首先向 upload URL 發送一個 POST 請求。請求如下所示：

{
  "meta": {
    "api-version": "2.0"
  },
  "filename": "foo-1.0.tar.gz",
  "size": 1000,
  "hashes": {"sha256": "...", "blake2b": "..."},
  "metadata": "...",
  "mechanism": "http-post-bytes"
}

除了標準的 meta 鍵外，請求 JSON 還有以下額外鍵：

filename (必要)

正在上傳的檔案名稱。檔名 必須 (MUST) 符合原始碼發行版檔名規範或二進位發行版檔名慣例。索引 應該 (SHOULD) 在請求時驗證這些檔名，若檔名不符合規範，應傳回 Errors 節中描述的 400 Bad Request 錯誤碼。

size (必要)

正在上傳的檔案大小（以位元組為單位）。

hashes (必要)

雜湊名稱與十六進位編碼摘要的映射。這些摘要分別是正在上傳的檔案經由名稱所識別的演算法雜湊後的檢查碼。

預設情況下，hashlib 中可用的任何雜湊演算法都可用作雜湊字典的鍵 [3]。必須 (MUST) 始終包含至少一種來自 hashlib.algorithms_guaranteed 的安全演算法。本 PEP 特別推薦 sha256。

可以一次傳遞多個雜湊，但提供的所有雜湊 必須 (MUST) 對該檔案有效。

mechanism (必要)

用戶端打算用於此檔案的檔案上傳機制。此機制 應該 (SHOULD) 從發佈工作階段建立回應主體中宣傳的機制列表中選擇。如果伺服器營運者記錄了可供「預發佈」使用的新的或即將推出的機制，用戶端 可以 (MAY) 發送未宣傳的機制。

metadata (選用)

如果提供，這是一個包含檔案核心中繼資料的字串值。

伺服器 可以 (MAY) 使用此請求中提供的資料在允許上傳檔案之前進行一些健全性檢查。這些檢查可能包括但不限於：

• 檢查 filename 是否已存在於已發佈的發行版本中；
• 檢查 size 是否會超出任何專案或檔案配額；
• 檢查所提供的 metadata 內容是否有效。

如果伺服器決定應繼續上傳，它將傳回 202 Accepted 回應，並附帶以下回應主體。發佈工作階段的狀態也將在 files 映射中包含該檔名。如果伺服器因為不支援用戶端提供的 mechanism 而無法繼續上傳，則 必須 (MUST) 傳回 422 Unprocessable Content。伺服器 可以 (MAY) 允許並行上傳檔案，但非必要。如果伺服器判斷上傳無法繼續，則 必須 (MUST) 傳回 409 Conflict。

{
  "meta": {
    "api-version": "2.0"
  },
  "links": {
    "file-upload-session": "..."
  },
  "status": "pending",
  "expires-at": "2025-08-01T13:00:00Z",
  "mechanism": {
    "identifier": "http-post-bytes",
    "file_url": "...",
    "attestations_url": "..."
  }
}

完成檔案上傳工作階段

要完成檔案上傳工作階段（這表示檔案上傳機制已執行且未產生錯誤），用戶端向檔案上傳工作階段建立回應主體中的 file-upload-session 連結發送一個 POST。

請求如下所示：

{
  "meta": {
    "api-version": "2.0"
  },
  "action": "complete",
}

如果伺服器能夠立即完成檔案上傳工作階段，則可以這樣做並傳回 201 Created 回應，並將檔案上傳工作階段的狀態設置為 complete。如果無法立即完成（例如：如果需要進行可能超過單一 HTTP 請求合理時間的驗證），則可以傳回 202 Accepted 回應，並將檔案上傳工作階段的狀態設置為 processing。

在任何一種情況下，伺服器都應包含指向檔案上傳工作階段狀態 URL 的 Location 標頭。

伺服器 必須 (MUST) 允許用戶端輪詢檔案上傳工作階段狀態 URL 以監控狀態變化。如果伺服器以 202 Accepted 回應，用戶端可以輪詢檔案上傳工作階段狀態 URL 以監控狀態變化。用戶端 應該 (SHOULD) 遵守檔案上傳工作階段狀態回應的 Retry-After 標頭值。

取消與刪除

用戶端可以取消進行中的檔案上傳工作階段，或刪除已完全上傳的檔案。在兩種情況下，用戶端均透過向其想要刪除之檔案的檔案上傳工作階段建立回應中的 links.file-upload-session URL 發送 DELETE 請求來執行此操作。

成功的刪除請求 必須 (MUST) 回應 204 No Content。

一旦取消或刪除，用戶端 不得 (MUST NOT) 假設之前的檔案上傳工作階段資源或相關的檔案上傳機制可以重複使用。

更換部分或完全上傳的檔案

要更換工作階段檔案，檔案上傳 必須 (MUST) 是先前已完成、取消或刪除的。如果該檔案的上傳正在進行中，則無法更換檔案。

要更換工作階段檔案，用戶端應先取消並刪除進行中的上傳。在此之後，可以透過重新開始整個檔案上傳序列來啟動新的檔案上傳。這意味著再次提供中繼資料請求以檢索新的上傳資源 URL。用戶端 不得 (MUST NOT) 假設刪除後可以重複使用之前的上傳資源 URL。

檔案上傳工作階段狀態

用戶端可以透過向檔案上傳工作階段建立回應中的 links.file-upload-session URL 發送 GET 請求來查詢檔案上傳工作階段狀態。伺服器以與檔案上傳工作階段建立回應相同的負載回應此請求，但反映了 status 和 expires-at 的任何變化。

延長檔案上傳工作階段

伺服器 可以 (MAY) 允許用戶端延長檔案上傳工作階段，但總存留期和允許的延長次數由伺服器決定。要延長檔案上傳工作階段，用戶端向檔案上傳工作階段建立回應中的 links.file-upload-session URL 發送 POST 請求。

請求如下所示：

{
  "meta": {
    "api-version": "2.0"
  },
  "action": "extend",
  "extend-for": 3600
}

指定的秒數僅是用戶端對伺服器關於延長當前檔案上傳工作階段額外秒數的建議。例如，如果用戶端希望將工作階段再延長一小時，extend-for 將為 3600。成功延長後，伺服器將以與初始建立發佈工作階段時相同的檔案上傳工作階段建立回應主體進行回應，但反映了 status 或 expires-at 的任何變化。

如果伺服器拒絕延長所請求的秒數，它 必須 (MUST) 仍然傳回成功回應，且 expires-at 鍵將僅反映工作階段當前的過期時間。

必要檔案上傳機制

Content-Type: application/octet-stream

<binary contents of the file to upload>

Content-Type: application/json

[{"version": 1, "verification_material": {...}, "envelope": {...}},...]

伺服器特定檔案上傳機制

特定伺服器 可以 (MAY) 實作任意數量的伺服器特定機制，並負責記錄其用法。

伺服器特定實作的檔案上傳機制識別碼由三個部分組成：

<prefix>-<operator identifier>-<implementation identifier>

伺服器特定實作 必須 (MUST) 使用 vnd 作為其 prefix。operator identifier 應該 (SHOULD) 清楚地識別伺服器營運者，與其他知名索引區分開來，且僅包含英數字元 [a-z0-9]。implementation identifier 應該 (SHOULD) 簡明地描述底層實作，且僅包含英數字元 [a-z0-9] 和 -。

當伺服器營運者需要對其上傳機制進行重大變更時，應該 (SHOULD) 建立新的機制識別碼，而不是修改現有的。推薦的模式是在實作識別碼後附加版本後綴，如 -v1、-v2 等。這允許用戶端明確選擇使用新版本，同時保持與現有用戶端的向後相容性。

例如

如果伺服器打算精確匹配另一個伺服器實作的行為，則 可以 (MAY) 回應該實作的檔案上傳機制名稱。