# Name for pyproject.toml builds and PEPs **URL:** \ **Category:** Packaging\ **Tags:** bikeshed\ **Created:** [May 11, 2019, 12:45pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659 "2019-05-11T12:45:52Z")\ **Posts on this page:** 20\ **Page:** 1
**Author:** ![pradyunsg](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/pradyunsg/32/206_2.png) [@pradyunsg](https://discuss.python.org/u/pradyunsg)\ **Post date:** [May 11, 2019, 12:45pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/1 "2019-05-11T12:45:52Z")
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. ---
**Author:** ![cjerdonek](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/cjerdonek/32/63_2.png) [@cjerdonek](https://discuss.python.org/u/cjerdonek)\ **Post date:** [May 11, 2019, 3:09pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/2 "2019-05-11T15:09:59Z")
> [@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](https://github.com/pypa/pip/issues/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](https://www.python.org/dev/peps/pep-0517/): > 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](https://github.com/pypa/pip/pull/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](https://twitter.com/EWDurbin/status/1125459954847113217) ---
**Author:** ![pradyunsg](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/pradyunsg/32/206_2.png) [@pradyunsg](https://discuss.python.org/u/pradyunsg)\ **Post date:** [May 11, 2019, 4:22pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/3 "2019-05-11T16:22:26Z")
I think we agreed that calling it the flat layout is fine. None the less, I think that can be a different topic. ---
**Author:** ![pradyunsg](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/pradyunsg/32/206_2.png) [@pradyunsg](https://discuss.python.org/u/pradyunsg)\ **Post date:** [May 12, 2019, 8:47pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/4 "2019-05-12T20:47:58Z")
@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. 🙈 ---
**Author:** ![pradyunsg](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/pradyunsg/32/206_2.png) [@pradyunsg](https://discuss.python.org/u/pradyunsg)\ **Post date:** [December 29, 2020, 6:14pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/5 "2020-12-29T18:14:34Z")
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? ---
**Author:** ![bernatgabor](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/bernatgabor/32/3003_2.png) [@bernatgabor](https://discuss.python.org/u/bernatgabor)\ **Post date:** [December 29, 2020, 6:48pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/6 "2020-12-29T18:48:22Z")
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. ---
**Author:** ![pradyunsg](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/pradyunsg/32/206_2.png) [@pradyunsg](https://discuss.python.org/u/pradyunsg)\ **Post date:** [December 29, 2020, 6:55pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/7 "2020-12-29T18:55:52Z")
> [@bernatgabor](#): > > PEP-517/518 packaging environment Yea, I’ve been calling it something like that too – but this feels like a mouthful and even user-hostile at some level. * * * 💡 “pyproject.toml based builds” is probably the best name I can think of. ---
**Author:** ![pf\_moore](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/pf_moore/32/35_2.png) [@pf\_moore](https://discuss.python.org/u/pf_moore)\ **Post date:** [December 29, 2020, 7:21pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/8 "2020-12-29T19:21:23Z")
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. ---
**Author:** ![encukou](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/encukou/32/2461_2.png) [@encukou](https://discuss.python.org/u/encukou)\ **Post date:** [December 30, 2020, 8:57am UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/9 "2020-12-30T08:57:25Z")
Just `pyproject` is a pretty good name, too. ---
**Author:** ![pradyunsg](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/pradyunsg/32/206_2.png) [@pradyunsg](https://discuss.python.org/u/pradyunsg)\ **Post date:** [November 2, 2022, 10:35pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/10 "2022-11-02T22:35:05Z")
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](https://pip.pypa.io/en/stable/reference/build-system/) 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). ---
**Author:** ![pradyunsg](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/pradyunsg/32/206_2.png) [@pradyunsg](https://discuss.python.org/u/pradyunsg)\ **Post date:** [November 18, 2022, 3:59pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/11 "2022-11-18T15:59:30Z")
IIUC, [Rename this project to `pyproject-hooks` and trim functionality · Issue #136 · pypa/pyproject-hooks · GitHub](https://github.com/pypa/pyproject-hooks/issues/136) 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. 😅 ---
**Author:** ![fungi](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/fungi/32/5963_2.png) [@fungi](https://discuss.python.org/u/fungi)\ **Post date:** [November 18, 2022, 5:47pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/12 "2022-11-18T17:47:29Z")
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? ---
**Author:** ![ncoghlan](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/ncoghlan/32/14266_2.png) [@ncoghlan](https://discuss.python.org/u/ncoghlan)\ **Post date:** [November 27, 2022, 1:43am UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/13 "2022-11-27T01:43:32Z")
The stable link for version specifiers is [Version specifiers — Python Packaging User Guide](https://packaging.python.org/en/latest/specifications/version-specifiers/) 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” ---
**Author:** ![fungi](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/fungi/32/5963_2.png) [@fungi](https://discuss.python.org/u/fungi)\ **Post date:** [November 27, 2022, 1:15pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/14 "2022-11-27T13:15:05Z")
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. ---
**Author:** ![pf\_moore](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/pf_moore/32/35_2.png) [@pf\_moore](https://discuss.python.org/u/pf_moore)\ **Post date:** [November 27, 2022, 1:53pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/15 "2022-11-27T13:53:12Z")
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. ---
**Author:** ![pradyunsg](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/pradyunsg/32/206_2.png) [@pradyunsg](https://discuss.python.org/u/pradyunsg)\ **Post date:** [November 27, 2022, 4:19pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/16 "2022-11-27T16:19:37Z")
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. 🙂 ---
**Author:** ![fungi](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/fungi/32/5963_2.png) [@fungi](https://discuss.python.org/u/fungi)\ **Post date:** [November 27, 2022, 10:17pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/17 "2022-11-27T22:17:43Z")
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). ---
**Author:** ![pf\_moore](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/pf_moore/32/35_2.png) [@pf\_moore](https://discuss.python.org/u/pf_moore)\ **Post date:** [November 27, 2022, 10:47pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/18 "2022-11-27T22:47:46Z")
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. ---
**Author:** ![fungi](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/fungi/32/5963_2.png) [@fungi](https://discuss.python.org/u/fungi)\ **Post date:** [November 28, 2022, 1:55pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/19 "2022-11-28T13:55:06Z")
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. ---
**Author:** ![encukou](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/encukou/32/2461_2.png) [@encukou](https://discuss.python.org/u/encukou)\ **Post date:** [December 7, 2022, 1:40pm UTC](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659/20 "2022-12-07T13:40:40Z")
> [@pradyunsg](#): > > 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 just noticed the Rust library `pep440`: [crates.io: Rust Package Registry](https://crates.io/crates/pep440) Edit: Apparently there’s `pep508` as well: [crates.io: Rust Package Registry](https://crates.io/crates/pep508) [Next page](https://discuss.python.org/t/name-for-pyproject-toml-builds-and-peps/1659.md?page=2)