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.
The “status” of a project is an important piece of metadata, made more important 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:
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.
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-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.
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) 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 (i.e. conveys more than one possible state), index-agnostic, and applies to the entire project, instead of per-release or per-distribution.
| Trove classifiers | ✅ | ✅ | ✅ | ❌ |
| Yanking | ✅ | ❌ | ✅ | ✅ |
| PyPI project statuses | ✅ | ✅ | ❌ | ✅ |
This PEP proposes adopting PyPI’s project statuses as an index-agnostic mechanism, satisfying all four conditions.
This PEP specifies two aspects: a set of project status markers, as well as their presentation in the standard HTML and JSON indices.
This PEP proposes the following project status markers.
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 to their needs.
This PEP does not prescribe which principals (i.e. project maintainers, index administrators, etc.) are allowed to set and unset which statuses.
Description: The project is active. This is the default status for a project.
Index semantics:
Installer semantics: none.
Description: The project does not expect to be updated in the future.
Index semantics:
Installer semantics:
Description: The project is considered generally unsafe for use, e.g. due to malware.
Index semantics:
Installer semantics:
Description: The project is considered obsolete, and may have been superseded by another project.
Index semantics:
Installer semantics:
This PEP defines version 1.4 of the index APIs.
All changes to the HTML and JSON simple indices below occur at the per-project level, i.e. within each project’s index response, rather than the root index response. No root index response changes are proposed by this PEP.
The following changes are made to the simple repository API:
For example, the following would be a valid HTML index response for sampleproject after is has been marked as quarantined:
Observe that, per the quarantined semantics above, the index response contains no distribution links for the project.
The following changes are made to the JSON simple index:
For example, the following would be a valid JSON index response for sampleproject after is has been marked as quarantined:
Observe that, like with the HTML index, the JSON response contains no distribution links for the quarantined project.
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. 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 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.
This PEP does not identify any positive or negative security implications associated with adding project status markers.
Educating the Python community about this PEP has two aspects:
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.
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.
One alternative to this PEP is to avoid standardizing project status markers directly, but instead use existing mechanisms within the standards to communicate them in a non-standard fashion.
For example, the JSON simple index says the following:
In effect, this means that the following would be standards-compliant:
However, this approach has several drawbacks:
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.
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).
This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.
Source: https://github.com/python/peps/blob/main/peps/pep-0792.rst
Last modified: 2025-08-11 18:52:20 UTC