From ddf1f9f3bda8f0edc4536a66e3d368105fde718c Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Wed, 21 May 2025 17:46:24 -0400 Subject: [PATCH 01/12] PEP: Project status markers in the simple index Signed-off-by: William Woodruff --- peps/pep-9999.rst | 371 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 371 insertions(+) create mode 100644 peps/pep-9999.rst diff --git a/peps/pep-9999.rst b/peps/pep-9999.rst new file mode 100644 index 00000000000..69ad87303d7 --- /dev/null +++ b/peps/pep-9999.rst @@ -0,0 +1,371 @@ +PEP: 9999 +Title: Project status markers in the simple index +Author: William Woodruff , + Facundo Tuesca +Sponsor: Donald Stufft +PEP-Delegate: Donald Stufft +Discussions-To: https://discuss.python.org/t/79356 +Status: Draft +Type: Standards Track +Topic: Packaging +Created: 08-Apr-2025 +Post-History: `03-Feb-2025 `__ + +Abstract +======== + +This PEP proposes a standardized set of project status markers, as well +as a mechanism for communicating those markers in the HTML and JSON +simple indices. + +Rationale and Motivation +======================== + +The "status" of a project is an important piece of metadata, made more important +by growth in both the breadth and depth of the Python packaging ecosystem. +Both humans and tools use project statuses (or proxies for status, +such as recent activity) to determine whether the project is maintained or +otherwise suitable for consumption. + +Python packaging has at least three different mechanisms for communicating +the "status" of a project: + +1. Distributions can include *trove classifiers* in their metadata, as + originally specified in :pep:`301`. The list of supported classifiers is + `maintained by the PyPA `_, + and includes the ``Development Status`` hierarchy. For example, a + distribution can include the ``Development Status :: 7 - Inactive`` + classifier to indicate that the distribution's project is inactive. + + Trove classifiers are flexible, but also come with significant limitations: + they're machine-readable and are rendered on indices like PyPI, but + they also require the maintainer to push one or more *new* distributions + each time they wish to update their project's development status. + Furthermore, because distributions are *de facto* immutable in the Python + packaging ecosystem, older distributions can't have their classifiers + updated to reflect the current status of the project. + +2. Indices can mark distributions and releases as "yanked", as originally + specified in :pep:`592`. Yanked distributions are not considered + eligible for dependency resolution. + + When a distribution has been yanked, it is marked with ``data-yanked`` + in the HTML index and with ``yanked: bool | str`` in the JSON index. + Additionally, indices like PyPI will hide yanked distributions by default + and will render them with a notice when the user navigates directly to them. + + Yanking is machine-readable like trove classifiers, but is single-purpose + rather than general-purpose: users can specify a free-form "yank reason," + but the semantics of yanking are fixed. + +3. PyPI itself has *project statuses*, which apply to the entire project + (i.e., all releases and distributions). Project statuses have both + maintainer- and index-admin-controllable states: + + * PyPI administrators can "quarantine" a project. Quarantine behaves like + a strengthened yank: the project remains entirely uninstallable while + quarantined. + + * Project maintainers can "archive" a project. Archiving a project + disables new release and distribution uploads to that project, + but otherwise has no effect on the project's downloadability. + + Project statuses are machine-readable *in principle*, but are not currently + exposed via any of PyPI's APIs. Instead, PyPI renders project statuses on + each project's user-facing (i.e. non-index) HTML. + +In summary: there are multiple ways to communicate the "status" of a project in +Python packaging, but none of these mechanisms are *simultaneously* (1) +machine-readable, (2) general, (3) index-agnostic, and (4) updatable across +the entire project (instead of per-release or per-distribution). + +.. csv-table:: + :header: "Mechanism", "Machine-readable?", "General?", "Index-agnostic?", "Project updatable?" + + "Trove classifiers", "✅", "✅", "✅", "❌" + "Yanking", "✅", "❌", "✅", "✅" + "Project statuses", "✅", "✅", "❌", "✅" + +This PEP proposes adopting PyPI's project statuses as an index-agnostic +mechanism, satisfying all four conditions. + +Specification +============= + +This PEP specifies two aspects: a set of project status markers, +as well as their presentation in the standard HTML and JSON indices. + +Project status markers +---------------------- + +This PEP proposes the following project status markers. + +A project **MUST** have exactly one project status marker at any given time. + +Indices **MAY** implement any subset of the status markers specified in this +PEP, as applicable. + +``active`` +~~~~~~~~~~ + +Description: The project is active. This is the default status for a project. + +Index semantics: none. + +Installer semantics: none. + +``archived`` +~~~~~~~~~~~~ + +Description: The project does not expect to be updated in the future. + +Index semantics: + +* The index hosting the project **MUST NOT** allow uploads of new distributions to + the project. +* The index **MUST** offer existing distributions of the project for download. + +Installer semantics: + +* Installers **MAY** produce warnings about a project's archival. + +``quarantined`` +~~~~~~~~~~~~~~~ + +Description: The project is considered generally unsafe for use, e.g. due to +malware. + +Index semantics: + +* The index hosting the project **MUST NOT** allow uploads of new distributions to + the project. +* The index **MUST NOT** offer any distributions of the project for download. + +Installer semantics: + +* Installers **MAY** produce warnings about a project's quarantine, although + doing so is effectively moot (as the index will not offer any distributions + for installation). + +``deprecated`` +~~~~~~~~~~~~~~ + +Description: The project is considered obsolete, and may have been superseded +by another project. + +Index semantics: + +* The index hosting the project **MUST** allow uploads of new distributions to + the project. +* The index **MUST** offer existing distributions of the project for download. + +Installer semantics: + +* Installers **MAY** produce warnings about a project's deprecation. + +Status markers in the index APIs +-------------------------------- + +This PEP defines version 1.4 of the index APIs. + +HTML index +~~~~~~~~~~ + +The following changes are made to the +:ref:`simple repository API `: + +* The index **SHALL** define the ``pypi:repository-version`` as ``1.4``. +* The index **SHOULD** add an appropriate ``pypi:project-status`` meta tag, with + a ``content`` of the project's status marker. The index **MAY** choose to omit + the ``pypi:project-status`` meta tag if the project is marked as ``active``. + +For example, the following would be a valid HTML index response for +``sampleproject`` after is has been marked as ``quarantined``: + +.. code-block:: html + :emphasize-lines: 5 + + + + + + + Links for sampleproject + + +

Links for sampleproject

+ + + +Observe that, per the ``quarantined`` semantics above, the index response +contains no distribution links for the project. + +JSON index +~~~~~~~~~~ + +The following changes are made to the +:ref:`JSON simple index `: + +* The index **SHALL** define the ``meta.api-version`` as ``1.4``. +* The index **SHOULD** include a ``project-status`` key in the JSON response, + with a value of the project's status marker. The index **MAY** choose to omit + the ``project-status`` key if the project is marked as ``active``. + +For example, the following would be a valid JSON index response for +``sampleproject`` after is has been marked as ``quarantined``: + +.. code-block:: json + :emphasize-lines: 5 + + { + "meta": { + "api-version": "1.4" + }, + "project-status": "quarantined", + "alternate-locations": [], + "files": [], + "name": "sampleproject", + "versions": [ + "1.2.0", + "1.3.0", + "1.3.1", + "2.0.0", + "3.0.0", + "4.0.0" + ] + } + +Observe that, like with the HTML index, the JSON response contains no +distribution links for the ``quarantined`` project. + +Future Considerations +===================== + +This PEP defines only four project status markers: ``active``, ``archived``, +``quarantined``, and ``deprecated``. + +Future PEPs (or PyPA standards processes) may define additional project +status markers, as needed. + +As specified in this PEP, project status markers are "bare," i.e. they +convey no additional user-controlled metadata (such as an explanation +for a project's archival). + +A future PEP may choose to extend the project +status mechanism to include user-controlled metadata, in a manner similar +to the free-form text allowed during release yanking. + +Security Implications +===================== + +This PEP does not identify any positive or negative security implications +associated with adding project status markers. + +How to Teach This +================= + +Educating the Python community about this PEP has two aspects: + +* Ordinary package maintainers will need to be informed of their ability to + set project status markers, e.g. to inform their downstreams that + a project has been archived or deprecated. + + If this PEP is accepted, the authors of this PEP will coordinate with + PyPI on appropriate maintainer-oriented documentation and communication, + including feature announcement blog posts and updates to + `PyPI's user documentation `_. + +* Installer and index maintainers will need to be informed of the new project + status markers, and how to interpret them. + + If this PEP is accepted, the authors of this PEP will perform its + implementation on PyPI, serving as a reference implementation for other + indices. + + This PEP does not *mandate* any changes in installer behavior. However, + if this PEP is accepted, the authors of this PEP will coordinate with + the maintainers of popular installers (e.g. ``pip``) to help each determine + the extent to which they wish to surface project statuses. + +Rejected Ideas +============== + +Using "reserved" keys +--------------------- + +One alternative to this PEP is to avoid standardizing project status +markers directly, but instead leverage existing mechanisms within the standards +to communicate them in a non-standard fashion. + +For example, the `JSON simple index `_ +says the following: + + Keys (at any level) with a leading underscore are reserved as private for + index server use. No future standard will assign a meaning to any such key. + +In effect, this means that the following would be standards-compliant: + +.. code-block:: json + :emphasize-lines: 5 + + { + "meta": { + "api-version": "1.4" + }, + "_project-status": "quarantined", + "alternate-locations": [], + "files": [], + "name": "sampleproject", + "versions": [ + "1.2.0", + "1.3.0", + "1.3.1", + "2.0.0", + "3.0.0", + "4.0.0" + ] + } + +However, this approach has several drawbacks: + +* Standards-aligned tools (such as ``pip``, ``pip-audit``, and ``uv``) + may find it unacceptable to use a "reserved" key, since that key will + have no standard semantics or compatibility properties. +* The "reserved" approach is only suitable for the JSON simple index; + no equivalent mechanism exists for the HTML simple index. + This would disadvantage consumers of the HTML simple index, as well as + mirror implementations that may consume the JSON index but only expose + an HTML index. + +Project markers in PyPI's non-standard JSON API +----------------------------------------------- + +Another standardization-avoidance alternative is to expose project status +markers, but only in PyPI's +`non-standard JSON API `_. PyPI has full +control over the layout of this API, and could include a ``project-status`` +or similar key without needing a PEP or underscore prefix. + +This has similar drawbacks as the "reserved" keys approach above, +and more generally deepens the differences between the standard +and non-standard APIs. + +Multiple project status markers at once +--------------------------------------- + +An earlier version of this PEP considered proposing support for +multiple project markers at once. For example, a project could be marked +as both ``archived`` and ``quarantined``. + +After consideration, this was rejected for complexity reasons: having multiple +project status markers requires the PEP to specify a conflict resolution +mechanism when merging their semantics, as well as as state machine for which +markers are exclusive (for example, ``active`` is conceptually exclusive with +all other markers, while ``archived`` and ``quarantined`` are conceptually +compatible with each other). + +Copyright +========= + +This document is placed in the public domain or under the CC0-1.0-Universal +license, whichever is more permissive. From e238ba3804a41e5e537773a7089ba5d95b127c1f Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Wed, 21 May 2025 18:26:15 -0400 Subject: [PATCH 02/12] Update peps/pep-9999.rst Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- peps/pep-9999.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-9999.rst b/peps/pep-9999.rst index 69ad87303d7..2aa2f43881e 100644 --- a/peps/pep-9999.rst +++ b/peps/pep-9999.rst @@ -1,4 +1,4 @@ -PEP: 9999 +PEP: 792 Title: Project status markers in the simple index Author: William Woodruff , Facundo Tuesca From ff972d7484f04e3c3384ed2a4d24ca5626740300 Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Wed, 21 May 2025 18:26:50 -0400 Subject: [PATCH 03/12] CODEOWNERS: dstufft owns PEP 792 Signed-off-by: William Woodruff --- .github/CODEOWNERS | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 0062df25475..c50b05e42a8 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -670,6 +670,7 @@ peps/pep-0788.rst @ZeroIntensity @vstinner peps/pep-0789.rst @njsmith peps/pep-0790.rst @hugovk peps/pep-0791.rst @vstinner +peps/pep-0792.rst @dstufft # ... peps/pep-0801.rst @warsaw # ... From 3b28def215b29b62b356f865e1ed3a64bf12a76d Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Wed, 21 May 2025 18:27:48 -0400 Subject: [PATCH 04/12] PEP: renumber Signed-off-by: William Woodruff --- peps/{pep-9999.rst => pep-0792.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename peps/{pep-9999.rst => pep-0792.rst} (100%) diff --git a/peps/pep-9999.rst b/peps/pep-0792.rst similarity index 100% rename from peps/pep-9999.rst rename to peps/pep-0792.rst From bae063de038abcbbf5b803f4fbfc5209e0ffd2b5 Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Wed, 21 May 2025 22:22:15 -0400 Subject: [PATCH 05/12] Apply suggestions from code review Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- peps/pep-0792.rst | 53 +++++++++++++++++++++++++---------------------- 1 file changed, 28 insertions(+), 25 deletions(-) diff --git a/peps/pep-0792.rst b/peps/pep-0792.rst index 2aa2f43881e..8096e67f0e1 100644 --- a/peps/pep-0792.rst +++ b/peps/pep-0792.rst @@ -1,15 +1,15 @@ PEP: 792 Title: Project status markers in the simple index Author: William Woodruff , - Facundo Tuesca + Facundo Tuesca , Sponsor: Donald Stufft PEP-Delegate: Donald Stufft -Discussions-To: https://discuss.python.org/t/79356 +Discussions-To: Pending Status: Draft Type: Standards Track Topic: Packaging Created: 08-Apr-2025 -Post-History: `03-Feb-2025 `__ +Post-History: `03-Feb-2025 `__, Abstract ======== @@ -23,9 +23,8 @@ Rationale and Motivation The "status" of a project is an important piece of metadata, made more important by growth in both the breadth and depth of the Python packaging ecosystem. -Both humans and tools use project statuses (or proxies for status, -such as recent activity) to determine whether the project is maintained or -otherwise suitable for consumption. +Project status (or proxies such as recent activity) is useful to know in +determining whether a project is maintained or otherwise suitable for consumption. Python packaging has at least three different mechanisms for communicating the "status" of a project: @@ -55,8 +54,10 @@ the "status" of a project: and will render them with a notice when the user navigates directly to them. Yanking is machine-readable like trove classifiers, but is single-purpose - rather than general-purpose: users can specify a free-form "yank reason," - but the semantics of yanking are fixed. + rather than general-purpose: users can specify a free-text reason for + yanking a given distribution package, but the semantics of yanking are + fixed, and no reliable inference of project status can be made by a machine + based upon that free-text reason. 3. PyPI itself has *project statuses*, which apply to the entire project (i.e., all releases and distributions). Project statuses have both @@ -66,25 +67,27 @@ the "status" of a project: a strengthened yank: the project remains entirely uninstallable while quarantined. - * Project maintainers can "archive" a project. Archiving a project + * Project owners can "archive" a project. Archiving a project disables new release and distribution uploads to that project, - but otherwise has no effect on the project's downloadability. + but otherwise has no effect on the ability to download a project. Project statuses are machine-readable *in principle*, but are not currently exposed via any of PyPI's APIs. Instead, PyPI renders project statuses on - each project's user-facing (i.e. non-index) HTML. - -In summary: there are multiple ways to communicate the "status" of a project in -Python packaging, but none of these mechanisms are *simultaneously* (1) -machine-readable, (2) general, (3) index-agnostic, and (4) updatable across -the entire project (instead of per-release or per-distribution). - -.. csv-table:: - :header: "Mechanism", "Machine-readable?", "General?", "Index-agnostic?", "Project updatable?" - - "Trove classifiers", "✅", "✅", "✅", "❌" - "Yanking", "✅", "❌", "✅", "✅" - "Project statuses", "✅", "✅", "❌", "✅" + each project's user-facing (i.e. non-index) webpage. + +In summary, there are multiple ways to communicate the "status" of a project in +Python packaging. However, none of them satisfy the four characteristics we desire. +There is no current project status indicator that is machine-readable, general, +index-agnostic, and applies to the entire project, instead of per-release or +per-distribution. + +================= ================ ======= ============== ============ +Mechanism Machine-readable General Index-agnostic Project-wide +================= ================ ======= ============== ============ +Trove classifiers ✅ ✅ ✅ ❌ +Yanking ✅ ❌ ✅ ✅ +Project statuses ✅ ✅ ❌ ✅ +================= ================ ======= ============== ============ This PEP proposes adopting PyPI's project statuses as an index-agnostic mechanism, satisfying all four conditions. @@ -183,7 +186,7 @@ For example, the following would be a valid HTML index response for ``sampleproject`` after is has been marked as ``quarantined``: .. code-block:: html - :emphasize-lines: 5 + :emphasize-lines: 5 @@ -215,7 +218,7 @@ For example, the following would be a valid JSON index response for ``sampleproject`` after is has been marked as ``quarantined``: .. code-block:: json - :emphasize-lines: 5 + :emphasize-lines: 5 { "meta": { From b803be9c437689b2a7070875e0d5b640908846bc Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Wed, 21 May 2025 22:33:50 -0400 Subject: [PATCH 06/12] PEP 792: address more feedback Signed-off-by: William Woodruff --- peps/pep-0792.rst | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/peps/pep-0792.rst b/peps/pep-0792.rst index 8096e67f0e1..d6a64a49e10 100644 --- a/peps/pep-0792.rst +++ b/peps/pep-0792.rst @@ -22,14 +22,14 @@ Rationale and Motivation ======================== The "status" of a project is an important piece of metadata, made more important -by growth in both the breadth and depth of the Python packaging ecosystem. +by growth in both the size and complexity of the Python packaging ecosystem. Project status (or proxies such as recent activity) is useful to know in determining whether a project is maintained or otherwise suitable for consumption. Python packaging has at least three different mechanisms for communicating the "status" of a project: -1. Distributions can include *trove classifiers* in their metadata, as +1. Distribution packages can include *trove classifiers* in their metadata, as originally specified in :pep:`301`. The list of supported classifiers is `maintained by the PyPA `_, and includes the ``Development Status`` hierarchy. For example, a @@ -77,17 +77,17 @@ the "status" of a project: In summary, there are multiple ways to communicate the "status" of a project in Python packaging. However, none of them satisfy the four characteristics we desire. -There is no current project status indicator that is machine-readable, general, +There is no current project status indicator that is machine-readable, general, index-agnostic, and applies to the entire project, instead of per-release or per-distribution. -================= ================ ======= ============== ============ -Mechanism Machine-readable General Index-agnostic Project-wide -================= ================ ======= ============== ============ -Trove classifiers ✅ ✅ ✅ ❌ -Yanking ✅ ❌ ✅ ✅ -Project statuses ✅ ✅ ❌ ✅ -================= ================ ======= ============== ============ +===================== ================ ======= ============== ============ +Mechanism Machine-readable General Index-agnostic Project-wide +===================== ================ ======= ============== ============ +Trove classifiers ✅ ✅ ✅ ❌ +Yanking ✅ ❌ ✅ ✅ +PyPI project statuses ✅ ✅ ❌ ✅ +===================== ================ ======= ============== ============ This PEP proposes adopting PyPI's project statuses as an index-agnostic mechanism, satisfying all four conditions. @@ -103,7 +103,8 @@ Project status markers This PEP proposes the following project status markers. -A project **MUST** have exactly one project status marker at any given time. +A project always has exactly one status. If no status is explicitly noted, +then the project is considered to be in the ``active`` state. Indices **MAY** implement any subset of the status markers specified in this PEP, as applicable. @@ -113,7 +114,11 @@ PEP, as applicable. Description: The project is active. This is the default status for a project. -Index semantics: none. +Index semantics: + +* The index hosting the project **MUST** allow uploads of new distributions to + the project. +* The index **MUST** offer existing distributions of the project for download. Installer semantics: none. @@ -158,9 +163,7 @@ by another project. Index semantics: -* The index hosting the project **MUST** allow uploads of new distributions to - the project. -* The index **MUST** offer existing distributions of the project for download. +* This status shares the same semantics as ``active``. Installer semantics: From a253d94b7149186b84ce294127aa7ca598f0710d Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Thu, 22 May 2025 09:46:50 -0400 Subject: [PATCH 07/12] Apply suggestions from code review Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- peps/pep-0792.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/peps/pep-0792.rst b/peps/pep-0792.rst index d6a64a49e10..a21bc856bd0 100644 --- a/peps/pep-0792.rst +++ b/peps/pep-0792.rst @@ -8,7 +8,7 @@ Discussions-To: Pending Status: Draft Type: Standards Track Topic: Packaging -Created: 08-Apr-2025 +Created: 21-May-2025 Post-History: `03-Feb-2025 `__, Abstract @@ -29,7 +29,7 @@ determining whether a project is maintained or otherwise suitable for consumptio Python packaging has at least three different mechanisms for communicating the "status" of a project: -1. Distribution packages can include *trove classifiers* in their metadata, as +1. Distribution packages can include *Trove classifiers* in their metadata, as originally specified in :pep:`301`. The list of supported classifiers is `maintained by the PyPA `_, and includes the ``Development Status`` hierarchy. For example, a @@ -53,7 +53,7 @@ the "status" of a project: Additionally, indices like PyPI will hide yanked distributions by default and will render them with a notice when the user navigates directly to them. - Yanking is machine-readable like trove classifiers, but is single-purpose + Yanking is machine-readable like Trove classifiers, but is single-purpose rather than general-purpose: users can specify a free-text reason for yanking a given distribution package, but the semantics of yanking are fixed, and no reliable inference of project status can be made by a machine @@ -300,7 +300,7 @@ Using "reserved" keys --------------------- One alternative to this PEP is to avoid standardizing project status -markers directly, but instead leverage existing mechanisms within the standards +markers directly, but instead use existing mechanisms within the standards to communicate them in a non-standard fashion. For example, the `JSON simple index `_ From 3965134438aadf67341b163688137d007f58f005 Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Thu, 22 May 2025 10:00:41 -0400 Subject: [PATCH 08/12] qualify "project" with "index-supplied" Signed-off-by: William Woodruff --- peps/pep-0792.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/peps/pep-0792.rst b/peps/pep-0792.rst index a21bc856bd0..186495e120c 100644 --- a/peps/pep-0792.rst +++ b/peps/pep-0792.rst @@ -14,8 +14,8 @@ Post-History: `03-Feb-2025 `__, Abstract ======== -This PEP proposes a standardized set of project status markers, as well -as a mechanism for communicating those markers in the HTML and JSON +This PEP proposes a standardized set of index-supplied project status markers, +as well as a mechanism for communicating those markers in the HTML and JSON simple indices. Rationale and Motivation From 11ddd9ff80d3b63ea0ed077d32ca3d60b2a66a5a Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Thu, 22 May 2025 10:02:05 -0400 Subject: [PATCH 09/12] clarify who can un-quarantine a project Signed-off-by: William Woodruff --- peps/pep-0792.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/peps/pep-0792.rst b/peps/pep-0792.rst index 186495e120c..c8430ee56fb 100644 --- a/peps/pep-0792.rst +++ b/peps/pep-0792.rst @@ -64,8 +64,8 @@ the "status" of a project: maintainer- and index-admin-controllable states: * PyPI administrators can "quarantine" a project. Quarantine behaves like - a strengthened yank: the project remains entirely uninstallable while - quarantined. + a strengthened yank: the entire project remains uninstallable while + quarantined, and only an administrator can un-quarantine it. * Project owners can "archive" a project. Archiving a project disables new release and distribution uploads to that project, From 6f27d07a95477b7506fcce5c125c32cbde126581 Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Thu, 22 May 2025 10:02:47 -0400 Subject: [PATCH 10/12] explain what "general" means Signed-off-by: William Woodruff --- peps/pep-0792.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/peps/pep-0792.rst b/peps/pep-0792.rst index c8430ee56fb..d94baf99d8c 100644 --- a/peps/pep-0792.rst +++ b/peps/pep-0792.rst @@ -76,10 +76,10 @@ the "status" of a project: each project's user-facing (i.e. non-index) webpage. In summary, there are multiple ways to communicate the "status" of a project in -Python packaging. However, none of them satisfy the four characteristics we desire. -There is no current project status indicator that is machine-readable, general, -index-agnostic, and applies to the entire project, instead of per-release or -per-distribution. +Python packaging. However, none of them satisfy the four characteristics we +desire. There is no current project status indicator that is machine-readable, +general (i.e. conveys more than one possible state), index-agnostic, and applies +to the entire project, instead of per-release or per-distribution. ===================== ================ ======= ============== ============ Mechanism Machine-readable General Index-agnostic Project-wide From 1b40e31fbb47a763abcca6a4c57ba1124a4534bc Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Thu, 22 May 2025 10:14:51 -0400 Subject: [PATCH 11/12] add language about unsetting of statuses Signed-off-by: William Woodruff --- peps/pep-0792.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/peps/pep-0792.rst b/peps/pep-0792.rst index d94baf99d8c..94f0d63c953 100644 --- a/peps/pep-0792.rst +++ b/peps/pep-0792.rst @@ -109,6 +109,9 @@ then the project is considered to be in the ``active`` state. Indices **MAY** implement any subset of the status markers specified in this PEP, as applicable. +This PEP does not prescribe *which* principals (i.e. project maintainers, +index administrators, etc.) are allowed to set and unset which statuses. + ``active`` ~~~~~~~~~~ From 40a4245af0e8e81a9fb68bc859234ac5f552bdb8 Mon Sep 17 00:00:00 2001 From: William Woodruff Date: Thu, 22 May 2025 10:19:20 -0400 Subject: [PATCH 12/12] future: notes on future version changes Signed-off-by: William Woodruff --- peps/pep-0792.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/peps/pep-0792.rst b/peps/pep-0792.rst index 94f0d63c953..aa5ec8a3059 100644 --- a/peps/pep-0792.rst +++ b/peps/pep-0792.rst @@ -253,8 +253,11 @@ Future Considerations This PEP defines only four project status markers: ``active``, ``archived``, ``quarantined``, and ``deprecated``. -Future PEPs (or PyPA standards processes) may define additional project -status markers, as needed. +Future PEPs (or PyPA standards processes) may define additional project status +markers, as needed. Any future status markers may require a metadata version +bump, unless a future metadata change is made to allow for "open-ended" status +markers (i.e., where indices and installers do not necessarily share a single +common list of allowed statuses). As specified in this PEP, project status markers are "bare," i.e. they convey no additional user-controlled metadata (such as an explanation