iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PEP 694: Grammar changes + reason phrase deprecation mention (#2685) 

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Donald Stufft <donald@stufft.io>
This commit is contained in:
Wouter Koorn 2022-06-29 15:15:24 +02:00 committed by GitHub
parent 135e66f311
commit 21dff31c33
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 14 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
pep-0694.rst
View File

@ -13,8 +13,8 @@ Post-History: `27-Jun-2022 <https://discuss.python.org/t/pep-694-upload-2-0-api-
Abstract
========
There currently is not a standardized API for uploading files to a Python package
repository such as PyPI. Instead everyone has been forced to reverse engineer
There is currently no standardized API for uploading files to a Python package
repository such as PyPI. Instead, everyone has been forced to reverse engineer
the non-standard API from PyPI.
That API, while functional, leaks a lot of implementation details of the original
@ -38,10 +38,10 @@ Beyond the above, there are a number of major issues with the current API:
not go last, possibly some hard to build packages are attempting to be built
from source.
- It has very limited support for communicating back to the user, limited entirely
to the HTTP status code, and status message (something which I'm not sure is
even technically valid HTTP?). It has no support for multiple errors, warnings,
deprecations, etc.
- It has very limited support for communicating back to the user, with no support
for multiple errors, warnings, deprecations, etc. It is limited entirely to the
HTTP status code and reason phrase, of which the reason phrase has been
deprecated since HTTP/2 (:rfc:`RFC 7540 <7540#section-8.1.2.4>`).
- The metadata for a release/file is submitted alongside the file, however this
metadata is famously unreliable, and most installers instead choose to download
@ -119,20 +119,20 @@ roughly two things:
- The metadata is submitted alongside the file, rather than being parsed from the
file itself.
- This is actually fine if used as a pre-check, but it should be reconciled
- This is actually fine if used as a pre-check, but it should be validated
against the actual ``METADATA`` or similar files within the distribution.
- It supports a single request, using nothing but form data, that either succeeds
or fails, and everything is done and contained within that single request.
We then propose a multiple request workflow, that essentially boils down to:
We then propose a multi-request workflow, that essentially boils down to:
1. Initiate an upload session.
2. Upload the file(s) as part of the upload session.
3. Complete the upload session.
4. (Optional) Check the status of an upload session.
All URLs described here will be relative to the root end point, which may be
All URLs described here will be relative to the root endpoint, which may be
located anywhere within the url structure of a domain. So it could be at
``https://upload.example.com/``, or ``https://example.com/upload/``.
@ -263,7 +263,7 @@ to actually upload each of those files.
There is no set endpoint for actually uploading the file, that is given to the
client by the server as part of the creation of the upload session, and clients
**MUST NOT** assume that there is any stability to what those URLs look like from
**MUST NOT** assume that there is any commonality to what those URLs look like from
one session to the next.
To initiate a file upload, a client sends a ``POST`` request to the upload URL
@ -298,7 +298,7 @@ Besides the standard ``meta`` key, this currently has 4 keys:
Multiple hashes may be passed at a time, but all hashes must be valid for the
file.
- ``metadata``: An optional key that is a string that contains the file's
- ``metadata``: An optional key that is a string containing the file's
`core metadata <https://packaging.python.org/en/latest/specifications/core-metadata/>`_.
Servers **MAY** use the data provided in this response to do some sanity checking
@ -364,7 +364,7 @@ repository, but merely staged until the upload session has completed.
To upload in multiple chunks, a client sends multiple ``POST`` requests to the same
URL as before, one for each chunk.
However, this time the ``Content-Length`` is equal to the size, in bytes, of the
This time however, the ``Content-Length`` is equal to the size, in bytes, of the
chunk that they are sending. In addition, the client **MUST** include a
``Upload-Offset`` header which indicates a byte offset that the content included
in this request starts at and a ``Upload-Incomplete`` header set to ``1``.
@ -443,7 +443,7 @@ Session Status
Similarly to file upload, the session URL is provided in the response to
creating the upload session, and clients **MUST NOT** assume that there is any
stability to what those URLs look like from one session to the next.
commonality to what those URLs look like from one session to the next.
To check the status of a session, clients issue a ``GET`` request to the
session URL, to which the server will respond with the same response that
@ -515,7 +515,7 @@ a ``source`` key, which is a string that indicates what the source of the
error is, and a ``messasge`` key for that specific error.
The ``message`` and ``source`` strings do not have any specific meaning, and
are intended for humans to interpet to figure out what the underlying issue
are intended for human interpetation to figure out what the underlying issue
was.