PEP 694 – 上传 Python 包存储库的 2.0 API

抽象

目前没有用于将文件上传到 Python 包的标准化 API 存储库，例如 PyPI。相反，每个人都被迫进行逆向工程来自 PyPI 的非标准 API。

该 API 虽然功能正常，但泄露了原始 API 的许多实现细节 PyPI 代码库，现在必须在新的代码库和替代实现。

除上述问题外，当前 API 还存在许多主要问题：

它是一个完全同步的 API，这意味着我们被迫拥有一个单一的请求可能会保持打开很长时间，无论是对于上传本身，然后，当存储库处理上传的文件以确定成功时或失败。
它不支持任何恢复上传的机制，其中文件最大 PyPI 的大小略低于 1GB，如果出现这种情况，则浪费了很多带宽大文件在上传结束时出现网络闪烁。
它将单个文件视为原子操作单元，这可能会有问题当一个版本可能有多个二进制轮时，这可能会导致人们获得在上传文件时的不同版本，如果 SDIST 碰巧不是最后去，可能正在尝试构建一些难以构建的软件包从源头。
它对与用户通信的支持非常有限，没有任何支持对于多个错误、警告、弃用等。它完全限于 HTTP 状态代码和原因短语，其中原因短语是自 HTTP/2 （RFC 7540）起已弃用。
发布/文件的元数据与文件一起提交，但是这元数据是出了名的不可靠，大多数安装程序都选择下载整个文件并读取它，部分原因是这种不可靠性。
没有允许存储库执行任何理智的机制在带宽开始在上传上消耗之前进行检查，而很多可以检查无效元数据或不正确权限的情况在上传之前。
它不支持在将草稿发布到之前将其“暂存”到存储库。
它不支持在不上传文件的情况下创建新项目。

此 PEP 提出了一个用于上传的新 API，并弃用了现有的非标准应用程序接口。

现状

这并不是试图成为当前 API 的完全详尽的文档，而是对现有 API 进行高级概述。

端点

现有的上传 API（以及现已删除的注册 API）位于 url 中，用于传达您想要的特定 API 若要调用，请添加值为的 URL 参数。价值观的、和也曾经被支持，但是不再是。https://upload.pypi.org/legacy/:actionfile_uploadsubmitsubmit_pkg_infodoc_upload

它还有一个参数，理论上允许新版本的 API 被编写，但实际上从未发生过，并且值始终为 .protocol_version1

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

编码

要提交的数据将作为具有内容类型的请求提交之。这是由于历史性质，这个 API 实际上并没有被设计为一个 API，而是初始 PyPI 上的一个表单实现，然后编写客户端代码以编程方式提交该表单。POSTmultipart/form-data

内容

粗略地说，包中包含的元数据是作为部分提交的其中 content-disposition 是，name 是田。这些不同元数据的名称没有记录在案，它们有时，但并不总是与文件中使用的名称匹配。外壳虽然很少匹配，但总的来说，到转换是极度不一致。form-dataMETADATAMETADATAform-data

然后，文件本身将作为带有名称的部分发送的，如果附加了 PGP 签名，则它将被包括在内作为名称为的部分。application/octet-streamcontentapplication/octet-streamgpg_signature

规范

此 PEP 跟踪现有 API 的大多数问题的根本原因大致有两件事：

元数据与文件一起提交，而不是从文件本身。
如果用作预检查，这实际上很好，但应该对其进行验证针对发行版中的实际或类似文件。METADATA

它支持单个请求，仅使用表单数据，任一成功或失败，并且一切都已完成并包含在该单个请求中。

然后，我们提出了一个多请求工作流，它基本上可以归结为：

启动上载会话。
在上传会话中上传文件。
完成上传会话。
（可选）检查上传会话的状态。

此处描述的所有 URL 都将相对于根终结点，这可能是位于域的 URL 结构中的任何位置。所以它可能在，或者。https://upload.example.com/https://example.com/upload/

版本控制

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

端点

创建上传会话

要创建新的上传会话，您可以向发送请求，有效负载如下所示：POST/

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

它目前有三个键，、和。metanameversion

该密钥包含在所有有效负载中，它描述了有关有效载荷本身。meta

键是此会话尝试的项目的名称将文件添加到。name

关键是此会话所访问的项目版本将文件添加到。version

如果创建会话成功，则服务器必须返回响应如下所示：

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

除了键之外，此响应还有五个键：、、、和。metaurlsvalid-forstatusfilesnotices

键是将标识符映射到相关 URL 的字典会期。urls

键是一个整数，表示直到服务器本身将使此会话过期（因此，其中包含的所有 URL）都将过期。会话至少应该存在更长的时间，除非客户端本身已取消会话。服务器可以选择增加这个时间，但应该永远不要减少它，除非通过时间的流逝自然而然地减少它。valid-for

键是一个字符串，其中包含、、或之一，此字符串表示会话。statuspendingpublishederroredcanceled

密钥是包含已上传的文件名的映射到此会话，到包含有关每个文件的详细信息的映射。files

该键是一个可选键，它指向一系列通知，该通知服务器希望与最终用户进行通信，但这些通信不是特定于任何用户的一个文件。notices

对于映射中的每个文件名，有三个键，，，和。filesstatusurlnotices

该密钥与顶级密钥相同，只是它指示特定文件的状态。statusstatus

密钥是客户端应上传该特定 URL 的绝对 URL 文件添加到（或用于删除该文件）。url

该键是一个可选键，即服务器通知的数组希望与特定于此文件的最终用户进行通信。notices

成功创建会话所需的响应代码是响应，它必须包含一个标头，该标头是此会话的 URL，可用于检查其状态或取消它。201 CreatedLocation

对于密钥，目前可能会出现三个密钥：urls

密钥，这是此会话要启动的上传终结点文件上传。upload

密钥，即提供这些文件的存储库 URL 在发布之前。draft

密钥，即触发发布会话的终结点。publish

除上述内容外，如果为相同的名称+版本创建第二个会话 pAIr，则上传服务器必须返回已经存在的会话，而不是而不是创建一个新的、空的。

上传每个文件

启动一个或多个文件的上传会话后，您就拥有实际上传每个文件。

没有用于实际上传文件的设置端点，该端点被赋予客户端作为创建上传会话的一部分，并且客户端不得假定这些 URL 的外观有任何共性一个会话到下一个会话。

要启动文件上传，客户端会向上传 URL 发送请求在会话中，请求正文如下所示：POST

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

除了标准密钥外，目前还有 4 个密钥：meta

filename：正在上传的文件的文件名。
size：正在上传的文件的大小（以字节为单位）。
hashes：哈希名称到十六进制编码摘要的映射，每个摘要是该文件的摘要，当由名称中标识的哈希进行哈希处理时。

默认情况下，任何可通过 hashlib 获得的哈希算法（特别是任何可以被传递给并且不需要额外的参数）可以用作哈希字典的键。必须始终包含至少一种来自 SECURE 算法。当时特别推荐使用此 PEP。hashlib.new()hashlib.algorithms_guaranteedsha256

一次可以传递多个哈希值，但所有哈希值必须对文件。

metadata：一个可选键，它是包含文件核心元数据的字符串。

服务器可以使用此响应中提供的数据进行一些健全性检查在允许上传文件之前，这可能包括但不限于自：

检查是否已存在。filename
检查是否会使某些配额无效。size
检查的内容是否有效（如果提供）。metadata

如果服务器确定客户端应尝试上传，它将返回一个响应，正文为空，标头指向到文件本身应上传到的 URL。201 CreatedLocation

此时，会话的状态应显示文件名，并带有上述 url 包含在其中。

上传数据

要上传文件，客户端有两种选择，他们可以将文件上传为单个块，或多个块。任何一种选择都是可以接受的，但它是建议大多数客户端应选择将每个文件作为单个块上传因为这需要更少的请求，并且通常具有更好的性能。

但是，对于特别大的文件，可能会导致在单个请求中上传在超时，因此可能需要在多个区块中上传较大的文件。

无论哪种情况，客户端都必须为每次上传生成唯一的令牌（或随机数）尝试获取文件，并且必须在标头的每个请求中包含该令牌。是使用 base64 编码的二进制 blob ，周围环绕着 a 在两侧。客户端应至少使用 32 字节的加密随机数据。您可以使用以下命令生成它：Upload-TokenUpload-Token:

import base64import secretsheader = ":" + base64.b64encode(secrets.token_bytes(32)).decode() + ":"

允许从上传中省略的一次请求是指客户端希望选择退出可恢复或分块文件上传功能完全。在这种情况下，他们可以省略和文件必须在单个 HTTP 请求中成功上传，如果失败，则必须在另一个 HTTP 请求中重新发送整个文件。Upload-TokenUpload-Token

要在单个块中上传，客户端会从该文件名的会话响应。客户端必须包含一个标头，该标头等于文件的大小（以字节为单位），并且该标头必须与原始会话创建中给出的大小。POSTContent-Length

例如，如果上传一个 100,000 字节的文件，您将发送如下标头：

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

如果上传成功完成，服务器必须以状态进行响应。此时，此文件不得存在于存储库，但只是暂存，直到上传会话完成。201 Created

要上传多个块，客户端会向同一个块发送多个请求 URL 和以前一样，每个块一个。POST

然而，这一次，等于他们正在发送的块。此外，客户端必须包含一个标头，该标头指示内容包含的字节偏移量在此请求中，从开始，标头设置为。Content-LengthUpload-OffsetUpload-Incomplete1

例如，如果以 1000 字节的块上传 100,000 字节的文件，并且此块表示字节 1001 到 2000，您可以发送如下标头：

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

但是，最后一个数据块省略了标头，因为此时，上传不再不完整。Upload-Incomplete

对于每个成功的块，服务器必须使用标头进行响应，但最后一个块除外，该块必须是 .202 Accepted201 Created

以下限制将针对上传，无论它们是否单个块或多个块：

客户端不得并行执行多个请求相同的文件，以避免竞争条件和数据丢失或损坏。服务器可以终止使用相同 .POSTPOSTUpload-Token
如果中提供的偏移量不是或下一个块在不完成的上传中，则服务器必须以 409 冲突进行响应。Upload-Offset0
使用特定令牌开始上传后，不得使用其他令牌对于该文件，而不删除正在进行的上传。
文件上传成功后，您可以启动另一次上传该文件，这样做将替换该文件。

简历上传

要恢复上传，您首先必须知道服务器有多少数据已收到，无论您最初是否将文件上传为单个块或多个块。

要获取单个上传的状态，客户端可以发出请求与它们现有的 URL 相同。HEADUpload-Token

服务器必须使用响应进行响应，并带有指示客户端应继续的偏移量的标头上传自。如果服务器没有收到任何数据，则这将是，如果它接收了 1007 个字节，那么它将是 .204 No ContentUpload-Offset01007

一旦客户端检索到了他们需要从中开始的偏移量，他们就可以如上所述，在单个请求中上传文件的其余部分包含所有剩余数据或多个块。

取消正在进行的上传

如果客户希望取消特定文件的上传，例如，因为他们需要上传不同的文件，他们可以通过向文件上传 URL 发出请求来上传文件。DELETEUpload-Token

成功的取消请求必须以 .204 No Content

删除已上传的文件

可以通过向文件发出请求来删除已上传的文件上传 URL 不带 .DELETEUpload-Token

成功的删除请求必须以 .204 No Content

会话状态

与文件上传类似，会话 URL 在响应中提供创建上传会话，并且客户端不得假定存在任何这些 URL 从一个会话到下一个会话的外观的共性。

要检查会话的状态，客户端会向会话 URL，服务器将使用与他们在最初创建上传会话时获得，但任何对、或 updated 的更改已反映。GETstatusvalid-forfiles

会话取消

要取消上传会话，客户端会向与以前相同的会话 URL。此时，服务器将会话标记为已取消，则可以清除作为该会话的一部分上传的任何数据，将来尝试访问该会话 URL 或任何文件上传 URL 可能会返回 .DELETE404 Not Found

为了防止大量悬空会话，服务器还可以选择取消会议自发。建议服务器清除其会话后不少于一周，但每个服务器可以选择自己的附表。

会话完成

要完成会话并发布已包含在其中的文件，客户端必须向会话状态有效负载。POSTpublish

如果服务器能够立即完成会话，它可能会这样做并返回响应。如果无法立即完成会话（例如，如果它需要进行处理，则可能在单个 HTTP 请求中花费的时间超过合理时间），然后它可能会返回一个回应。201 Created202 Accepted

无论哪种情况，服务器都应包含指向的标头返回到会话状态 URL，如果服务器返回，客户端可能会轮询该 URL 以监视状态是否更改。Location202 Accepted

错误

所有包含正文的错误响应的正文如下所示：

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

除了标准键之外，它还有两个顶级键和 .metamessageerrors

密钥是一条单数消息，它封装了所有错误可能已在此请求上发生。message

键是特定错误的数组，每个错误都包含一个键，它是一个字符串，指示错误是，并且是该特定错误的键。errorssourcemessasge

和字符串没有任何特定含义，并且旨在供人类解释，以找出根本问题是。messagesource

内容类型

与 PEP 691 一样，此 PEP 建议来自上传 API 将具有描述内容的标准内容类型是，它代表的 API 是什么版本，以及序列化格式是什么被使用过。

此内容类型的结构为：

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

由于只有主要版本才应该对试图了解这些 API 内容主体之一，只有主要版本将是包含在内容类型中，并将以 a 为前缀以阐明它是一个版本号。v

与 PEP 691 不同，此 PEP 不会更改任何方式，因此将需要服务器来托管此 PEP 中描述的新 API，网址为与现有上传 API 不同的终结点。1.0

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

JSON格式： application/vnd.pypi.upload.v2+json

除上述内容外，还支持一个名为，其目的是允许客户端请求绝对最新版本，而无需必须提前知道那个版本是什么。但是，建议：客户明确说明他们支持哪些版本。latest

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

版本 + 格式选择

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

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

常见问题

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

目前，PyPI 没有任何具体的计划来放弃对现有上传 API。

与 PEP 691 不同，这样做有广泛的好处，因此很有可能我们希望在未来的某个时候放弃对它的支持，但是在此 API 实现并得到广泛使用之前，它还为时过早制定任何计划来实际放弃对它的支持。

这个断点续传协议是基于什么的吗？

是的！

它实际上是 Active Internet-Draft 中指定的协议，作者利用他们在实施 TUS 时学到的知识，以完全通用的、基于标准的方式提供可恢复上传的想法道路。

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

这是该草案的唯一部分它不完全依赖于现有标准，因为它增加了新的信息状态。104 Upload Resumption Supported
许多客户端和 Web 框架不支持信息性以一种非常好的方式做出回应，如果有的话，添加它会变得复杂实施几乎没有好处。1xx
支持的目的是允许客户端，以确定他们正在交互的任意终结点支持断点续传。由于此 PEP 强制要求支持在服务器中，客户端可以假设它们是服务器与支持它交互，因此不需要使用它。104 Upload Resumption Supported
从理论上讲，如果对响应的支持得到解决，并且草案被接受，我们可以在以后没有更改 API 的整体流程。1xx

上述草案存在不被接受的风险，但即使它被接受没有，这实际上并没有影响我们。这只是意味着我们的对断点续传的支持是特定于应用程序的协议，但仍然完全符合标准。

开放性问题

分段上传与 tus

此 PEP 目前基于互联网草稿的实际文件上传从支持断点续传文件上传的 tus.io。

该协议需要满足以下几点要求：

客户端选择用于标识的安全上传单个文件。Upload-Token
如果客户端没有一次性上传整个文件，那么他们有以正确的顺序连续提交块，除最后一个块有一个标头。Upload-Incomplete: 1
恢复上传本质上只是查询服务器以查看如何他们得到的大量数据，然后发送剩余的字节（作为单个字节请求，或分块）。
当服务器成功获取所有来自客户端的数据。

这有一个很大的好处，如果客户不关心恢复他们的下载，工作支持，从客户端，断点续传是可以的被完全忽略。他们可以只将文件发送到 URL，如果它没有成功，他们可以再次打开整个文件。POSTPOST

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

另一个可能是理论上的好处是，对于上传的文件进行哈希处理，串行块要求意味着服务器可以保持哈希状态在请求之间，为每个请求更新它，然后将该文件写回存储。不幸的是，这实际上不可能与 Python 的 hashlib 一起完成，虽然有一些像 Rehash 这样的库实现了它，但它们并不支持 hashlib 所做的每个哈希（在撰写本文时，具体来说不是 Blake2 或 SHA3）。

无论如何，我们可能还需要重新构建下载以进行处理诸如从中提取元数据等，这将使它成为一个有争议的问题。

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

AWS S3 具有类似的 API（大多数 blob 存储都批量复制了它或类似的东西），他们称之为分段上传。

分段上传的基本流程是：

启动分段上传以获取上传 ID。
将您的文件分解为块，并单独上传每个块。
上传所有区块后，完成上传。 - 这是会发生任何错误的步骤。

它不直接支持恢复上传，但允许客户端通过调整每个零件的尺寸来控制失效的“爆炸半径” 他们上传，如果任何部分出现故障，他们只需要重新发送这些部分特定部分。

这有一个很大的好处，因为它允许在上传文件时并行化，允许客户端使用多个线程发送数据。

我们不需要显式步骤（1），因为我们的会话会隐式为每个文件启动分段上传。

它确实有其自身的缺点：

客户必须对每个请求做更多的工作才能拥有类似的东西续传。他们必须将文件分解为多个部分而不仅仅是发出一个 POST 请求，而只需要处理如果出现问题，则具有复杂性。
根本不关心复工的客户仍然需要处理第三个显式步骤，尽管他们可以将文件全部上传为单件。
S3 通过为一次性上传提供另一个 API 来解决此问题，但我宁愿不要有两个不同的 API 来上传同一个文件。
验证哈希变得更加复杂。AWS 实施哈希通过对每个部分进行哈希处理来上传分段，那么整体哈希只是一个这些哈希值的哈希值，而不是内容本身的哈希值。我们需要知道 PyPI 文件本身的实际哈希值，因此我们必须重新构建文件并读取其内容，并在完全上传后对其进行哈希处理，虽然我们仍然可以使用哈希的哈希技巧来校验和上传自身。
请参阅上文，了解这在实践中是否真的是一个缺点，或者如果只是理论上。

我倾向于 tus 风格的可恢复上传，因为我认为它们更简单使用和实施，主要的缺点是我们可能会离开桌面上的一些多线程性能，我认为我是个人还好吗？

我想 S3 风格的多部分上传的另一个好处是您不必尝试对并行上传进行任何形式的保护，因为它们只是受支持。仅此一项就可能抹去大部分服务器端实施简化。

版权

本文档被置于公共领域或位于 CC0-1.0-通用许可证，以更宽松的许可证为准。

The End