PEP 804: version 2, address all feedback received so far

[jaimergp]

• Change is either:
  • To a Draft PEP
  • To an Accepted or Final PEP, with Steering Council approval
  • To fix an editorial issue (markup, typo, link, header, etc)
• PR title prefixed with PEP number (e.g. PEP 123: Summary of changes)

cc'ing co-authors: @rgommers @pradyunsg @mgorny @msarahan

---

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

[mgorny]

Strictly speaking we also suffer from having some Python packages in other categories, particularly when they are also apps or parts of apps.

[jaimergp]

@pradyunsg, can you take a look here whenever you have the time? Thanks! 🙏

[mhsmith]

There's a large amount of repetition and overlap between the upper "central registry", "mappings", and "known ecosystems" sections, and the corresponding sections within "schema details". However, neither of them is complete in itself, so getting a full understanding requires constant scrolling back and forth.

Suggest unifying these into a single specification by merging the upper sections with the "schema details" sections, so that "Specification" would have only 3 child sections. This should make the PEP both shorter and easier to understand.

The table restructuring suggested in my other comment would help give some space where the extra content can go. Even more space could be made by removing the "required" column in favor of a marker inside the "Field" column, e.g. "name (required)". However some material may still be more appropriate to keep outside of the tables, as paragraphs above or below.

[jaimergp]

I've addressed part of this with:

• 53f3548: creates more space for the tables
• bac1563: merges schemas with specification text

Let me know if that's sufficient 🙏

[mhsmith]

Thanks, that's a big improvement, but I still feel like each section would be easier to understand if the introductory text was limited to high-level context and usage rules without getting into format details, and the schema was made into a more complete and self-contained specification. For example:

• Under "Central registry", the provides key says it's "Useful to annotate aliases or virtual package implementations, but you have to go back to the introductory text for examples of these.
• Under "Known ecosystems", the ecosystems dict schema doesn't contain a definition of the format of its own keys, only the introductory text does.
• Under "Mappings", a large amount of detail is still duplicated between the introductory text and the schema, making the section much longer than it needs to be. But some details are not duplicated, e.g. the install command exit code is defined in one place, then several pages later, the format of the command itself. So the reader still has to scroll back and forth a lot and compare the two sections to check whether they've missed anything.

[jaimergp]

Thank you @mhsmith, I'll try my best to accommodate your suggestions!

[mhsmith]

I understand PEP PRs are supposed to be for editorial comments only, so I'll post any substantive comments on the Discourse threads so they can have a larger audience.

[mhsmith]

Suggested change

	The identifier MUST conform to this regex: ``[a-z0-9\-_.]+(\+[a-z0-9\-_.])?``.
	The identifier MUST conform to this regex: ``[a-z0-9\-_.]+(\+[a-z0-9\-_.]+)?``.