This PEP proposes adding the ability to mark a particular file downloadon a simple repository as “yanked”. Yanking a file allows authors toeffectively delete a file, without breaking things for people who havepinned to exactly a specific version.
It also changes to the canonical source for the simple repository API totheSimple Repository API reference document.
Whenever a project detects that a particular release on PyPI might bebroken, they oftentimes will want to prevent further users frominadvertently using that version. However, the obvious solution ofdeleting the existing file from a repository will break users who havefollowed best practices and pinned to a specific version of the project.
This leaves projects in a catch-22 situation where new projects may bepulling down this known broken version, but if they do anything toprevent that they’ll break projects that are already using it.
By allowing the ability to “yank” a file, but still make it availablefor users who are explicitly asking for it, this allows projects tomitigate the worst of the breakage while still keeping things workingfor projects who have otherwise worked around or didn’t hit theunderlying issues.
One of the main scenarios where this may happen, is when droppingsupport for a particular version of Python. Thepython-requiresmetadata allows for dropping support for a version of Python ina way that is not disruptive to users who are still using thatPython. However, a common mistake is to either omit or forget toupdate that bit of metadata. When that mistake has been made, aproject really only has three options:
With this PEP, projects can choose the first option, but with amechanism that is less likely to break the world for people whoarecurrently successfully using said project.
Links in the simple repositoryMAY have adata-yanked attributewhich may have no value, or may have an arbitrary string as a value. Thepresence of adata-yanked attributeSHOULD be interpreted asindicating that the file pointed to by this particular link has been“Yanked”, and should not generally be selected by an installer, exceptunder specific scenarios.
The value of thedata-yanked attribute, if present, is an arbitrarystring that represents the reason for why the file has been yanked. Toolsthat process the simple repository APIMAY surface this string toend users.
The yanked attribute is not immutable once set, and may be rescinded inthe future (and once rescinded, may be reset as well). Thus API usersMUST be able to cope with a yanked file being “unyanked” (and evenyanked again).
The desirable experience for users is that once a file is yanked, whena human being is currently trying to directly install a yanked file, thatit fails as if that file had been deleted. However, when a human did thata while ago, and now a computer is just continuing to mechanically followthe original order to install the now yanked file, then it acts as if ithad not been yanked.
An installerMUST ignore yanked releases, if the selection constraintscan be satisfied with a non-yanked version, andMAY refuse to use ayanked release even if it means that the request cannot be satisfied at all.An implementationSHOULD choose a policy that follows the spirit of theintention above, and that prevents “new” dependencies on yankedreleases/files.
What this means is left up to the specific installer, to decide how to bestfit into the overall usage of their installer. However, there are twosuggested approaches to take:
== (without any modifiers that make it a range, such as.*) or===. Matching this version specifier should otherwisebe done as perPEP 440 for things like local versions, zero padding,etc.Pipfile.lock orpoetry.lock)specifies to be installed. In this case, a yanked fileSHOULD notbe used when creating or updating a lock file from some input file orcommand.Regardless of the specific strategy that an installer chooses for decidingwhen to install yanked files, an installerSHOULD emit a warning whenit does decide to install a yanked file. That warningMAY utilize thevalue of thedata-yanked attribute (if it has a value) to provide morespecific feedback to the user about why that file had been yanked.
Mirrors can generally treat yanked files one of two ways:
data-yanked attribute as well.MirrorsMUST NOT mirror a yanked file without also mirroring thedata-yanked attribute for it.
A previous, undocumented, version of the simple repository API hadversion specific pages, like/simple/<project>/<version>/. Ifwe were to add those back, the yanked files could only appear onthose pages and not on the version-less page at all. However thiswould drastically reduce the cache-ability of the simple API andwould directly impact our ability to scale it out to handle all ofthe incoming traffic.
A previous iteration of this PEP had thedata-yanked attributeact as a boolean value. However it was decided that allowing astring both simplified the implementation, and provided additionalgeneralized functionality to allow projects to provide a mechanismto indicatewhy they were yanking a release.
Another suggestion was to reserve some syntax in the arbitrary stringto allow us to evolve the standard in the future if we ever need to.However, given we can add additional attributes in the future, thisidea has been rejected, favoring instead to use additional attributesif the need ever arose.
While this PEP implements yanking at the file level, that is largelydue to the shape the simple repository API takes, not a specificdecision made by this PEP.
In Warehouse, the user experience will be implemented in terms ofyanking or unyanking an entire release, rather than as an operation onindividual files, which will then be exposed via the API as individualfiles being yanked.
Other repository implementations may choose to expose this capabilityin a different way, or not expose it at all.
Whenever a release has been yanked, an entry will be recorded in thejournal using one of the following string patterns:
yankreleaseunyankreleaseIn both cases, the standard journal structure will indicate which releaseof which project has been yanked or unyanked.
This document has been placed in the public domain.
Source:https://github.com/python/peps/blob/main/peps/pep-0592.rst
Last modified:2025-02-01 08:55:40 GMT