From 38192e0ba9697c2d2de88eed2c1326bf40a7e4b3 Mon Sep 17 00:00:00 2001 From: Paul Moore Date: Mon, 7 Nov 2022 19:38:37 +0000 Subject: [PATCH] PEP 700: Make upload time optional (gh-2873) --- pep-0700.rst | 47 ++++++++++++++--------------------------------- 1 file changed, 14 insertions(+), 33 deletions(-) diff --git a/pep-0700.rst b/pep-0700.rst index 8175c7c00..92e554cf8 100644 --- a/pep-0700.rst +++ b/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 - for index server use. No future standard will assign a meaning to any such key. +- Keys (at any level) with a leading underscore are reserved as private for + 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 -server does not store that information). +The ``versions`` and ``size`` keys are mandatory. The ``upload-time`` key is +optional. Versions -------- @@ -77,18 +77,17 @@ possible. Additional file information --------------------------- -The elements of the ``files`` key MUST contain two additional sub-keys, ``size`` -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. +Two new keys are added to the ``files`` key. -If a server does not record upload time information for a file, it MAY return -a value for ``upload-time`` of ``None`` (``null`` in JSON). However, it MUST -NOT omit the key. +- ``size``: This field is mandatory. It MUST contain an integer which is the + file size in bytes. +- ``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? ---------------------------------