Name for pyproject.toml builds and PEPs

bikeshed
(Pradyun Gedam) #1

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.

2 Likes
(Chris Jerdonek) #2

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
Draft PEP: Recording the origin of distributions installed from direct URL references
(Pradyun Gedam) #3

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

(Pradyun Gedam) #4

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