Important
This PEP is a historical document. The up-to-date, canonical spec,Project Status Markers, is maintained on thePyPA specs page.
×
See thePyPA specification update process for how to propose changes.
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 JSONsimple indices.
The “status” of a project is an important piece of metadata, made more importantby growth in both the size and complexity of the Python packaging ecosystem.Project status (or proxies such as recent activity) is useful to know indetermining whether a project is maintained or otherwise suitable for consumption.
Python packaging has at least three different mechanisms for communicatingthe “status” of a project:
DevelopmentStatus hierarchy. For example, adistribution can include theDevelopmentStatus::7-Inactiveclassifier 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, butthey also require the maintainer to push one or morenew distributionseach time they wish to update their project’s development status.Furthermore, because distributions arede facto immutable in the Pythonpackaging ecosystem, older distributions can’t have their classifiersupdated to reflect the current status of the project.
When a distribution has been yanked, it is marked withdata-yankedin the HTML index and withyanked:bool|str in the JSON index.Additionally, indices like PyPI will hide yanked distributions by defaultand will render them with a notice when the user navigates directly to them.
Yanking is machine-readable like Trove classifiers, but is single-purposerather than general-purpose: users can specify a free-text reason foryanking a given distribution package, but the semantics of yanking arefixed, and no reliable inference of project status can be made by a machinebased upon that free-text reason.
Project statuses are machine-readablein principle, but are not currentlyexposed via any of PyPI’s APIs. Instead, PyPI renders project statuses oneach project’s user-facing (i.e. non-index) webpage.
In summary, there are multiple ways to communicate the “status” of a project inPython packaging. However, none of them satisfy the four characteristics wedesire. There is no current project status indicator that is machine-readable,general (i.e. conveys more than one possible state), index-agnostic, and appliesto the entire project, instead of per-release or per-distribution.
| 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-agnosticmechanism, 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 theactive state.
IndicesMAY implement any subset of the status markers specified in thisPEP, as applicable to their needs.
This PEP does not prescribewhich principals (i.e. project maintainers,index administrators, etc.) are allowed to set and unset which statuses.
activeDescription: The project is active. This is the default status for a project.
Index semantics:
Installer semantics: none.
archivedDescription: The project does not expect to be updated in the future.
Index semantics:
Installer semantics:
quarantinedDescription: The project is considered generally unsafe for use, e.g. due tomalware.
Index semantics:
Installer semantics:
deprecatedDescription: The project is considered obsolete, and may have been supersededby another project.
Index semantics:
active.Installer semantics:
This PEP defines version 1.4 of the index APIs.
All changes to the HTML and JSON simple indices below occur at theper-project level, i.e. within each project’s index response, rather thanthe root index response. No root index response changes are proposed by thisPEP.
The following changes are made to thesimple repository API:
pypi:repository-version as1.4.pypi:project-status meta tag, withacontent of the project’s status marker. The indexMAY choose to omitthepypi:project-status meta tag if the project is marked asactive.pypi:project-status-reason meta tag,with acontent of free-form text contextualizing the project’s status.The indexMAY choose to omit thepypi:project-status-reason meta tagif the project is marked asactive or if no reason is provided.For example, the following would be a valid HTML index response forsampleproject after is has been marked asquarantined:
<!DOCTYPE html><html><head><metaname="pypi:repository-version"content="1.4"><metaname="pypi:project-status"content="quarantined"><metaname="pypi:project-status-reason"content="the project is haunted"><title>Links for sampleproject</title></head><body><h1>Links for sampleproject</h1></body></html>
Observe that, per thequarantined semantics above, the index responsecontains no distribution links for the project.
The following changes are made to theJSON simple index:
meta.api-version as1.4.project-status.state key in the JSON response,with a value of the project’s status marker. The indexMAY choose to omittheproject-status.state key if the project is marked asactive.project-status.reason key in the JSON response,with a value of free-form text contextualizing the project’s status.The indexMAY choose to omit theproject-status.reason keyif the project is marked asactive or if no reason is provided.For example, the following would be a valid JSON index response forsampleproject after is has been marked asquarantined:
{"meta":{"api-version":"1.4"},"project-status":{"status":"quarantined","reason":"the project is haunted"},"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 nodistribution links for thequarantined project.
This PEP defines only four project status markers:active,archived,quarantined, anddeprecated.
Future PEPs (or PyPA standards processes) may define additional project statusmarkers, as needed. Any future status markers may require a metadata versionbump, unless a future metadata change is made to allow for “open-ended” statusmarkers (i.e., where indices and installers do not necessarily share a singlecommon list of allowed statuses).
As specified in this PEP, project status markers are “bare,” i.e. theyconvey no additional user-controlled metadata (such as an explanationfor a project’s archival).
A future PEP may choose to extend the projectstatus mechanism to include user-controlled metadata, in a manner similarto the free-form text allowed during release yanking.
This PEP does not identify any positive or negative security implicationsassociated 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 withPyPI on appropriate maintainer-oriented documentation and communication,including feature announcement blog posts and updates toPyPI’s user documentation.
If this PEP is accepted, the authors of this PEP will perform itsimplementation on PyPI, serving as a reference implementation for otherindices.
This PEP does notmandate any changes in installer behavior. However,if this PEP is accepted, the authors of this PEP will coordinate withthe maintainers of popular installers (e.g.pip) to help each determinethe extent to which they wish to surface project statuses.
One alternative to this PEP is to avoid standardizing project statusmarkers directly, but instead use existing mechanisms within the standardsto communicate them in a non-standard fashion.
For example, theJSON simple indexsays the following:
Keys (at any level) with a leading underscore are reserved as private forindex server use. No future standard will assign a meaning to any such key.
In effect, this means that the following would be standards-compliant:
{"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:
pip,pip-audit, anduv)may find it unacceptable to use a “reserved” key, since that key willhave no standard semantics or compatibility properties.Another standardization-avoidance alternative is to expose project statusmarkers, but only in PyPI’snon-standard JSON API. PyPI has fullcontrol over the layout of this API, and could include aproject-statusor 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 standardand non-standard APIs.
An earlier version of this PEP considered proposing support formultiple project markers at once. For example, a project could be markedas botharchived andquarantined.
After consideration, this was rejected for complexity reasons: having multipleproject status markers requires the PEP to specify a conflict resolutionmechanism when merging their semantics, as well as as state machine for whichmarkers are exclusive (for example,active is conceptually exclusive withall other markers, whilearchived andquarantined are conceptuallycompatible with each other).
This document is placed in the public domain or under the CC0-1.0-Universallicense, whichever is more permissive.
Source:https://github.com/python/peps/blob/main/peps/pep-0792.rst
Last modified:2025-08-11 18:52:20 GMT