diff --git a/pep-0592.rst b/pep-0592.rst new file mode 100644 index 000000000..4fcdd992c --- /dev/null +++ b/pep-0592.rst @@ -0,0 +1,93 @@ +PEP: 592 +Title: Adding "Yank" Support to the Simple API +Author: Donald Stufft +BDFL-Delegate: Donald Stufft +Discussions-To: https://discuss.python.org/c/packaging +Status: Draft +Type: Standards Track +Content-Type: text/x-rst +Created: 07-May-2019 +Post-History: + + +Abstract +======== + +This PEP proposes adding the ability to mark a particular file download +on a simple repository as "yanked". Yanking a file allows authors to +effectively delete a file, without breaking things for people who have +pinned to exactly a specific version. + +It also changes to the canonical source for the simple repository API to +the `Simple Repository API`_ reference document. + + +Motivation +========== + +Whenever a project detects that a particular release on PyPI might be +broken, they often times will want to prevent further users from +inadvertantly using that version. However, the obvious solution of +deleting the existing file from a repository will break users who have +followed best practices and pinned to a specific version of the project. + +This leaves projects in a catch-22 situation where new projects may be +pulling down this known broken version, but if they do anything to +prevent that they'll break projects that are already using it. + +By allowing the ability to "yank" a file, but still make it available +for users who are explicitly asking for it, this allows projects to +mitigate the worst of the breakage while still keeping things working +for projects who have otherwise worked around or didn't hit the +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. + +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. + +In addition, and 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. + + +Rejected Ideas +============== + +A previous, undocumented, version of the simple repository API had +version specific pages, like ``/simple///``. 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. + +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`: + https://packaging.python.org/specifications/simple-repository-api/ + + +Copyright +========= + +This document has been placed in the public domain. + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + coding: utf-8 + End: