版本控制

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

与 PEP 629 类似，如果对新格式的任何更改会导致不再能够期望现有客户端有意义地理解该格式，则**必须**递增主版本号。

同样，如果向格式添加或删除功能，但现有客户端预计将继续有意义地理解该格式，则**必须**递增次版本号。

不会导致现有客户端无法有意义地理解格式并且不代表添加或删除功能的更改可以在不更改版本号的情况下发生。

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

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 中定义的相同失败/警告语义。

• 所有不特定于 HTML 的 PEP 503 要求仍然适用。

{
  "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 建议 Simple API 的所有响应都将具有一个标准内容类型，该类型描述响应是什么（Simple 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. 客户端发出包含 Accept 标头的 HTTP 请求，该标头列出他们能够理解的所有版本+格式内容类型。
2. 服务器检查该标头，选择列出的内容类型之一，然后使用该内容类型返回响应（将缺少 Accept 标头视为 Accept: */*）。
3. 如果服务器不支持 Accept 标头中的任何内容类型，则可以选择 3 种不同的响应方式
   1. 选择客户端请求之外的默认内容类型并使用该类型返回响应。
   2. 返回 HTTP 406 Not Acceptable 响应以指示没有可用的请求内容类型，并且服务器无法或不愿选择默认内容类型进行响应。
   3. 返回 HTTP 300 Multiple Choices 响应，其中包含可能已选择的响应列表。
4. 客户端解释响应，处理服务器可能已响应的不同类型的响应。

此 PEP 没有指定服务器在处理无法返回的内容类型时做出的选择，并且客户端**应该**准备好以对该客户端最有意义的方式处理所有可能的响应。

然而，由于没有关于如何解释300 Multiple Choices响应的标准格式，此PEP强烈建议服务器不要使用该选项，因为客户端将无法理解并选择不同的内容类型来请求。此外，客户端不太可能理解其他内容类型，因此，此响应充其量可能只会像406 Not Acceptable错误一样处理。

此PEP**确实**要求，如果正在使用元版本latest，则服务器**必须**以响应中包含的实际版本的content-type进行响应（例如，一个返回v1.x响应的Accept: application/vnd.pypi.simple.latest+json请求应该具有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/）。当使用TUF客户端而不是直接使用标准HTTP客户端访问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的目标路径。这可以通过使用类似simple/PROJECT/vnd.pypi.simple.vN.FORMAT的内容来修改，以包含API版本和序列化格式。因此，v1 HTML格式将是simple/PROJECT/vnd.pypi.simple.v1.html，v1 JSON格式将是simple/PROJECT/vnd.pypi.simple.v1.json。

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

同样，元版本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 创建一个新的命名空间。由于 / 已定义，我们需要使这些命名空间成为无效的项目名称，因此类似于 /_html/ 和 /_json/ 的方式可以，然后将非命名空间 URL 重定向到该存储库的“默认”值（可能是 HTML，除非它们已禁用 HTML，否则为 JSON）。

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

  对此最简单的实现是请求 JSON URL，并对每个请求回退到 HTML URL，但这在性能上非常糟糕，并且违反了减少额外 HTTP 请求的目标。

  对此最可能的实现是创建某种存储库级别的配置文件，该文件以某种方式指示支持的内容。我们将遇到与上面相同的命名空间问题，以及相同的解决方案，例如 /_config.json 可以保存这些数据，客户端可以首先向其发出 HTTP 请求，如果存在则将其下载并解析以了解此特定存储库的功能。

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