Identifiers for packaging specs

The “living standards” on the new PUG page don’t have any identifiers we can refer to them by. Identifiers are useful not just for cataloguing but also mnemonically (it’s quicker to process something easily distinguishable like “621” than a long string of words) and discursively (we don’t talk about “the project metadata spec”, we talk about 621). Can we (re-)introduce these?

2 Likes

If we’re to do that, we probably want to give each standard an “official” short name (the Core Metadata Standard, the Wheel Standard, etc.), instead of numbers. I believe there have been multiple soft suggestions we should reference PEPs less because those numbers are difficult to remember and map to their actual content.

3 Likes

Short official names are substantially better than PEP numbers. The brevity of numbers is nice, but lacking the hints a title provides, requires keeping the PEP index handy. This isn’t difficult, but… can be seriously inconvenient.

-Fred

2 Likes

Maybe, but assigning a random number is comparatively frictionless. Coming up with semantically meaningful identifiers is not an easy task. Terms like “wheel” and “sdist” are easier to remember but are complete jargon to an outsider, no better than a random number.

I don’t think the packaging specifications are really aimed at complete outsiders. Anyone who’s interested has at least some experience consuming Python packages, and will be familiar with the most common terminology from the consumer side.

We should avoid being intentionally obtuse, of course, since that works against everyone.

-Fred

In the US government, the first line in proposed laws is always “This law shall be known as […]”, to give it a handy name to reference it.

It would actually make a lot of sense for every PEP to have a short unique name like that too, assigned when created or when accepted – like PEP 440 could be “version-syntax”, PEP 619 could be “py310”, PEP 503 could be “pypi-simple-api”, PEP 13 could be “governance”.

First draft shoddy table:

old                         new
--------------------------  ------------
none (superseded)           coremeta
pep440                      verspec
pep508                      depspec
pep425                      tags
pep518                      buildmeta
pep517                      buildapi
pep621                      projectmeta
pep376, 627                 install
pep610 (superseded)         installdirecturl
none                        installentrypoints
none                        sdistfmt
pep427 (superseded)         wheelfmt
pep503, 592, 629            simpleapi

Feel free to suggest alternatives. This is the one time when no one’s gonna tell you off for bikeshedding :stuck_out_tongue:

This would have been very helpful in my rewrite of PEP 639, which references basically all of them heavily, as I often struggled to refer to them by names that were standardized, readable yet concise. I ended up having to define a whole terminology section of both standardized terms and many that aren’t formally defined to handle this, particularly to refer to the nouns that some of the verb-named standards define. Reframing the names to use, or at least refer to a specific noun rather than a verb would be more convenient and usable for referencing elsewhere, particularly PEPs and other specs.

For example, it is verbose, awkward and potentially confusing to refer to a format as “the source metadata format defined in the Recording Project Metadata specification”, as opposed to just the “Project Source Metadata Format”, and the latter still doesn’t uniquely specify the format originally defined in PEP 621 and stored in the [project] table of the pyproject.toml, as opposed to other such formats (setup.cfg and other tool-specific methods) without prepending PEP 621, which even though technically imprecise is still practically clearer given its wide use and the inherent ambiguity in just using even the modified standard title, much less the original. As such, this required including the full term (PEP 621 project source metadata) in a terminology section and referring to it as such through the PEP, which necessarily doesn’t match the name of the original standard nor necessarily all common usage.

As such, having a short, standardized, unambiguous and human-readable way to uniquely refer to each of those standards would be very beneficial, though I’m still forming an opinion on precisely what this should look like. I wouldn’t favor clipping words and concatenating them directly together in all lowercase, as this harms human readability and clarity, while as far as I’m aware there is no proposal for making them machine-readable where this would matter. Standardized names should be concise, but clear enough to unambiguously and uniquely identify the specific standard by themselves to a user familiar with the standards but not necessarily the particular shortname.

They are abbreviations. They don’t need be in lowercase and monospace; they should be unambiguously identifiable as identifiers and favour brevity. In my mind, at least.

1 Like