111 lines
4.6 KiB
ReStructuredText
111 lines
4.6 KiB
ReStructuredText
PEP: 700
|
|
Title: Additional Fields for the Simple API for Package Indexes
|
|
Author: Paul Moore <p.f.moore@gmail.com>
|
|
PEP-Delegate: Donald Stufft <donald@stufft.io>
|
|
Discussions-To: https://discuss.python.org/t/pep-700-additional-fields-for-the-simple-api-for-package-indexes/20177
|
|
Status: Draft
|
|
Type: Standards Track
|
|
Topic: Packaging
|
|
Content-Type: text/x-rst
|
|
Created: 21-Oct-2022
|
|
Post-History: `21-Oct-2022 <https://discuss.python.org/t/pep-700-additional-fields-for-the-simple-api-for-package-indexes/20177>`__
|
|
|
|
|
|
Abstract
|
|
========
|
|
|
|
:pep:`691` defined a JSON form for the "Simple Repository API". This allowed
|
|
clients to more easily query the data that was previously only available in
|
|
HTML, as defined in :pep:`503`.
|
|
|
|
This proposal adds three *optional* additional fields to the JSON form, which
|
|
allow it to be used in place of PyPI's `JSON API <https://warehouse.pypa.io/api-reference/json.html>`__
|
|
in a number of situations.
|
|
|
|
- A field to allow retrieval of a list of all the published versions of a project.
|
|
- Fields containing the size and upload time for a project file.
|
|
|
|
|
|
Specification
|
|
=============
|
|
|
|
The proposal adds three new fields to the JSON form of the "project detail"
|
|
pages in the simple index, located at the URL ``/<project>/``. These fields are
|
|
*not* available in the HTML form of the page.
|
|
|
|
An index MUST provide all of the specified information, for all projects and
|
|
files, if it provides any of it. In other words, while indexes may choose to
|
|
only support the base :pep:`691`, if they choose to support this PEP they must
|
|
do so completely.
|
|
|
|
In addition, as a technical point, this PEP reserves all field names in the JSON
|
|
form beginning with an underscore as available for private use by indexes - no
|
|
future PEP will assign a standardised meaning to such names.
|
|
|
|
Versions
|
|
--------
|
|
|
|
An additional key, ``versions`` MAY be present at the top level, in addition to
|
|
the keys ``name``, ``files`` and ``meta`` defined in :pep:`691`. This key, if
|
|
present, MUST contain a list of version strings conforming to :pep:`440`, which
|
|
list all of the project versions uploaded for this project.
|
|
|
|
All of the files listed in the ``files`` key MUST be associated with one of the
|
|
versions in the ``versions`` key, if present. The ``versions`` key MAY contain
|
|
versions with no associated files.
|
|
|
|
Additional file information
|
|
---------------------------
|
|
|
|
The elements of the ``files`` key MAY 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 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.
|
|
|
|
FAQ
|
|
===
|
|
|
|
Why not add this data to the HTML API as well?
|
|
----------------------------------------------
|
|
|
|
It would be possible to add the data to the HTML API, but the vast majority of
|
|
consumers for this data are likely to be currently getting it from the PyPI JSON
|
|
API, and so will already be expecting to parse JSON. Traditional consumers of
|
|
the HTML API have never needed this data previously.
|
|
|
|
Does this imply that the HTML API is obsolete?
|
|
----------------------------------------------
|
|
|
|
No. The FAQ of :pep:`691` was clear that the HTML API is not being deprecated,
|
|
and this PEP does not change that position. However, clients wishing to access
|
|
the new data introduced by this PEP will need to use the JSON API to get it. And
|
|
indexes wanting to provide it will need to serve the JSON format.
|
|
|
|
Why not allow other date formats?
|
|
---------------------------------
|
|
|
|
The ISO 8601 standard is complex, and there seems little value in requiring
|
|
clients to deal with that. The standard library ``datetime`` module provides
|
|
methods to parse ISO 8601 strings, but it is possible that users may want to
|
|
access index data *without* using Python (for example, piping the output of
|
|
``curl`` into ``jq``). Having a single, well-defined format makes this easier,
|
|
and doesn't have any significant disadvantages.
|
|
|
|
What if file sizes are too big for a JSON number?
|
|
-------------------------------------------------
|
|
|
|
The JSON standard does not specify how numbers are to be interpreted. Python can
|
|
read and write arbitrary-length integers in a JSON file, so this should not be
|
|
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.
|
|
|
|
|
|
Copyright
|
|
=========
|
|
|
|
This document is placed in the public domain or under the
|
|
CC0-1.0-Universal license, whichever is more permissive.
|