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 underlying idea behind this PEP is to give Python packaging a “status” mechanism that (1) operates at the project level, rather than per-release or per-file, and (2) allows for currently PyPI-only features like quarantine and archival to be exposed for downstream installer/tool consumption in a standard and reusable (by other index implementations) way.
I’m excited to hear what the community thinks about this! I thank you all in advance for your consideration and feedback
I see no reason not to, but I’m curious if you have a use case in mind for it – I’ll be honest and say I almost never look at the “Base HTML API” at all
(One really - really tiny? - downside is that it would make that response bigger, but given how big it already is I don’t think it’s an overriding concern. But others perhaps know better than I do.)
I’m also curious what the use case would be. I suspect that it might not be served very well by including status markers there – at least in the case of PyPI, the underlying data for this page changes so rapidly that we intentionally only update the cache for it every 24 hours, which means this page is almost always out of date and status markers would be as well, and we generally recommend using other APIs instead.
Per @dustin’s point I’m inclined to not add markers to it (at least until there’s another response asking for it), but not mentioning it at all was an oversight on my part! I’ll update the PEP’s index specification part to clarify that
Quarantined is meant to be a potentially temporary state, as it can be “rolled back” to active. Can we mention that in the state description? Currently it could be confused that a project that becomes quarantined is to be considered malware.
Do we want to try adding the free-text user message to statuses in this PEP? It feels especially relevant for archived and deprecated and something that installers will want to forward to the user if they’re implementing warnings.
Security implication about project statuses, adding the classification of a negative status (quarantined) might further drive the idea that “anything on PyPI is safe”, which we don’t want users to believe and for users to continue evaluating releases they choose to use. Descriptions of project statuses that are user-facing should reflect this.
The line “should be considered in the active state”, do we want to clarify the semantics for when an index doesn’t implement statuses, does the active state still apply then (and installers / users should treat projects in that case as “active”)?
Nit to capitalize all SHOULD and MUST (some already are, but not all), SHALL → MUST, etc.
That seems reasonable to me to mention! Thinking generally as well: technically there really aren’t any permanent states with this PEP, since the PEP (intentionally) doesn’t define any state transitions or a state machine.
Given that, perhaps it makes sense for me to add some overarching language that explains that a project’s state is whatever state it happens to be in, and that states are not guaranteed to be static over time (much like yanking)? That would cover quarantine transitively, but perhaps it would also be confusing to state so generally.
I like this idea and have no opposition to it – the reason I left it out initially is because it wasn’t clear where the free-text should live in the index responses, but here’s one idea:
<meta name="pypi:project-status" content="quarantined">
<meta name="pypi:project-status-reason" content="the project is haunted">
and:
{
"project-status": {
"state": "quarantined",
"reason": "the project is haunted"
}
}
Thoughts on that?
(There are probably some additional considerations that come with that as well, e.g. how long reasons can be, support for links, etc. Curious if anybody has thoughts on those!)
Agreed; I think there’s probably a separate UI/UX component to further surfacing these states on PyPI that’s probably distinct from this PEP itself. But I suppose the PEP could also make it clear that project statuses aren’t contrapositive, i.e. a project that isn’t in the “archived” state isn’t inherently active, not quarantined doesn’t mean safe, etc.
Yeah, that was meant to be clarified by this line at the top of the Project status markers section:
A project always has exactly one status. If no status is explicitly noted, then the project is considered to be in the active state.
i.e. the implication is that an index that doesn’t implement this only has the “active” state, and all installers should treat all packages from that index as “active.”
Curious if you think it could use further clarification
Okay, next round of updates are in: I’ve added free-form reasons to the PEP’s proposed changes, and have replaced SHALL with MUST where present to use the more canonical RFC 2119 labels.
