111 lines
3.9 KiB
ReStructuredText
111 lines
3.9 KiB
ReStructuredText
PEP: 592
|
|
Title: Adding "Yank" Support to the Simple API
|
|
Author: 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
|
|
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/<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.
|
|
|
|
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:
|