address general content feedback from review

Author: ewdurbin

peps/pep-0694.rst

@@ -14,22 +14,23 @@ Post-History: `27-Jun-2022 <https://discuss.python.org/t/pep-694-upload-2-0-api-
 Abstract
 ========
 
-This PEP proposes a standard API for uploading files to a Python package index such as PyPI.  Along
-with standardization, the upload API provides additional useful features such as support for:
+This PEP proposes an extensible API for uploading files to a Python package index such as PyPI.
+Along with standardization, the upload API provides additional useful features such as support for:
 
 * an upload session, which can be used to simultaneously publish all wheels in a package release;
 
-* "staging" a release, which can be used to test uploads before publicly publishing them, without the
-  need for `test.pypi.org <https://test.pypi.org/>`__;
+* "staging" a release, which can be used to test uploads before publicly publishing them,
+  without the need for `test.pypi.org <https://test.pypi.org/>`__;
 
 * artifacts which can be overwritten and replaced, until a session is published;
 
-* flexible file upload mechanisms for index operators;
-
 * detailed status on the state of artifact uploads;
 
 * new project creation without requiring the uploading of an artifact.
 
+* a protocol to extend the supported upload mechanisms in the future without requiring a full PEP;
+  these can be standardized and recommended for all indexes, or be index-specific;
+
 Once this new upload API is adopted, the existing legacy API can be deprecated, however this PEP
 does not propose a deprecation schedule for the legacy API.
 
@@ -77,11 +78,12 @@ In addition, there are a number of major issues with the legacy API:
 * Creation of new projects requires the uploading of at least one file, leading to "stub" uploads
   to claim a project namespace.
 
-The new upload API proposed in this PEP provides a solution to all of these problems,
-providing for a much more flexible approach, with support for servers to
-implement resumable and parallel uploads via mechanisms,
-better error reporting, better release testing experience,
+The new upload API proposed in this PEP provides an immediate solution to many of these problems,
+and defines a flexible mechanism for future support of the other problems by extension.
+Indexes implementing this API will provide better error reporting,
+better release testing experience,
 and atomic and simultaneous publishing of all release artifacts.
+In the future indexes can implement resumable and parallel uploads via extensions.
 
 
 Legacy API
@@ -154,8 +156,9 @@ these steps:
 
 #. Initiate an upload session, creating a release stage.
 #. Initiate file-upload session(s) to that stage as part of the upload session.
-#. Execute file upload mechanism for the file-upload session(s).
-#. Complete the file-upload session(s), marking them as executed or canceled.
+#. Negotiate the specific file upload mechanism to use between client and server.
+#. Execute file upload mechanism for the file-upload session(s) using the negotiated mechanism.
+#. Complete the file-upload session(s), marking them as completed or canceled.
 #. Complete the upload session, publishing or discarding the stage.
 #. Optionally check the status of an upload session.
 
@@ -178,6 +181,8 @@ All URLs described here are relative to the "root endpoint", which may be locate
 the url structure of a domain. For example, the root endpoint could be
 ``https://upload.example.com/``, or ``https://example.com/upload/``.
 
+The choice of the root endpoint is left up to the index operator.
+
 .. _session-create:
 
 Create an Upload Session
@@ -271,7 +276,8 @@ the following keys:
     which are provided below.
 
 ``mechanisms``
-    A list of file-upload mechanisms supported by the server.
+    A list of file-upload mechanisms supported by the server, sorted in server-preferred order.
+    At least one value is required.
 
 ``session-token``
     If the index supports :ref:`previewing staged releases <staged-preview>`, this key will contain
@@ -427,8 +433,7 @@ the file to be uploaded.  These checks may include, but are not limited to:
 If the server determines that upload should proceed, it will return a ``202 Accepted`` response, with
 the response body below. The :ref:`status <session-status>` of the session will also include the filename in the ``files`` mapping. If the server determines the upload cannot proceed, it **MUST** return
 a ``409 Conflict``.  The server **MAY** allow parallel uploads of files, but is not required to.
-If the server cannot proceed with an upload because the ``mechanism`` supplied by the client is not supported
-it **MUST** return a ``422 Unprocessable Entity``.
+If the server cannot proceed with an upload because the ``mechanism`` supplied by the client is not supported it **MUST** return a ``422 Unprocessable Entity``.
 
 .. _file-upload-session-response:
 
@@ -511,13 +516,18 @@ The requests looks like:
       "action": "complete",
     }
 
+After receiving this requests the server **MAY** perform additional asynchronous processing
+on the file, for instance to verify its hashes or contents.
 
-After receiving this requests the server **MAY** perform additional asynchronous processing on the file,
-for instance to verify its hashes or contents.
-If the processing is required to complete before an upload session can be published,
-the status of the file upload session can be set to ``processing`` until such processing is complete,
-reaches an error state, or the file upload session is canceled.
+If the file upload session requires no further processing, the server **MUST** respond with a
+``200 OK`` and the status of the file upload session **MUST** be set to set to ``complete``.
 
+If such processing is required to complete before an upload session can be published,
+the server **MUST** respond with a ``202 Accepted`` and the status
+of the file upload session **MUST** be set to ``processing`` until such processing is complete,
+reaches an error state, or the file upload session is canceled.
+Clients can query the file upload session :ref:`status <session-status>` by issuing a GET request to
+the ``file-upload-session`` :ref:`link <file-upload-session-links>`.
 
 .. _file-upload-session-cancelation:
 
@@ -760,7 +770,7 @@ interpretation to aid in diagnosing underlying issue.
 File Upload Mechanisms
 ----------------------
 
-Servers **MUST** implement :ref:`required file upload mechansisms <required-file-upload-mechanisms>`.
+Servers **MUST** implement :ref:`required file upload mechanisms <required-file-upload-mechanisms>`.
 Such mechanisms serve as a fallback if no server specific implementations exist.
 
 Each major version of the Upload API **MUST** specify at least one required File Upload Mechanism.