PEP: 592 Title: Adding "Yank" Support to the Simple API Author: Donald Stufft BDFL-Delegate: Paul Moore 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 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. 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. 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. 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. 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. .. _`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: