Skip to content

Commit 3effee2

Browse files
committed
clarify file upload mechanism details
1 parent 7f0798b commit 3effee2

File tree

1 file changed

+31
-14
lines changed

1 file changed

+31
-14
lines changed

peps/pep-0694.rst

Lines changed: 31 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,7 @@ these steps:
159159
#. Complete the upload session, publishing or discarding the stage.
160160
#. Optionally check the status of an upload session.
161161

162+
.. _versioning:
162163

163164
Versioning
164165
----------
@@ -759,26 +760,42 @@ interpretation to aid in diagnosing underlying issue.
759760
File Upload Mechanisms
760761
----------------------
761762

762-
File Upload Mechanisms, with the exception of ``http-post-application-octet-stream`` are left as an
763-
implementation detail specific to each server. Servers **MUST** implement a
764-
``http-post-application-octet-stream`` mechanism. This serves as a fallback if no server specific implementations
765-
exist.
763+
Servers **MUST** implement :ref:`required file upload mechansisms <required-file-upload-mechanisms>`.
764+
Such mechanisms serve as a fallback if no server specific implementations exist.
766765

767-
A given server may implement an arbitrary number of mechanisms and is responsible for documenting
768-
their usage. Implemenatations **SHOULD** be prefixed with a string that clearly identifies the
769-
server and is unique from other well known servers or implementations.
766+
Each major version of the Upload API **MUST** specify at least one required File Upload Mechanism.
770767

771-
If a server intendes to match the behavior of another server's implementation, it **MAY** respond
768+
New required mechanisms **MUST NOT** be added and existing required mechanisms **MUST NOT** be removed
769+
without an update to the :ref:`major version <versioning>`.
770+
771+
A given server **MAY** implement an arbitrary number of server specific mechanisms
772+
and is responsible for documenting their usage.
773+
Server specific implementations **MUST** be prefixed with ``vnd-``
774+
and **SHOULD** further contain a string that clearly identifies the server operator
775+
and is unique from other well known servers or implementations.
776+
777+
For example:
778+
779+
====================================== ================ ========================================================
780+
File Upload Mechanism string Server Operator Mechanism description
781+
====================================== ================ ========================================================
782+
``vnd-pypi-s3multipart-presigned`` PyPI S3 multipart upload via pre-signed URL
783+
``vnd-pypi-fetch`` PyPI File delivered by instructing server to fetch from a URL
784+
``vnd-acmecorp-fetch`` Acme Corp File delivered by instructing server to fetch from a URL
785+
``vnd-acmecorp-postal`` Acme Corp File delivered via postal mail
786+
``vnd-madscience-quantumentanglement`` Mad Science Labs Upload via quantum entanglement
787+
====================================== ================ ========================================================
788+
789+
If a server intends to match the behavior of another server's implementation, it **MAY** respond
772790
with that implementation's file upload mechanism name.
773791

774-
All implementations of this PEP **MUST** implement the ``http-post-application-octet-stream`` file
775-
upload mechanism.
792+
.. _required-file-upload-mechanisms:
776793

777-
``http-post-application-octet-stream`` Mechanism
778-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
794+
Required File Upload Mechanisms
795+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
779796

780-
The ``http-post-application-octet-stream`` mechansism **MUST** be supported servers which
781-
implement this PEP.
797+
``http-post-application-octet-stream``
798+
++++++++++++++++++++++++++++++++++++++
782799

783800
A client executes this mechanism by submitting a ``POST`` request to the ``file_url`` returned in the
784801
``http-post-application-octet-stream`` map of the ``mechanism`` map of the

0 commit comments

Comments
 (0)