PEP 763: Limiting deletions on PyPI

.github/CODEOWNERS

@@ -638,6 +638,8 @@ peps/pep-0757.rst  @vstinner
 peps/pep-0758.rst  @pablogsal @brettcannon
 peps/pep-0759.rst  @warsaw
 # ...
+peps/pep-0763.rst  @dstufft
+# ...
 peps/pep-0789.rst  @njsmith
 # ...
 peps/pep-0801.rst  @warsaw

peps/pep-0763.rst

@@ -0,0 +1,275 @@
+PEP: 763
+Title: Limiting deletions on PyPI
+Author: William Woodruff <[email protected]>,
+        Alexis Challande <[email protected]>
+Sponsor: Donald Stufft <[email protected]>
+PEP-Delegate: Donald Stufft <[email protected]>
+Discussions-To: TODO
+Status: Draft
+Type: Standards Track
+Topic: Packaging
+Created: 07-Oct-2024
+Post-History: `09-Jul-2022 <https://discuss.python.org/t/stop-allowing-deleting-things-from-pypi/17227>`__,
+              `01-Oct-2024 <https://discuss.python.org/t/pre-pep-limiting-deletions-on-pypi/66351>`__
+
+Abstract
+========
+
+This PEP proposes limiting user-level deletions of projects (including release
+and file-level deletions) on PyPI, in favor of the "yanking" mechanism
+adopted by PyPI with :pep:`592`.
+
+In particular, the PEP proposes a time-based deletion criterion via
+which projects (and their releases and files) are protected from *deletion*
+after an initial grace period of 72 hours following their creation.
+An exception to this criteria is made for versions and files that are
+marked with :ref:`pre-release specifiers <packaging:version-specifiers>`,
+which will remain deletable at all times.
+
+This PEP does not propose changes to administrator-initiated deletions, e.g.
+for moderation or security purposes.
+
+Rationale and Motivation
+========================
+
+As observed in :pep:`592`, user-level deletion of projects on PyPI
+enables a `Catch-22 <https://www.merriam-webster.com/dictionary/catch-22>`_
+of dependency breakage:
+
+    Whenever a project detects that a particular release on PyPI might be
+    broken, they oftentimes will want to prevent further users from
+    inadvertently 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.
+
+On a technical level, the problem of deletion is mitigated by
+"yanking," also specified in :pep:`592`. However, deletions continue to be
+allowed on PyPI, and have caused multiple notable disruptions to the Python
+ecosystem over the interceding years:
+
+* July 2022: `atomicwrites <https://pypi.org/project/atomicwrites/>`_
+  was `deleted by its maintainer <https://github.com/untitaker/python-atomicwrites/issues/61>`_
+  in an attempt to remove the project's "critical" designation, without the
+  maintainer realizing that project deletion would also delete all previously
+  uploaded versions.
+
+  The project was subsequently restored with the maintainer's consent,
+  but at the cost of manual administrator action and extensive downstream
+  breakage to projects like `pytest <https://github.com/pytest-dev/pytest/issues/10114>`_.
+  As of October 2024, atomicwrites is archived but still has
+  around `4.5 million monthly downloads from PyPI <https://pypistats.org/packages/atomicwrites>`_.
+
+* April 2023: `codecov <https://pypi.org/project/codecov/>`_ was deleted by
+  its maintainers after a long deprecation period. This caused extensive
+  breakage for many of Codecov's CI/CD users, who were unaware of the
+  deprecation period due to limited observability of deprecation warnings
+  within CI/CD logs.
+
+  The project was
+  `subsequently re-created <https://about.codecov.io/blog/message-regarding-the-pypi-package/>`_
+  by its maintainers, with a new release published to compensate for the deleted releases
+  (which were not restored), meaning that any pinned installations remained
+  broken. As of October 2024, this single release remains the only release on
+  PyPI and has around
+  `1.5 million monthly downloads <https://pypistats.org/packages/codecov>`_.
+
+* June 2023: `python-sonarqube-api <https://pypi.org/project/python-sonarqube-api/>`_
+  deleted all released versions prior to 2.0.2, which was both a breaking
+  change version *and* was accompanied by a paid "Professional Edition".
+
+  The project's maintainer subsequently
+  `deleted conversations <https://discuss.python.org/t/stop-allowing-deleting-things-from-pypi/17227/114>`_
+  and force-pushed over the tag history for ``python-sonarqube-api``'s source repository,
+  impeding efforts by the community to compare changes between versions
+  and obtain previous, permissively-licensed versions.
+
+* June 2024: `PySimpleGUI <https://pypi.org/project/PySimpleGUI/>`_ changed
+  licenses from LGPL to a commercial license, and deleted
+  `nearly all previous versions <https://discuss.python.org/t/48790/27>`_.
+  This resulted in widespread disruption for users, who (prior
+  to the relicensing) were downloading PySimpleGui
+  approximately 25,000 times a day. This deletion also impeded efforts
+  by the community to provide "continuity" projects, as the
+  permissively-licensed artifacts were no longer available for reference
+  and re-uploading.
+
+In addition to their disruptive effect on downstreams, deletions
+also have deleterious effects on PyPI's sustainability as well as the overall
+security of the ecosystem:
+
+* Deletions raise the baseline support load for PyPI's administrators and
+  moderators, as users mistakenly file support requests believing that PyPI
+  is broken, or that the administrators themselves have removed the
+  project.
+
+* Deletions impair incident response and external analysis, making it
+  difficult to distinguish "good faith" maintainer behavior from malicious
+  post-exploitation track-covering.
+
+The size and interdependency of the Python ecosystem is continuing to grow,
+meaning that future deletions of projects can be reasonably assumed to
+be *just as if not more* disruptive than the deletions sampled above.
+
+Given the above, this PEP concludes that the availability of "hard" deletions
+versus "soft" deletions (i.e. yanking) now presents more of a risk and detriment
+to the Python ecosystem than a benefit.
+
+Specification
+=============
+
+This PEP identifies 3 different types of deletable objects:
+
+1. **Files**, which are individual project distributions (such as source
+   distributions or wheels).
+
+   Example: ``requests-2.32.3-py3-none-any.whl``.
+
+2. **Versions**, which contain one or more files that share the same version.
+
+   Example: `requests v2.32.3 <https://pypi.org/project/requests/2.32.3/>`_.
+
+3. **Projects**, which contain one or more versions.
+
+   Example: `requests <https://pypi.org/project/requests>`_.
+
+This PEP proposes the following *deletion eligibility rules*:
+
+* A **file** is considered deletable if and only if it was uploaded to
+  PyPI less than 72 hours from the current time, **or** if it
+  has a :ref:`pre-release specifier <packaging:version-specifiers>`.
+* A **release** is considered deletable if and only if all of its
+  constituent files are deletable.
+* A **project** is considered deletable if and only if all of its
+  constituent releases are deletable.
+
+These rules are intentionally "telescoping": they allow new projects to be
+deleted entirely, and allow old projects to delete new files or releases,
+but do not allow old projects to delete old files or releases.
+
+This is intended to strike a balance between competing interests: brand new
+projects are unlikely to have significant community uptake and thus pose a
+minimal disruptive risk, while established projects (of any size)
+are more likely to have a "tail" of adopted versions. Their downstream users
+are not necessarily equipped to address the sudden deletion
+of a version, file, or the whole project.
+
+Implementation
+==============
+
+This PEP's implementation primarily concerns aspects of PyPI that are not
+standardized or subject to standardization, such as the web interface and
+signed-in user operations. As a result, this section describes its
+implementation in behavioral terms.
+
+Changes
+-------
+
+* Per the eligibility rules above, PyPI will reject web interface requests
+  (using an appropriate HTTP response code of its choosing) for
+  file, release, or project deletion if the respective object is not
+  eligible for deletion.
+* PyPI will amend its web interface to indicate a file/release/project's
+  deletion ineligibility, e.g. by styling the relevant UI elements as "inactive"
+  and making relevant bottoms/forms unclickable.
+
+Security Implications
+=====================
+
+This PEP does not identify any positive or negative security implications
+associated with proposed approach.
+
+How To Teach This
+=================
+
+This PEP suggests at least two pieces of public-facing material to help
+the larger Python packaging community (and its downstream consumers)
+understand its changes:
+
+* An announcement post on the `PyPI blog <https://blog.pypi.org>`_ explaining
+  the nature of the PEP and its behavioral implications for PyPI.
+* Updates to the `PyPI user documentation <https://docs.pypi.org/>`_ explaining
+  the difference between deletion and yanking and the limited conditions under
+  which the former can still be initiated by package owners.
+
+Rejected Ideas
+==============
+
+Conditioning deletion on dependency relationships
+-------------------------------------------------
+
+An alternative to time-based deletion windows is deletion eligibility based on
+downstream dependents. For example, a release could be considered deletable
+if and only if it has fewer than ``N`` downstream dependents on PyPI,
+where ``N`` could be as low as 1.
+
+This idea is appealing since it directly links deletion eligibility to
+disruptiveness. `NPM <https://www.npmjs.com/>`_ uses it and
+conditions project removal on the absence of any downstream dependencies
+known to the index.
+
+Despite its appeal, this PEP identifies several disadvantages and technical
+limitations that make dependency-conditioned deletion not appropriate
+for PyPI:
+
+1. *PyPI is not aware of dependency relationships.* In Python packaging,
+   both project builds *and* metadata generation are frequently dynamic
+   operations, involving arbitrary project-specified code. This is typified
+   by source distributions containing ``setup.py`` scripts, where the execution
+   of ``setup.py`` is responsible for computing the set of dependencies
+   encoded in the project's metadata.
+
+   This is in marked contrast to ecosystems like NPM and Rust's
+   `crates <https://crates.io/>`_, where project *builds* can be dynamic but
+   the project's metadata itself is static.
+
+   As a result of this,
+   `PyPI doesn't know your project's dependencies <https://dustingram.com/articles/2018/03/05/why-pypi-doesnt-know-dependencies/>`_,
+   and is architecturally incapable of knowing them without either running
+   arbitrary code (a significant security risk) or performing a long-tail
+   deprecation of ``setup.py``-based builds in favor of :pep:`517` and
+   :pep:`621`-style static metadata.
+
+2. *Results in an unintuitive permissions model.* Dependency-conditioned
+   deletion results in a "reversed" power relationship, where anybody
+   who introduces a dependency on a project can prevent that project from
+   being deleted.
+
+   This is reasonable on face value, but can be abused to produce unexpected
+   and undesirable (in the context of enabling some deletions) outcomes.
+   A notable example of this is NPM's
+   `everything package <https://www.npmjs.com/package/everything>`_, which
+   depends on every public package on NPM (as of 30-Dec-2023) and thereby
+   prevents their deletion.
+
+
+Conditioning deletion on download count
+---------------------------------------
+
+Another alternative to time-based deletion windows is to delete based on the
+number of downloads. For example, a release could be considered deletable if
+and only if it has fewer than ``N`` downloads during the last period.
+
+While presenting advantages by tying a project deletion possibility to its
+usage, this PEP identifies several limitations to this approach:
+
+1. *Ecosystem diversity.* The Python ecosystem includes projects with widely
+varying usage patterns. A fixed download threshold would not adequately account
+for niche but critical projects with naturally low download counts.
+
+2. *Time sensitivity.* Download counts do not necessarily reflect a project's
+current status or importance. A previously popular project might have low
+recent downloads but still be crucial for maintaining older systems.
+
+3. *Technical complexity.* Accessing the download count of a project within
+PyPI is not straightforward, and there is limited possibility to gather a
+project download statistics from mirrors or other distributions systems.
+
+Copyright
+=========
+
+This document is placed in the public domain or under the CC0-1.0-Universal
+license, whichever is more permissive.