Name for pyproject.toml builds and PEPs

One of the take aways I have from the discussions I had at PyCon US 2019 is that we need a better name for our PEP 517, 518 and to be written editable installs PEP.

Currently, it is trivial for us “experts” to communicate using PEP numbers since we’re all mostly aware of these things and it’s unambiguous. However, a PEP number doesn’t mean much to an average python user.

It would probably help if we’re able to think of a name that covers these newer build mechanisms to make it easier to talk about them.

I haven’t been able to come up with anything other than “modern” and I figured starting a conversation is more important than starting with a good suggestion.

3 Likes

I agree. I had actually started doing this for PEP 517 using the naming we already had from the PEP. This was in the changes I made for 19.1, but which we later reverted. There was also an issue (issue #6256, “pip’s error message for wheel-build failure on PEP 517 packages isn’t very friendly”) filed about this for PEP 517, which is what gave me the idea.

If you look at PEP 517, fortunately it already does explicitly provide one way of speaking about the newer behavior without having to reference the PEP number. It calls it “pyproject.toml-style” (versus the older “setup.py-style”). From PEP 517:

There is an existing, legacy source tree format involving setup.py. … We’ll refer to it as the setup.py-style.

Here we define a new style of source tree based around the pyproject.toml file defined in PEP 518, extending the [build-system] table in that file with one additional key, build-backend. …

And then later the document refers to them explicitly as pyproject.toml-style source trees. It may not be the best name, but it’s a documented name we have now.

PR #6370 is one of the PR’s where I incorporated this terminology instead of the number. Here’s an example of one of the error messages from the PR:

Error installing ‘my-package’: editable mode is not supported for pyproject.toml-style projects. pip is processing this project as pyproject.toml-style because it has a pyproject.toml file. Since the project has a setup.py and the pyproject.toml has no “build-backend” key for the “build_system” value, you may pass --no-use-pep517 to opt out of pyproject.toml-style processing. See PEP 517 for details on pyproject.toml-style projects.

More generally, I agree strongly with the idea that whenever a PEP introduces a new concept, one of the tasks should be to choose a good human-friendly name for each new concept introduced. (The “yanked” terminology in PEP 592 is a good example of a human-friendly name associated with a PEP.)

Another naming question that came up at PyCon US was what to call the project layout that isn’t the “src layout.” Towards the end of the src layout discussion, I said this is something I thought we should try to decide on. Here’s the slide about it (the one that says “name for non-src layout”): https://twitter.com/EWDurbin/status/1125459954847113217

1 Like

I think we agreed that calling it the flat layout is fine. None the less, I think that can be a different topic.

@cjerdonek reminded me that I had stopped the conversation on the name for non-src/ layouts, and we didn’t really complete that conversation.

Sorry for the mess up on that. My brain is mixing discussions from PyCon already. :see_no_evil:

I’d like to nudge this discussion again – what I’m hoping to get out of this is some sort of concensus on a good name to refer the “system” that PEP 517 + PEP 518 + whatever-the-editable-PEP-will-be collectively describe.

Any thoughts/opinions from folks here?

Well, I think the easiest to understand by most people will be the modern Python build environment, but today at litera it’s the isolated API build system (isolated due to PEP-518, and API because PEP-517 introduces a programmatic API to communicate with backends). I generally refer to it to my colleagues as the PEP-517/518 packaging environment.

1 Like

Yea, I’ve been calling it something like that too – but this feels like a mouthful and even user-hostile at some level.


:bulb: “pyproject.toml based builds” is probably the best name I can think of.

3 Likes

The term "pyproject.toml based build" seems like the best option.

I’m not a fan of “modern”, is feels like it’s asking for trouble in the future. And “isolated” isn’t accurate - it’s perfecly OK to have a pyproject.toml based build that isn’t isolated, it’s just up to the user to set up the build environment.

4 Likes

Just pyproject is a pretty good name, too.

1 Like

FWIW, to close out the loop on this with an update, after a couple of years:

I’ve since written Build System Interface - pip documentation v22.3

This has ended up getting called the “pyproject.toml based build system” and I’ve been mostly calling this “pyproject.toml-based builds” whenever this comes up in a discussion for quite some time now. The older mechanism is the “legacy setup.py based builds” (trying to include the legacy bit whenever I can. :P).

Multiple tools have since moved away from using pepNNN naming to pyproject-{thing} naming (or are in the process of doing so).

2 Likes

IIUC, Rename this project to `pyproject-hooks` and trim functionality · Issue #136 · pypa/pyproject-hooks · GitHub is the final major piece as part of the broader initiative of “don’t use PEP numbers for referencing packaging functionality” that this thread originally identified.

If anyone knows of tooling that still uses a “pepNNNN?” to refer to some sort of Python packaging functionality, I’d appreciate it if you could share that here. I’ll mention pip’s --[no]-use-pep517 flags. :sweat_smile:

1 Like

I’ve got projects that still refer to “PEP 440 compliant version
strings” and link to the PEP 440 text for that specification. What
is the formal replacement document for the standard version grammar
these days?

3 Likes

The stable link for version specifiers is Version specifiers — Python Packaging User Guide

The spec currently hasn’t changed since PEP 440 though, so it’s mostly just a link to the PEP text.

If any substantial amendments are ever made, then the PEP making them will just describe the changes, and the combined result will be posted directly on the spec page.

As far as alternate names go, the same approach as discussed above would apply: the more user friendly alternative to “PEP 440 compatible version string” would be “pyproject compatible version string”

And do you anticipate versioning the version-specifiers document
itself if another PEP comes along to revise or extend it? For
example, I can imagine applications supporting the pyproject version
standard described by PEP 440 may not immediately implement support
for whatever PEP NNNN which comes later, so would need to be able to
clarify that they are pyproject versions v1.0.0 compatible but not
(yet) compatible with pyproject versions v1.1.0.

As the current PEP-delegate, I would take the view that any new PEP changing the rules on versions would have to discuss backward compatibility, and propose a workable solution to any such problems.

But I’m not aware of anyone even considering a change where this would come up, so I don’t think there’s any need to worry too much about the possibility right now.

Backwards compatibility is a dedicated section in the PEP template and I doubt we’d ever make a backwards-incompatible versioning update without an extensive discussion about that. :slight_smile:

2 Likes

I was thinking more in terms of forward compatibility, e.g. if my
library supports things described in PEP 440 but not some
additions/extensions to versioning specified in a successor. Letting
users know what subset of the standard they can expect to use it
with at any given point in time would potentially need some way to
differentiate those. I suppose the new features could be enumerated,
but that would require someone being around and aware to update the
lib’s documentation, vs being able to say that the current standard
is implemented and not (yet) any future revisions which would
require the current standard to have an explicit version to which
documentation can refer (what referring to PEP 440 instead gets me
right now).

1 Like

I’d expect that to be covered under “backward compatibility” in any new version PEP (I’m not particularly interested in hair-splitting over forward vs backward). But I still think we shouldn’t worry unless (until) we get a real proposal.

Thanks, I’ll try to find a way to convey in documentation that the
project is compatible with version strings following the pyproject
versioning standard circa 2022, but may not be able to correctly
parse version strings relying on any future amendments to the syntax
unless otherwise specified. Being able to say it supports strings
which follow pyproject versioning 1.0.0 would have been clearer, but
I understand the desire not to commit to a version tracking plan for
standards publication.

I just noticed the Rust library pep440: crates.io: Rust Package Registry

Edit: Apparently there’s pep508 as well: crates.io: Rust Package Registry

1 Like