端点

现有的上传 API（以及现在已删除的注册 API）位于一个 URL 上，当前为 https://upload.pypi.org/legacy/，要告知要调用的特定 API，您需要添加一个 :action URL 参数，其值为 file_upload。 submit、submit_pkg_info 和 doc_upload 的值也曾经受支持，但现在已不再支持。

它还有一个 protocol_version 参数，理论上允许编写新版本的 API，但在实践中从未发生过，并且该值始终为 1。

因此，在实践中，在 PyPI 上，端点为 https://upload.pypi.org/legacy/?:action=file_upload&protocol_version=1。

编码

要提交的数据作为 POST 请求以 multipart/form-data 的内容类型提交。这是由于历史原因，该 API 实际上并非设计为 API，而是最初 PyPI 实现中的表单，然后编写客户端代码以编程方式提交该表单。

内容

粗略地说，包中包含的元数据作为内容处置为 form-data 且名称为字段名称的部分提交。这些各种元数据名称未记录，并且有时（但并非总是）与 METADATA 文件中使用的名称匹配。大小写很少匹配，但总体而言，METADATA 到 form-data 的转换非常不一致。

然后，文件本身作为名称为 content 的 application/octet-stream 部分发送，如果附加了 PGP 签名，则将其作为名称为 gpg_signature 的 application/octet-stream 部分包含。

版本控制

本 PEP 使用与 PEP 691 中使用的相同的 MAJOR.MINOR 版本控制系统，但除此之外是独立版本控制的。本规范认为现有 API 的版本为 1.0，但除此之外，它不尝试以任何方式修改该 API。

端点

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

{
  "meta": {
    "api-version": "2.0"
  },
  "urls": {
    "upload": "...",
    "draft": "...",
    "publish": "..."
  },
  "valid-for": 604800,
  "status": "pending",
  "files": {},
  "notices": [
    "a notice to display to the user"
  ]
}

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

import base64
import secrets

header = ":" + base64.b64encode(secrets.token_bytes(32)).decode() + ":"

Content-Length: 100000
Upload-Token: :nYuc7Lg2/Lv9S4EYoT9WE6nwFZgN/TcUXyk9wtwoABg=:

Content-Length: 1000
Upload-Token: :nYuc7Lg2/Lv9S4EYoT9WE6nwFZgN/TcUXyk9wtwoABg=:
Upload-Offset: 1001
Upload-Incomplete: 1

错误

所有包含正文的错误响应都将具有如下所示的正文

{
  "meta": {
    "api-version": "2.0"
  },
  "message": "...",
  "errors": [
    {
      "source": "...",
      "message": "..."
    }
  ]
}

除了标准的 meta 键之外，它还有两个顶级键，message 和 errors。

message 键是一个封装此请求中可能发生的所有错误的单一消息。

errors 键是一个特定错误数组，每个错误都包含一个 source 键（表示错误来源的字符串）和一个用于该特定错误的 message 键。

message 和 source 字符串没有任何特定含义，旨在供人类解释以找出潜在的问题。

内容类型

与 PEP 691 一样，本 PEP 建议上传 API 的所有请求和响应都将具有一个标准内容类型，用于描述内容是什么、表示 API 的哪个版本以及使用了什么序列化格式。

此内容类型的结构将为

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

由于只有主版本才会破坏试图理解其中一个 API 内容体的系统，因此内容类型中只会包含主版本，并在前面加上 v 以明确它是一个版本号。

与 PEP 691 不同，本 PEP 不会以任何方式更改现有的 1.0 API，因此服务器需要在与现有上传 API 不同的端点托管本 PEP 中描述的新 API。

这意味着对于新的 2.0 API，内容类型将为

• JSON： application/vnd.pypi.upload.v2+json

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

这些内容类型不适用于文件上传本身，仅适用于上传 API 中的其他 API 请求/响应。文件本身应使用 application/octet-stream 内容类型。

版本+格式选择

同样类似于 PEP 691，本 PEP 将标准化使用服务器驱动的内容协商，以允许客户端请求不同的版本或序列化格式，其中包括 format url 参数。

由于本 PEP 预计现有的遗留 1.0 上传 API 将存在于不同的端点，并且它目前仅提供 JSON 序列化，因此此机制并不是特别有用，客户端只有一个可以请求的版本和序列化。但是，客户端应该设置为在将来添加其他格式或版本的情况下优雅地处理内容协商。

这意味着 PyPI 计划放弃对现有上传 API 的支持吗？

目前 PyPI 还没有任何关于停止支持现有上传 API 的具体计划。

与 PEP 691 不同，这样做有很多好处，因此我们很可能希望在将来某个时候停止对其的支持，但在实施此 API 之前，并且在获得广泛使用之前，制定任何停止支持它的计划都为时尚早。

这个可恢复上传协议基于什么？

是的！

它实际上是 活动互联网草案 中指定的协议，其中作者利用他们在实施 tus 中获得的经验，以完全通用、基于标准的方式提出了可恢复上传的想法。

我们与该规范的唯一偏差是我们没有在第一个 POST 请求中使用 104 Upload Resumption Supported 信息响应。做出此决定的原因有几个

• 104 Upload Resumption Supported 是该草案中唯一不完全依赖于现有标准中已支持的事物的部分，因为它添加了一种新的信息状态。
• 许多客户端和 Web 框架并不好地支持 1xx 信息响应（如果支持的话），添加它会增加实现的复杂性，而收益却很小。
• 104 Upload Resumption Supported 支持的目的是允许客户端确定他们正在与之交互的任意端点是否支持可恢复上传。由于本 PEP 要求服务器支持此功能，因此客户端只需假设他们正在与之交互的服务器支持它，这使得使用它变得没有必要。
• 理论上，如果 1xx 响应的支持得到解决并且草案在其中被接受，我们可以在以后的某个时间添加它，而无需更改 API 的整体流程。

上述草案可能不会被接受，但这并不会真正影响我们。这仅仅意味着我们对可恢复上传的支持是一个特定于应用程序的协议，但仍然完全符合标准。

分块上传 vs tus

本 PEP 目前将文件的实际上传基于来自 tus.io 的一个支持可恢复文件上传的互联网草案。

该协议需要一些东西

• 客户端选择一个安全的 Upload-Token 来识别上传单个文件。
• 如果客户端没有一次上传整个文件，则必须按顺序且按正确顺序提交块，除了最后一个块之外，所有块都必须具有 Upload-Incomplete: 1 标头。
• 上传恢复本质上只是查询服务器以查看他们获得了多少数据，然后发送剩余的字节（作为单个请求或分块）。
• 当服务器成功从客户端获取所有数据时，上传会隐式完成。

这有一个很大的好处，那就是如果客户端不关心恢复下载，则客户端方面支持可恢复上传的工作可以完全忽略。他们只需将文件 POST 到 URL，如果失败，他们只需再次 POST 整个文件。

另一个好处是，即使您确实想要支持恢复，您仍然可以只 POST 文件，除非您需要恢复下载，否则这就是您需要做的全部。

另一个可能只是理论上的好处是，对于散列上传的文件，串行块要求意味着服务器可以在请求之间维护散列状态，为每个请求更新它，然后将该文件写回存储。不幸的是，使用 Python 的 hashlib 实际上无法做到这一点，尽管有一些像 Rehash 这样的库实现了它，但它们不支持 hashlib 的所有散列（具体来说，在撰写本文时不支持 blake2 或 sha3）。

我们可能还需要重建下载以进行处理，以便从其中提取元数据等，这将使其成为一个无关紧要的问题。

缺点是无法并行上传单个文件，因为每个块都必须按顺序提交。

AWS S3 具有类似的 API（大多数 Blob 存储已全部或部分复制了它），他们称之为分块上传。

分块上传的基本流程是

1. 启动分块上传以获取上传 ID。
2. 将文件分成块，并分别上传每个块。
3. 所有块上传完成后，完成上传。- 这是发生任何错误的步骤。

它不直接支持恢复上传，但它允许客户端通过调整他们上传的每个部分的大小来控制故障的“影响范围”，如果任何部分失败，他们只需重新发送这些特定部分。

这具有很大的好处，因为它允许并行上传文件，允许客户端使用多个线程发送数据来最大化其带宽。

我们不需要显式步骤 (1)，因为我们的会话将隐式地为每个文件启动分块上传。

它确实有自己的缺点

• 客户端必须在每个请求上做更多工作才能获得类似于可恢复上传的内容。他们必须将文件分成多个部分，而不是仅仅发出单个 POST 请求，并且只有在出现故障时才需要处理复杂性。
• 完全不关心恢复的客户端仍然必须处理第三个显式步骤，尽管他们可以将整个文件都作为一个部分上传。
  • S3 通过为一次性上传提供另一个 API 来解决此问题，但我宁愿不要为上传同一个文件提供两个不同的 API。
• 验证散列变得稍微复杂了一些。AWS 通过散列每个部分来实现散列分块上传，然后总体散列只是这些散列的散列，而不是内容本身的散列。我们需要知道文件本身的实际散列才能用于 PyPI，因此我们必须在文件完全上传后重建文件并读取其内容并对其进行散列，尽管我们仍然可以使用散列的散列技巧来对上传本身进行校验和。
  • 请参阅上面关于这在实践中是否真的是一个缺点，或者它是否仅仅是理论上的内容。

我倾向于使用 tus 风格的可恢复上传，因为我认为它们更易于使用和实现，主要缺点是我们可能会放弃一些多线程性能，而我个人对此是可以接受的？

我想 S3 风格的多部分上传的一个额外好处是，您不必尝试进行任何类型的并行上传保护，因为它们本身就是受支持的。仅此一项就可能消除大部分服务器端实现的简化。