94 lines
3.0 KiB
ReStructuredText
94 lines
3.0 KiB
ReStructuredText
PEP: 592
|
|
Title: Adding "Yank" Support to the Simple API
|
|
Author: Donald Stufft <donald@stufft.io>
|
|
BDFL-Delegate: Donald Stufft <donald@stufft.io>
|
|
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/<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.
|
|
|
|
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:
|