Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PEP 691: touch up #2668

Merged
merged 1 commit into from
Jun 24, 2022
Merged

PEP 691: touch up #2668

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 27 additions & 33 deletions pep-0691.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,8 @@ return data, whose interpretation is defined by the version of that data, and th
serialized into the target serialization format.


.. _json-serialization:

JSON Serialization
------------------

Expand Down Expand Up @@ -217,13 +219,14 @@ Project Detail
~~~~~~~~~~~~~~

The format of this URL is ``/<project>/`` where the ``<project>`` is replaced by the
:pep:`503` normalized name for that project, so a project named "Holy_Grail" would
have a URL like ``/holy-grail/``.
:pep:`503` normalized name for that project, so a project named "Silly_Walk" would
have a URL like ``/silly-walk/``.

This URL must respond with a JSON encoded dictionary that has three keys:

This URL must respond with a JSON encoded dictionary that has three keys, ``name``,
which represents the normalized name of the project, ``files``. The ``files`` key is
a list of dictionaries, each one representing an individual file. Finally the ``meta``
key which is the general response metadata described earlier.
- ``name``: The normalized name of the project.
- ``files``: A list of dictionaries, each one representing an individual file.
- ``meta``: The general response metadata as `described earlier <json-serialization_>`__.

Each individual file dictionary has the following keys:

Expand All @@ -236,7 +239,7 @@ Each individual file dictionary has the following keys:

The ``hashes`` dictionary **MUST** be present, even if no hashes are available
for the file, however it is **HIGHLY** recommended that at least one secure,
guaranteed to be available hash is always included.
guaranteed-to-be-available hash is always included.

By default, any hash algorithm available via `hashlib
<https://docs.python.org/3/library/hashlib.html>`_ (specifically any that can
Expand All @@ -254,11 +257,12 @@ Each individual file dictionary has the following keys:
- ``dist-info-metadata``: An **optional** key that indicates
that metadata for this file is available, via the same location as specified in
:pep:`658` (``{file_url}.metadata``). Where this is present, it **MUST** be
boolean to indicate if the file has an associated metadata file, or a dictionary
mapping hash names to a hex encoded digest of the metadata's hash.
either a boolean to indicate if the file has an associated metadata file, or a
dictionary mapping hash names to a hex encoded digest of the metadata's hash.

When this is a dictionary of hashes, then all the same requirements and
recommendations as the ``hashes`` key hold true for this key as well.
When this is a dictionary of hashes instead of a boolean, then all the same
requirements and recommendations as the ``hashes`` key hold true for this key as
well.

If this key is missing then the metadata file may or may not exist. If the key
value is truthy, then the metadata file is present, and if it is falsey then it
Expand All @@ -267,11 +271,12 @@ Each individual file dictionary has the following keys:
It is recommended that servers make the hashes of the metadata file available if
possible.
- ``gpg-sig``: An **optional** key that acts a boolean to indicate if the file has
an associated GPG signature or not. If this key does not exist, then the signature
may or may not exist.
- ``yanked``: An **optional** key which may be a boolean to indicate if the file
has been yanked, or a non empty, but otherwise arbitrary, string to indicate that
a file has been yanked with a specific reason. If the ``yanked`` key is present
an associated GPG signature or not. The URL for the signature file follows what
is specified in :pep:`503` (``{file_url}.asc``). If this key does not exist, then
the signature may or may not exist.
- ``yanked``: An **optional** key which may be either a boolean to indicate if the
file has been yanked, or a non empty, but otherwise arbitrary, string to indicate
that a file has been yanked with a specific reason. If the ``yanked`` key is present
and is a truthy value, then it **SHOULD** be interpreted as indicating that the
file pointed to by the ``url`` field has been "Yanked" as per :pep:`592`.

Expand Down Expand Up @@ -417,7 +422,7 @@ content type over another, they may use the ``Accept`` header's
syntax.

This allows a client to specify a priority for a specific entry in their
``Accept`` header, by append a ``;q=`` followed by a value between ``0`` and
``Accept`` header, by appending a ``;q=`` followed by a value between ``0`` and
``1`` inclusive, with up to 3 decimal digits. When interpreting this value,
an entry with a higher quality has priority over an entry with a lower quality,
and any entry without a quality present will default to a quality of ``1``.
Expand Down Expand Up @@ -607,14 +612,15 @@ It is recommended that servers:
long as they're receiving non trivial traffic that uses the HTML responses.

- When encountering an ``Accept`` header that does not contain any content types
that it knows how to work with, should not ever return a ``300 Multiple Choice``
response, and it should be preferred to return a ``406 Not Acceptable`` response.
that it knows how to work with, the server should not ever return a
``300 Multiple Choice`` response, and instead return a ``406 Not Acceptable``
response.

- However, if choosing to use the endpoint configuration, you should prefer to
return a ``200 OK`` response in the expected content type for that endpoint.

- When selecting an acceptable version, should choose the highest version that
the client supports, with the most expressive/featureful serialization format,
- When selecting an acceptable version, the server should choose the highest version
that the client supports, with the most expressive/featureful serialization format,
taking into account the specificity of the client requests as well as any
quality priority values they have expressed, and it should only use the
``text/html`` content type as a last resort.
Expand Down Expand Up @@ -694,18 +700,6 @@ so if there's some new piece of data that an installer might need, future PEPs c
easily make that available.


Why is the root URL a dictionary instead of a list?
---------------------------------------------------

The most natural direct translation of the root URL being a list of links is to turn
it into a list of objects. However, stepping back, that's not the most natural way
to actually represent this data. This was a result of a HTML limitation that we had to
work around. With a list (either of ``<a>`` tags, or objects) there's nothing stopping
you from listing the same project twice and other unwanted patterns.

A dictionary also allows for an average of constant-time access given the project name.


Why include the filename when the URL has it already?
-----------------------------------------------------

Expand Down