PEP 792: Project status markers in the simple index

[woodruffw]

Pre-PEP thread: https://discuss.python.org/t/pre-pep-discussion-project-status-markers-in-the-index-apis/79356

Once allocated a number, I'll make the official PEP thread and update here!

Basic requirements (all PEP Types)

• Read and followed PEP 1 & PEP 12
• File created from the latest PEP template
• PEP has next available number, & set in filename (pep-NNNN.rst), PR title (PEP 123: <Title of PEP>) and PEP header
• Title clearly, accurately and concisely describes the content in 79 characters or less
• Core dev/PEP editor listed as Author or Sponsor, and formally confirmed their approval
• Author, Status (Draft), Type and Created headers filled out correctly
• PEP-Delegate, Topic, Requires and Replaces headers completed if appropriate
• Required sections included
  • Abstract (first section)
  • Copyright (last section; exact wording from template required)
• Code is well-formatted (PEP 7/PEP 8) and is in code blocks, with the right lexer names if non-Python
• PEP builds with no warnings, pre-commit checks pass and content displays as intended in the rendered HTML
• Authors/sponsor added to .github/CODEOWNERS for the PEP

Standards Track requirements

• PEP topic discussed in a suitable venue with general agreement that a PEP is appropriate
• Suggested sections included (unless not applicable)
  • Motivation
  • Rationale
  • Specification
  • Backwards Compatibility
  • Security Implications
  • How to Teach This
  • Reference Implementation
  • Rejected Ideas
  • Open Issues
• Python-Version set to valid (pre-beta) future Python version, if relevant
• Any project stated in the PEP as supporting/endorsing/benefiting from the PEP formally confirmed such
• Right before or after initial merging, PEP discussion thread created and linked to in Discussions-To and Post-History

---

📚 Documentation preview 📚: https://pep-previews--4432.org.readthedocs.build/pep-0792/

[AA-Turner]

PEP 792 is yours. Please wait until this PR is merged & the proper link is online until creating the new Discourse topic.

A

[AA-Turner]

Can we disambiguate in the abstract to "distribution project" or the correct term in the context of package indices? I would tend to read "project status" here as relating to the source project, i.e. pyproject.toml.

[woodruffw]

This could be my misunderstanding, but I thought "project" was the disambiguating term: the PyPUG glossary defines both "distribution package" and "project," but the former appears to refer to a single instance (i.e. file) while the latter refers to the thing that gets packaged into distribution(s) and appears on PyPI.

Refs:

• https://packaging.python.org/en/latest/glossary/#term-Project
• https://packaging.python.org/en/latest/glossary/#term-Distribution-Package

(Apologies if I'm getting this wrong, though.)

[AA-Turner]

My view is that a "project" is nominally tied to a source tree / pyproject.toml (etc), and so when discussing some form of project status indicator, my expectation would be for it to relate to the project as a collection of sources. Note from the glossary "that is intended to be packaged into a Distribution".

The ideal here would be a term that captures 'project as a collection of distribution packages, as represented on a package index'. I recall some discussion with @pfmoore on the distinction between various types of 'projects' (in the context of PyPI pages & displayed licences), I'm not sure if any clarity was found there.

[woodruffw]

Gotcha, I see what you mean! Perhaps "index project" or "inside-side project" then, to clarify that this is a state within the index itself, rather than the project's distributions/source tree/etc.?

[woodruffw]

I've gone with "index-supplied" as a stopgap, but happy to change further.

[AA-Turner]

I can't find anywhere in Specification defining state transitions between status markers. E.g. an explicit note that one may un-deprecate a project, etc.

It may also be good to note the expected interface for markers (e.g. project owners or admins can change at any time per-project), though this probably is a little overkill.

[woodruffw]

I can't find anywhere in Specification defining state transitions between status markers. E.g. an explicit note that one may un-deprecate a project, etc.

One of the follow-on discussions I had with the PyPI folks is that this PEP should probably avoid defining state transitions directly, since that begins to fall into permissions/index-specific behavior. But as a midway point I could note which statuses are conceptually "owner-level" versus "admin-level" (e.g. "archived" vs. "quarantined").

It may also be good to note the expected interface for markers (e.g. project owners or admins can change at any time per-project), though this probably is a little overkill.

Yeah, I think this would push too far into index policy 😅 -- I can see a reasonable scenario in which a non-PyPI index might want admins to be able to archive or deprecate projects, while that's not something that PyPI itself would likely do.

[AA-Turner]

My intent here wasn't defining the actor, but just the state -- currently, it is unclear if an archived project can be un-archived, or a deprecated project un-deprecated, etc. I think a line saying that there are no restrictions in the PEP on changing status would help. You could maybe add a further line to note that indices may have further policies on the 'quarrantine' status as a special case?

[woodruffw]

Sounds good, will do!

[woodruffw]

I'm going to add some language that'll hopefully clarify that states can be set and un-set, but that the PEP leaves it up to the index to determine which "principals" can do what (i.e. whether maintainers or admins can deprecate, archive, etc.)

[AA-Turner]

Am I right in understanding that further status markers would require a change to the metadata version?

[woodruffw]

I think so, yeah (I don't feel confident asserting that as a manner of policy, but that seems to be the norm, and would make intuitive sense here). Do you think that makes sense to say explicitly?

[AA-Turner]

Perhaps, as it means that the light-touch process can't be used. Thinking again, given this demands behaviour from both indices and installers, it would require a PEP to add a new 'status marker'.

On that note, it might be worth adding a line on the behaviour for encountering an unknown marker. It should never happen given metadata versions, I believe, but an explict 'fail' or 'ignore' might be helpful.

A

[hugovk]

@dstufft Please can you confirm you are sponsoring this PEP?