Name for pyproject.toml builds and PEPs

[cjerdonek (Chris Jerdonek)]

@pradyunsg

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 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