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: