Clarifications to PEP 592 (#1034)
This commit is contained in:
parent
01b3a01495
commit
543cece82e
47
pep-0592.rst
47
pep-0592.rst
|
@ -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`:
|
||||
|
|
Loading…
Reference in New Issue