Clarifications to PEP 592 (#1034)

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
+Links in the simple repository **MAY** have a ``data-yanked`` attribute
-which can be either a ``true``, ``false``, or have no value at all. For
+which may have a no value, or may have an arbitrary string as a value.
-the purposes of this PEP, having no value is interpretted as a ``true``
+The presence of a ``data-yanked`` attribute **SHOULD** be interpreted as
-value.
+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``
+The value of the ``data-yanked`` attribute, if present, is an arbitrary
-attribute, they **SHOULD** treat that file link as if it does not
+string that represents the reason for why the file has been yanked. Tools
-exist *UNLESS* the user is requesting the version of that file using
+that process the simple repository API **MAY** surface this string to
-an exact ``==`` match. In other words, ``foo==1.0`` should install
+end users.
-a yanked 1.0, but ``foo>0``, ``foo``, ``foo==1.*``, etc should not.
 
-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`: