创建发布会话

发布通过创建新的发布会话开始。要创建会话，客户端向根 URL 提交一个 POST 请求，例如

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

该请求包含以下顶层键

meta (必需)

描述关于有效载荷本身的信息。目前，唯一定义的子键是 api-version，其值必须是字符串 "2.0"。可选的子键可以定义索引特定的行为。

name (必需)

此会话尝试发布新版本的项目名称。该名称**必须**符合标准包名称格式，并且服务器**必须**规范化该名称。

version (必需)

此会话尝试添加文件的项目版本。版本字符串**必须**符合包版本规范。

会话创建成功后，服务器返回 201 Created 响应。响应**还必须**包含一个 Location 头部，其中包含与链接.session 键在响应体中相同的 URL。

如果为没有先前发布的项目创建会话，则索引**可以**在会话发布之前保留项目名称，但是**必须不可能**使用“常规”（即未暂存）访问协议导航到该项目，**直到**该阶段发布。如果此首次发布阶段被取消，则索引**应该**删除项目记录，就像从未上传过一样。

会话由创建它的用户拥有，所有后续请求**必须**使用相同的凭据执行，否则后续请求将返回 403 Forbidden。

可选的索引特定元数据

索引可以选择性地定义自己的元数据，用于索引特定的行为。元数据键**必须**以下划线开头，其值应能够轻松且唯一地标识索引。例如，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 响应。

服务器**必须**在响应中包含一个 Location 头部，指向发布会话状态 URL，该 URL 可用于查询当前会话状态。如果服务器返回 202 Accepted，则可以通过轮询该 URL 来观察会话状态的变化。

发布会话取消

要取消发布会话，客户端向会话创建响应体中给出的session链接发出一个DELETE请求。然后，服务器将该会话标记为已取消，并且**应该**清除作为该会话一部分上传的任何数据。将来尝试访问该会话 URL 或任何发布会话 URL**必须**返回404 Not Found。

为了防止悬空会话，服务器也可以自行取消超时会话。建议服务器在一周之内清除其会话，但每个服务器可以选择自己的时间表。服务器**可以**支持客户端引导的会话扩展。

发布会话状态

客户端可以随时通过向links.session URL（也在会话创建响应的Location头部中提供）发出GET请求来查询会话状态。

服务器将以与最初创建发布会话时获得的发布会话创建响应相同的响应来回应此GET请求，但会反映status、expires-at或files的任何更改。

发布会话扩展

服务器**可以**允许客户端延长会话，但总生命周期和允许的延长次数由服务器决定。要延长会话，客户端向links.session URL（与上述相同，也是Location头）发出POST请求。

请求如下所示

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

指定的秒数只是对服务器的一个建议，表示要延长当前会话的额外秒数。例如，如果客户端希望将当前会话再延长一小时，extend-for 将为 3600。成功延长后，服务器将以与最初创建发布会话时获得的发布会话创建响应体相同的响应进行回复，但会反映 status、expires-at 或 files 的任何更改。

如果服务器拒绝按请求的秒数延长会话，它**必须**仍然返回成功响应，并且 expires-at 键将简单地反映会话的当前过期时间。

发布会话令牌

索引**应该**支持暂存预览，以便上传的文件可以在发布前进行实时测试。例如，CI 客户端可以使用预发布 wheel 执行安装测试，以确保其新版本按预期工作，然后才公开发布。

索引通过在发布会话创建响应中返回两个关键信息来宣传其对暂存预览的支持。不支持暂存预览的索引**不得**将其包含在响应中。

session-token 是一个短令牌，如果安装工具希望通过命令行开关支持暂存预览，例如 $TOOL install --staging $SESSION_TOKEN，则可将其用作方便的 UX。 links.stage 键提供了阶段的完整 URL，可以在 CLI 中使用，例如 pip install --extra-index-url $STAGE_URL。会话令牌和 URL **必须**在密码学上不可猜测，但生成令牌的算法留给索引。阶段 URL **必须**可以从会话令牌计算，使用索引文档化的格式，但 URL 的确切格式也留给索引。

创建文件上传会话

创建发布会话后，响应会话链接映射中的upload端点用于开始将新文件上传到该会话。客户端**必须**使用提供的upload URL，并且**不得**假定这些 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 (必需)

正在上传的文件名。文件名**必须**符合源分发文件名规范或二进制分发文件名约定。索引**应该**在请求时验证这些文件名，当文件名不符合时，返回错误部分中描述的400 Bad Request错误代码。

size (必需)

正在上传的文件大小（以字节为单位）。

hashes (必需)

哈希名称到十六进制编码摘要的映射。每个摘要都是由名称中标识的算法哈希后上传文件的校验和。

默认情况下，hashlib 中可用的任何哈希算法都可以用作 hashes 字典的键[3]。至少一个 hashlib.algorithms_guaranteed 中的安全算法**必须**始终包含在内。本 PEP 特别推荐 sha256。

可以一次传递多个哈希，但所有提供的哈希**必须**对文件有效。

mechanism (必需)

客户端打算用于此文件的文件上传机制。此机制**应该**从发布会话创建响应体中公布的机制列表中选择。客户端**可以**在服务器操作员已记录了新的或即将发布的机制，并且该机制可用于“预发布”的情况下发送未公布的机制。

metadata (可选)

如果给定，这是一个字符串值，包含文件的核心元数据。

服务器**可以**使用此请求中提供的数据在允许文件上传之前进行一些完整性检查。这些检查可以包括但不限于

• 检查 filename 是否已存在于已发布的版本中；
• 检查 size 是否会超过任何项目或文件配额；
• 检查提供的 metadata 内容（如果提供）是否有效。

如果服务器确定上传应该继续，它将返回 202 Accepted 响应，并包含以下响应体。发布会话的状态也将包含文件名在 files 映射中。如果服务器因为客户端提供的 mechanism 不受支持而无法继续上传，它**必须**返回 422 Unprocessable Content。服务器**可以**允许文件的并行上传，但不是必需的。如果服务器确定上传无法继续，它**必须**返回 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。

在任何一种情况下，服务器都应包含一个 Location 头部，指向文件上传会话状态 URL。

服务器**必须**允许客户端轮询文件上传会话状态 URL 以观察状态变化。如果服务器响应 202 Accepted，客户端可以轮询文件上传会话状态 URL 以观察状态变化。客户端**应该**尊重文件上传会话状态响应的 Retry-After 头部值。

取消和删除

客户端可以取消正在进行的文件上传会话，或删除已完全上传的文件。在这两种情况下，客户端通过向其要删除的文件的文件上传会话创建响应中的 links.file-upload-session URL 发出 DELETE 请求来执行此操作。

成功的删除请求**必须**响应 204 No Content。

一旦取消或删除，客户端**不得**假定先前的文件上传会话资源或关联的文件上传机制可以重复使用。

替换部分或完全上传的文件

要替换会话文件，文件上传**必须**之前已完成、取消或删除。如果该文件的上传正在进行中，则无法替换文件。

要替换会话文件，客户端应首先取消并删除正在进行的上传。在此之后，可以通过重新启动整个文件上传序列来启动新的文件上传。这意味着再次提供元数据请求以检索新的上传资源 URL。客户端**不得**假定删除后可以重复使用先前的上传资源 URL。

文件上传会话状态

客户端可以通过向文件上传会话创建响应中的links.file-upload-session URL 发出GET请求来查询文件上传会话状态。服务器以与文件上传会话创建响应相同的负载响应此请求，但会反映status和expires-at的任何更改。

文件上传会话扩展

服务器**可以**允许客户端延长文件上传会话，但总生命周期和允许的延长次数由服务器决定。要延长文件上传会话，客户端向文件上传会话创建响应中的links.file-upload-session URL 发出POST请求。

请求如下所示

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

指定的秒数只是对服务器的建议，表示要延长当前文件上传会话的额外秒数。例如，如果客户端希望将会话延长一小时，extend-for 将为 3600。成功延长后，服务器将以与最初创建发布会话时获得的文件上传会话创建响应体相同的响应进行回复，但会反映 status 或 expires-at 的任何更改。

如果服务器拒绝按请求的秒数延长会话，它**必须**仍然返回成功响应，并且 expires-at 键将简单地反映会话的当前过期时间。

必需的文件上传机制

Content-Type: application/octet-stream

<binary contents of the file to upload>

Content-Type: application/json

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

服务器特定文件上传机制

给定的服务器**可以**实现任意数量的服务器特定机制，并负责记录其用法。

服务器特定实现文件上传机制标识符包含三个部分

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

服务器特定实现**必须**使用 vnd 作为其 prefix。operator identifier **应该**清楚地标识服务器操作员，与其他知名索引不同，并且只包含字母数字字符 [a-z0-9]。implementation identifier **应该**简洁地描述底层实现，并且只包含字母数字字符 [a-z0-9] 和 -。

当服务器操作员需要对其上传机制进行破坏性更改时，他们**应该**创建一个新的机制标识符，而不是修改现有机制。推荐的模式是在实现标识符后附加版本后缀，如 -v1、-v2 等。这允许客户端明确选择新版本，同时保持与现有客户端的向后兼容性。

例如

如果服务器打算精确匹配另一个服务器实现的行为，它**可以**使用该实现的文件的上传机制名称进行响应。