PEP 700: Make upload time optional (gh-2873)

pep-0700.rst

@@ -47,11 +47,11 @@ version of the API, the following changes are made:
 - A new ``versions`` key is added at the top level.
 - Two new "file information" keys, ``size`` and ``upload-time``, are added to
   the ``files`` data.
-- Keys (at any level) named with a leading underscore are reserved as private
+- Keys (at any level) with a leading underscore are reserved as private for
-  for index server use. No future standard will assign a meaning to any such key.
+  index server use. No future standard will assign a meaning to any such key.
 
-All new fields are mandatory (although ``upload-time`` may be ``None`` if the
+The ``versions`` and ``size`` keys are mandatory. The ``upload-time`` key is
-server does not store that information).
+optional.
 
 Versions
 --------
@@ -77,18 +77,17 @@ possible.
 Additional file information
 ---------------------------
 
-The elements of the ``files`` key MUST contain two additional sub-keys, ``size``
+Two new keys are added to the ``files`` key.
-and ``upload-time``. The ``size`` field MUST contain an integer which is the
-file size in bytes, and the ``upload-time`` field MUST contain either ``null``
-(see below) or a valid ISO 8601 date/time string, in the format
-``yyyy-mm-ddThh:mm:ss.ffffffZ``, which represents the time the file was uploaded
-to the index. As indicated by the ``Z`` suffix, the upload time MUST use the UTC
-timezone. The fractional seconds part of the timestamp (the ``.ffffff`` part) is
-optional, and if present may contain up to 6 digits of precision.
 
-If a server does not record upload time information for a file, it MAY return
+- ``size``: This field is mandatory. It MUST contain an integer which is the
-a value for ``upload-time`` of ``None`` (``null`` in JSON). However, it MUST
+  file size in bytes.
-NOT omit the key.
+- ``upload-time``: This field is optional. If present, it MUST contain a valid
+  ISO 8601 date/time string, in the format ``yyyy-mm-ddThh:mm:ss.ffffffZ``,
+  which represents the time the file was uploaded to the index. As indicated by
+  the ``Z`` suffix, the upload time MUST use the UTC timezone. The fractional
+  seconds part of the timestamp (the ``.ffffff`` part) is optional, and if
+  present may contain up to 6 digits of precision. If a server does not record
+  upload time information for a file, it MAY omit the ``upload-time`` key.
 
 
 FAQ
@@ -143,24 +142,6 @@ an issue for code written in Python. Non-Python implementations may need to take
 care to handle large integers correctly, but this is not expected to be a
 significant problem.
 
-Why is it not possible to serve some of the new information, but not all?
--------------------------------------------------------------------------
-
-The versioning scheme for the simple API does not allow servers to "mix and
-match" what information they provide, except by making fields optional, and
-handling optional fields is an inconvenience for clients using the API. The
-PEP takes the view that ease of use for clients should be the priority (as
-there will always be more clients than servers).
-
-The main problem for servers is likely to be the upload time, as some servers
-may not retain this information. For this situation, a server is allowed to
-return a null value for the upload time, indicating that the value is not known.
-
-Version and file size information do not have a "not known" option, as they
-should not need them. Versions can be determined from the file names if
-necessary, and file size information is needed to serve the files, so it should
-always be possible for the server to determine it.
-
 Why not require PEP 440 versions?
 ---------------------------------