版本控制

版本控制将遵循 PEP 629 格式（Major.Minor），其中已将现有 HTML 响应定义为 1.0。由于本 PEP 未引入 API 的新功能，而是描述了现有功能的另一种序列化格式，因此本 PEP 不更改现有的 1.0 版本，而只是描述如何将其序列化为 JSON。

与 PEP 629 类似，如果对新格式的任何更改导致现有客户端无法有效理解该格式，则主要版本号必须递增。

同样，如果格式中添加或删除了功能，但现有客户端仍应能够有效理解该格式，则次要版本必须递增。

不会导致现有客户端无法有效理解格式且不代表添加或删除功能的更改可能发生，而无需更改版本号。

这有意含糊不清，因为本 PEP 认为最好留待未来的 PEP 来进行任何 API 更改时进行调查并决定该更改是否应增加主要或次要版本。

API 的未来版本可能会添加只能在该版本可用序列化子集中表示的内容。所有序列化版本号，在主要版本内，应保持同步，但功能序列化为每种格式的具体方式可能有所不同，包括该功能是否完全存在。

本 PEP 的意图是，API 应该被视为返回数据的 URL 端点，其解释由该数据的版本定义，然后序列化为目标序列化格式。

JSON 序列化

来自 PEP 503 的 URL 结构仍然适用，因为本 PEP 仅为现有 API 添加了一种额外的序列化格式。

以下限制适用于本 PEP 中描述的所有 JSON 序列化响应

• 所有 JSON 响应将 *始终* 是 JSON 对象，而不是数组或其他类型。
• 虽然 JSON 本身不支持 URL 类型，但此 API 中表示 URL 的任何值都可以是绝对或相对的，只要它们指向正确的位置。如果是相对的，则它们相对于当前 URL，就像它是 HTML 一样。
• 可以在 API 响应中的任何字典对象中添加额外的键，并且客户端必须忽略它们不理解的键。
• 所有 JSON 响应都将有一个 meta 键，其中包含与响应本身相关的信息，而不是响应的内容。
• 所有 JSON 响应都将包含 meta.api-version 键，它将是一个字符串，包含 PEP 629 Major.Minor 版本号，具有与 PEP 629 中定义的相同的失败/警告语义。
• 所有 PEP 503 中不特定于 HTML 的要求仍然适用。

{
  "meta": {
    "api-version": "1.0"
  },
  "projects": [
    {"name": "Frob"},
    {"name": "spamspamspam"}
  ]
}

{
  "meta": {
    "api-version": "1.0"
  },
  "name": "holygrail",
  "files": [
    {
      "filename": "holygrail-1.0.tar.gz",
      "url": "https://example.com/files/holygrail-1.0.tar.gz",
      "hashes": {"sha256": "...", "blake2b": "..."},
      "requires-python": ">=3.7",
      "yanked": "Had a vulnerability"
    },
    {
      "filename": "holygrail-1.0-py3-none-any.whl",
      "url": "https://example.com/files/holygrail-1.0-py3-none-any.whl",
      "hashes": {"sha256": "...", "blake2b": "..."},
      "requires-python": ">=3.7",
      "dist-info-metadata": true
    }
  ]
}

内容类型

本 PEP 提议，所有来自简单 API 的响应都应具有标准内容类型，该内容类型描述响应是什么（一个简单 API 响应）、它代表的 API 版本以及所使用的序列化格式。

这种内容类型的结构将是

application/vnd.pypi.simple.$version+format

由于只有主要版本才应干扰客户端试图理解这些 API 响应，因此内容类型中只包含主要版本，并以 v 为前缀，以明确表示它是版本号。

这意味着对于现有的 1.0 API，内容类型将是

• JSON： application/vnd.pypi.simple.v1+json
• HTML： application/vnd.pypi.simple.v1+html

除了以上内容，还支持一个名为 latest 的特殊“元”版本，其目的是允许客户端请求绝对最新版本，而无需事先知道该版本是什么。但是，建议客户端明确说明他们支持哪些版本。

为了支持期望现有 PEP 503 API 响应使用 text/html 内容类型的现有客户端，本 PEP 进一步定义 text/html 作为 application/vnd.pypi.simple.v1+html 内容类型的别名。

版本 + 格式选择

现在有多种可能的序列化方式，我们需要一种机制来允许客户端指示他们能够理解哪些序列化格式。此外，如果可以添加任何可能的 API 新主要版本而不会干扰期望先前 API 版本的现有客户端，那将是有益的。

为了实现这一点，本 PEP 将 HTTP 的服务器驱动内容协商标准化。

虽然本 PEP 不会完全描述服务器驱动内容协商的全部内容，但其流程大致如下

1. 客户端发出一个 HTTP 请求，其中包含一个 Accept 头部，列出了他们能够理解的所有版本+格式内容类型。
2. 服务器检查该头部，选择其中列出的内容类型之一，然后使用该内容类型返回响应（将缺少 Accept 头部视为 Accept: */*）。
3. 如果服务器不支持 Accept 头部中的任何内容类型，则它们可以选择 3 种不同的响应方式
   1. 选择一个不同于客户端请求的默认内容类型并返回带有该内容类型的响应。
   2. 返回 HTTP 406 不可接受 响应，表示所请求的内容类型均不可用，并且服务器无法或不愿选择默认内容类型进行响应。
   3. 返回 HTTP 300 多重选择 响应，其中包含所有可能选择的响应列表。
4. 客户端解释响应，处理服务器可能响应的不同类型的响应。

本 PEP 未指定服务器在处理无法返回的内容类型时所做的选择，并且客户端应准备好以最适合该客户端的方式处理所有可能的响应。

然而，由于对于如何解释 300 多重选择 响应没有标准格式，本 PEP 强烈不鼓励服务器利用该选项，因为客户端将无法理解并选择不同的内容类型进行请求。此外，客户端可能无法理解不同的内容类型，因此最好的情况是此响应可能只被视为与 406 不可接受 错误相同。

本 PEP 确实要求，如果正在使用元版本 latest，服务器必须使用响应中包含的实际版本的内容类型进行响应（即，请求 Accept: application/vnd.pypi.simple.latest+json 返回 v1.x 响应时，其 Content-Type 应为 application/vnd.pypi.simple.v1+json）。

Accept 头部是一个逗号分隔的列表，其中包含客户端理解并能够处理的内容类型。它支持三种不同的格式来请求每种内容类型

• $type/$subtype
• $type/*
• */*

对于选择版本+格式，最有用的就是 $type/$subtype，因为这是实际指定所需版本和格式的唯一方法。

Accept 头部中列出的内容类型的顺序没有特定含义，服务器应将它们都视为同样有效的响应。如果客户端希望指定他们偏好某个内容类型而不是另一个，他们可以使用 Accept 头部中的质量值语法。

这允许客户端通过附加 ;q= 后跟一个介于 0 和 1 之间（含）的值，最多 3 位小数，来指定 Accept 头部中特定条目的优先级。在解释此值时，质量较高的条目优先于质量较低的条目，任何未指定质量的条目将默认为 1。

然而，客户端应记住，服务器可以自由选择他们要求的**任何**内容类型，无论其请求的优先级如何，甚至可能返回他们**未**要求的内容类型。

为了帮助客户端确定从 API 请求收到的响应内容类型，本 PEP 要求服务器始终包含 Content-Type 头部，指示响应的内容类型。这在技术上是一个向后不兼容的更改，但实际上 pip 一直在强制执行此要求，因此实际中断的风险很低。

客户端操作的示例如下所示

import email.message
import requests

def parse_content_type(header: str) -> str:
    m = email.message.Message()
    m["content-type"] = header
    return m.get_content_type()

# Construct our list of acceptable content types, we want to prefer
# that we get a v1 response serialized using JSON, however we also
# can support a v1 response serialized using HTML. For compatibility
# we also request text/html, but we prefer it least of all since we
# don't know if it's actually a Simple API response, or just some
# random HTML page that we've gotten due to a misconfiguration.
CONTENT_TYPES = [
    "application/vnd.pypi.simple.v1+json",
    "application/vnd.pypi.simple.v1+html;q=0.2",
    "text/html;q=0.01",  # For legacy compatibility
]
ACCEPT = ", ".join(CONTENT_TYPES)


# Actually make our request to the API, requesting all of the content
# types that we find acceptable, and letting the server select one of
# them out of the list.
resp = requests.get("https://pypi.ac.cn/simple/", headers={"Accept": ACCEPT})

# If the server does not support any of the content types you requested,
# AND it has chosen to return a HTTP 406 error instead of a default
# response then this will raise an exception for the 406 error.
resp.raise_for_status()


# Determine what kind of response we've gotten to ensure that it is one
# that we can support, and if it is, dispatch to a function that will
# understand how to interpret that particular version+serialization. If
# we don't understand the content type we've gotten, then we'll raise
# an exception.
content_type = parse_content_type(resp.headers.get("content-type", ""))
match content_type:
    case "application/vnd.pypi.simple.v1+json":
        handle_v1_json(resp)
    case "application/vnd.pypi.simple.v1+html" | "text/html":
        handle_v1_html(resp)
    case _:
        raise Exception(f"Unknown content type: {content_type}")

如果客户端只想支持 HTML 或只支持 JSON，那么他们只需从 Accept 头部中移除他们不想要的内容类型，并将接收这些内容类型视为错误。

TUF 支持 - PEP 458

PEP 458 要求所有 API 响应都是可哈希的，并且可以通过相对于仓库根目录的路径唯一标识。对于简单 API 仓库，目标路径是 API 的根目录（例如 PyPI 上的 /simple/）。这在不直接使用标准 HTTP 客户端而使用 TUF 客户端访问 API 时带来了挑战，因为 TUF 客户端无法处理目标可能具有多个不同表示形式，所有这些表示形式都具有不同哈希值的事实。

PEP 458 没有指定简单 API 的目标路径应该是什么，但 TUF 要求目标路径是“文件式”的，换句话说，像 simple/PROJECT/ 这样的路径是不可接受的，因为它从技术上指向一个目录。

值得庆幸的是，目标路径不必实际匹配从简单 API 获取的 URL，它只是一个获取代码知道如何转换为实际需要获取的 URL 的标记。同样的事情也适用于实际 HTTP 请求的其他方面，例如 Accept 头部。

最终，如何将目录映射到文件名超出了本 PEP 的范围（但它将在 PEP 458 的范围内），本 PEP 推迟对如何在 PEP 458 元数据中精确表示这一点做出决定。

然而，目前针对 pip 尝试实现 PEP 458 的 WIP 分支似乎正在使用 simple/PROJECT/index.html 这样的目标路径。这可以修改为包含 API 版本和序列化格式，使用类似 simple/PROJECT/vnd.pypi.simple.vN.FORMAT 的内容。因此，v1 HTML 格式将是 simple/PROJECT/vnd.pypi.simple.v1.html，而 v1 JSON 格式将是 simple/PROJECT/vnd.pypi.simple.v1.json。

在这种情况下，由于 text/html 是 application/vnd.pypi.simple.v1+html 的别名，当通过 TUF 交互时，它最有可能有意义地规范化为更明确的名称。

同样，latest 元版本不应包含在目标中，只应支持显式声明的版本。

这是否意味着 PyPI 计划放弃对 HTML/PEP 503 的支持？

不，PyPI 目前没有计划放弃对 PEP 503 或 HTML 响应的支持。

尽管本 PEP 确实赋予了仓库这样做的灵活性，但这主要是为了确保像使用端点配置机制这样的东西能够正常工作，并确保客户端不会做出任何可能在未来某个时候阻碍优雅地放弃 HTML 支持的假设。

现有的 HTML 响应几乎没有给 PyPI 带来维护负担，也没有迫切需要删除它们。删除它们唯一真正的好处是减少 CDN 中缓存的项目数量。

如果将来 PyPI *确实*希望放弃对它们的支持，那么这样做几乎肯定会成为 PEP 的主题，或者至少是一个公开的、开放的讨论，并且将由显示对最终用户任何影响的指标提供信息。

为什么是 JSON 而不是 X 格式？

JSON 解析器在大多数（如果不是所有）语言中都广泛可用。Python 标准库中也提供 JSON 解析器。它不是完美的格式，但足够好用。

为什么不添加 X 功能？

本 PEP 的总体目标是很少更改或添加。我们将主要侧重于将 HTML 响应中包含的现有信息转换为合理的 JSON 表示。这将包括打包工具所需的 PEP 658 元数据。

本 PEP 中唯一真正新增的功能是能够为一个文件拥有多个哈希。这样做是因为当前的机制仅限于单个哈希，这在过去迁移哈希（md5 到 sha256）时造成了痛苦，而将哈希设为字典并允许多个哈希的成本相当低。

API 的设计通常允许通过添加新键进行进一步扩展，因此如果安装程序可能需要一些新的数据片段，未来的 PEP 可以轻松地提供这些数据。

为什么 URL 中已包含文件名，还要包含文件名？

我们可以通过删除 filename 键并期望客户端从 URL 中提取该信息来减小响应的大小。

目前本 PEP 选择不这样做，主要是因为 PEP 503 明确要求文件名可通过链接的锚点标签获得，尽管这主要是因为必须存在一些东西。目前尚不清楚实际的仓库是否总是将文件名作为 URL 的最后一部分，或者它们是否依赖于锚点标签中的文件名。

它还使响应对人类来说更易读，因为您会得到一个简洁的唯一标识符。

如果我们有充分的信心要求文件名存在于 URL 中，那么我们可以删除此数据并减小 JSON 响应的大小。

为什么不从文件名中分离出其他信息？

目前，客户端需要从文件名中解析出一些信息，例如项目名称、版本、ABI 标签等。我们可以将这些信息分解出来，并将它们作为键添加到文件对象中。

本 PEP 选择不这样做，因为这样做会增加 API 响应的大小，而且大多数客户端无论 API 如何，都将需要从文件名中解析出这些信息。因此，将该功能保留在客户端内部是合理的。

为什么使用内容协商而不是多个 URL？

另一种合理的实现方式是复制 API 路由，并在 URL 本身中包含一些 JSON 标记。例如，将 URL 设置为 /simple/foo.json、/simple/_index.json 等。

这使得一些事情变得更简单，例如 TUF 集成和仓库的完全静态服务（因为 .json 文件可以简单地写入）。

然而，这有两个相当大的问题

• 我们当前的 URL 结构依赖于一个表示“根”的 URL，即 /，用于提供项目列表。如果我们要为 JSON 和 HTML 提供单独的 URL，我们需要想出一种方法来拥有两个根 URL。

  像 / 是 HTML，/_index.json 是 JSON，因为 _index 不是有效的项目名称，这可能行得通。但是 / 是 HTML 如果仓库想要删除对 HTML 的支持，效果就不太好。

  另一个选择是将所有现有的 HTML URL 移到一个命名空间下，同时为 JSON 创建一个新的命名空间。由于 /<project>/ 已定义，我们必须使这些命名空间不是有效的项目名称，因此像 /_html/ 和 /_json/ 这样的名称可能会奏效，然后只需将非命名空间的 URL 重定向到该仓库的“默认”值（可能是 HTML，除非他们已禁用 HTML，那么就是 JSON）。

• 使用单独的 URL，无法很好地支持零配置发现仓库支持 JSON URL，而无需发出额外的 HTTP 请求来确定 JSON URL 是否存在。

  最幼稚的实现方式是请求 JSON URL，然后对每个请求都回退到 HTML URL，但这会严重影响性能，并违反最小化额外 HTTP 请求的目标。

  最可能的实现方式是创建一个某种仓库级别的配置文件，以某种方式指示支持什么。我们将面临与上述相同的命名空间问题，并采取相同的解决方案，像 /_config.json 之类的文件可以保存这些数据，客户端可以首先向其发出 HTTP 请求，如果存在则将其拉取并解析以了解此特定仓库的功能。

• Accept 的使用也允许我们将版本控制添加到此字段中

总而言之，本 PEP 认为这三个问题相结合，使得使用单独的 API 路由不如依赖内容协商来选择数据最理想的表示形式。

这是否意味着不再支持静态服务器？

简而言之，不，静态服务器仍然（几乎）完全受本 PEP 支持。

它们如何得到支持的具体细节将取决于相关的静态服务器。例如

• S3： S3 完全支持自定义内容类型，但它不支持任何形式的内容协商。为了在 S3 上托管服务器，您必须使用“端点配置”样式的协商，并且用户必须明确配置其客户端。
• GitHub Pages： GitHub Pages 不支持自定义内容类型，因此 S3 解决方案目前不可行，这意味着只有 text/html 仓库才能正常运行。
• Apache： Apache 完全支持服务器驱动的内容协商，只需配置即可将自定义内容类型映射到特定的扩展名。

为什么不添加 application/json 别名，就像 text/html 一样？

本 PEP 认为，客户端和服务器最好都明确 API 响应的类型，而像 application/json 这样的内容类型恰恰相反。

text/html 别名的存在主要是一种折衷方案，以确保 API 的现有消费者继续像以前一样运行。对于使用 application/json 内容类型的现有客户端，没有这样的期望。

此外，application/json 中没有版本控制，这意味着如果将来出现简单 API 的 2.x 版本，我们将被迫做出决定。是 application/json 应保持向后兼容并继续作为 application/vnd.pypi.simple.v1+json 的别名，还是应更新为 application/vnd.pypi.simple.v2+json 的别名？

这个问题对于 text/html 不存在，因为假设 HTML 将保持为传统格式，并且可能不会获得任何新功能，更不用说需要破坏兼容性的功能。因此，将其作为 application/vnd.pypi.simple.v1+html 的别名实际上与将其作为 application/vnd.pypi.simple.latest+html 的别名相同，因为 1.x 可能将是唯一存在的 HTML 版本。

添加 application/json 内容类型的最大好处是，有些事物不允许您拥有自定义内容类型，并要求您选择其预设内容类型之一。这方面的主要例子是 GitHub Pages，本 PEP 中缺少 application/json 支持意味着静态仓库将无法再托管在 GitHub Pages 上，除非 GitHub 添加 application/vnd.pypi.simple.v1+json 内容类型。

本 PEP 认为，目前添加该内容类型别名的好处不足以弥补其弊端，并且其包含可能会成为一个“自挖陷阱”，让毫无戒心的用户不小心使用。特别是考虑到我们将来总是可以添加它，但删除它则要困难得多。

为什么添加 application/vnd.pypi.simple.v1+html？

PEP 预计 API 的 HTML 版本将成为旧版，因此它可能采取的一个选项是不添加 application/vnd.pypi.simple.v1+html 内容类型，而只使用 text/html。

本 PEP 决定添加新的内容类型总体来说更好，因为它使旧版格式更具自描述性，并使它们彼此之间更加一致。总的来说，我认为如果 +html 版本不存在会更令人困惑。

为什么是 v1.0 而不是 v1.1 或 v2.0？

本 PEP 仍然完全向后兼容能够读取现有 v1.0 API 的客户端，在进行这些更改后仍然可以继续读取 API。在 PEP 629 中，主要版本升级的条件是

增加主要版本用于表示向后不兼容的更改，使得现有客户端不再能够有效使用 API。

本 PEP 中的更改不符合该标准，没有任何更改导致现有客户端不再能够有效使用 API。

这意味着我们仍应在 v1.x 版本系列内。

关于我们应该是 v1.1 还是 v1.0 的问题更有趣，有几种看待方式

• 我们已经向 API 暴露了新功能（项目页面上的项目名称、多个哈希），这表明我们应该增加次要版本。
• 新功能完全存在于 JSON 序列化中，这意味着当前请求 HTML 1.0 页面的客户端无论如何都不会看到任何新功能，因此对它们来说，它实际上仍然是 v1.0。
• 目前还没有主要的客户端实现对 PEP 629 的支持，这意味着次要版本编号在这一点上很大程度上是学术性的，因为它旨在让客户端向最终用户提供反馈。

上述第二点和第三点最终使第一点变得毫无意义，因此，将所有内容都称为 v1.0，并在未来更严格地更新版本更有意义。