Clarifications to PEP 592 (#1034)

This commit is contained in:
Donald Stufft 2019-05-08 11:00:46 -04:00 committed by GitHub
parent 01b3a01495
commit 543cece82e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 32 additions and 15 deletions

View File

@ -1,7 +1,7 @@
PEP: 592
Title: Adding "Yank" Support to the Simple API
Author: Donald Stufft <donald@stufft.io>
BDFL-Delegate: Donald Stufft <donald@stufft.io>
BDFL-Delegate: Paul Moore <p.f.moore@gmail.com>
Discussions-To: https://discuss.python.org/c/packaging
Status: Draft
Type: Standards Track
@ -45,18 +45,29 @@ underlying issues.
Specification
=============
Links on the simple repository **MAY** have a ``data-yanked`` attribute
which can be either a ``true``, ``false``, or have no value at all. For
the purposes of this PEP, having no value is interpretted as a ``true``
value.
Links in the simple repository **MAY** have a ``data-yanked`` attribute
which may have a no value, or may have an arbitrary string as a value.
The presence of a ``data-yanked`` attribute **SHOULD** be interpreted as
indicating that the file pointed to by this particular link has been
"Yanked", and should not generally be selected by an installer, except
under specific scenarios.
When an installer encounters a link that has a true ``data-yanked``
attribute, they **SHOULD** treat that file link as if it does not
exist *UNLESS* the user is requesting the version of that file using
an exact ``==`` match. In other words, ``foo==1.0`` should install
a yanked 1.0, but ``foo>0``, ``foo``, ``foo==1.*``, etc should not.
The value of the ``data-yanked`` attribute, if present, is an arbitrary
string that represents the reason for why the file has been yanked. Tools
that process the simple repository API **MAY** surface this string to
end users.
In addition, and installer **SHOULD** only use a yanked file as a last
When an installer encounters a link that has a ``data-yanked`` attribute,
they **SHOULD** treat that file link as if it does not exist *UNLESS* the
user is requesting the version of that file using an exact ``==`` or
``===`` match without any modifiers that make it a range (i.e. ``.*``).
Matching this version specifier is otherwise done as per PEP 440 for things
like local versions, zero padding, etc.
In other words, ``foo==1.0`` should install a yanked 1.0 or 1.0.0, but
``foo>0``, ``foo``, ``foo==1.*``, etc should not.
In addition, an installer **SHOULD** only use a yanked file as a last
resort if there are no files available that match the requested
version that are not yanked.
@ -67,11 +78,17 @@ Rejected Ideas
A previous, undocumented, version of the simple repository API had
version specific pages, like ``/simple/<project>/<version>/``. If
we were to add those back, the yanked files could only appear on
those pages and not on the version-less page at all.
those pages and not on the version-less page at all. However this
would drastically reduce the cache-ability of the simple API and
would directly impact our ability to scale it out to handle all of
the incoming traffic.
A previous iteration of this PEP had the ``data-yanked`` attribute
act as a boolean value. However it was decided that allowing a
string both simplified the implementation, and provided additional
generalized functionality to allow projects to provide a mechanism
to indicate *why* they were yanking a release.
However this would drastically reduce the cache-ability of the simple
API and would directly impact our ability to scale it out to handle
all of the incoming traffic.
.. _`Simple Repository API`: