So this was not an easy decision to make between PEP 722 and PEP 723, making it hard to be the PEP delegate (and that’s ignoring all of the controversy surrounding me being the delegate to begin with). I think pretty much everyone acknowledged that either solution would be great to have, but neither PEP explicitly stood out as objectively better than the other (I saw plenty of comments along the lines of, “I would accept either,” after expressing a preference). So this took a lot of thought, reflecting, and honestly gut feel, to come to a conclusion.
In the end I have decided to accept PEP 723 with the condition that we are okay introducing the
[run] table to
pyproject.toml (i.e., I don’t want
/// pyproject to have anything that’s invalid in
pyproject.toml; it should at best be a subset of what’s available, not a superset). I’m assuming we are okay with this after our last discussion about how
[project] is really meant for what ends up in wheel files, but since PEP 723 has knock-on effects I want to make sure I’m not misreading the room or get accused of sneaking in a change to
pyproject.toml via this PEP. If @pf_moore wants I can make the call about our general comfort on this topic as well.
So, as for why I went with PEP 723 over 722 (although it was admittedly a tough call), I have a couple of reasons. For any who view them as weak or could have gone the other way, then just assume my gut told gave me the ultimate guidance.
First, I realized you are going to need to learn both formats as neither of them are self-explanatory as to what effects that can have. With either you can probably work out that they are listing dependencies, but neither are self-documenting enough for you to understand that e.g.
pipx run script.py will do something magical with what’s listed inside the file. For me, that weakens PEP 722’s argument of being easier to read if you’re going to have to read up on how to use it appropriately anyway.
Second, the user study suggests that learning TOML isn’t that big of a burden. While I fully admit PEP 722 is easier to explain, it seems the delta between the two PEPs is not enough to outright reject PEP 723 for being too burdensome for folks who never go beyond the script-writing stage of Python development.
[run] being in
pyproject.toml, it will help with documentation. Having what PEP 723 provides be what you would put into
pyproject.toml allows for a “doubling up” on documentation and help. Unfortunately with PEP 722, it is a separate thing to learn (e.g., if I was to accept PEP 722 there was going to be a need to add a “requires Python” field, but it would be bespoke to this mechanism, just like how to list dependencies already is; this would continue to be a concern for any other metadata we add in the future). This isn’t a massive burden from PEP 722’s side, but it is a perk.
Fourth, I do appreciate that PEP 723 does help migrate people to
pyproject.toml if that day comes for that user. Admittedly that won’t apply to everyone, but for those that it does it will be a benefit. And assuming my points 1 and 2 are not off, this benefit for those that go as far as a
pyproject.toml will not come at a (great) cost to those who never migrate past PEP 723. Heck, maybe it will even help demystify
pyproject.toml for folks who should actually migrate to that layout anyway since they already did some upfront work.
Fifth, from a tooling perspective, PEP 723 is rather straight-forward:
line.removeprefix("#").removeprefix(" ") to each line you find between the
/// pyproject and
/// markers. Then you simply pass what you have to a TOML parser to tell you if everything is okay. The skew between tools potentially implementing things differently is very much minimized in this regard which will be useful when we have potential tools written in Python, Rust, TypeScript, etc. wanting access to the contained data. Compare this to PEP 722 where you would have to handle comments appropriately, etc. and in a unique, bespoke fashion.
So that’s my reasoning. I think you could have argued in either direction, but thinking long-term (i.e. decades), I think PEP 723 will be the (slightly) better outcome for us. But even if I’m wrong, it luckily won’t be the worst mistake I’ve ever made for Python.
I obviously want to thank both @pf_moore and @ofek for their PEPs and at least attempting to reconcile their differences to avoid needing separate PEPs. And also thanks to everyone who participated constructively in the discussions around these PEPs. Thanks to @courtneywebster for setting up and running a user study on these PEPs, as well as my co-workers listening to me go on and on about this decision. Ditto for my spouse, Andrea, who put up with me talking through this decision with me during our vacation last week.
Regardless of whether your preferred PEP was chosen, hopefully everyone can at least agree that we are getting something that will greatly benefit the community (I for one already have plans on how to use this to hopefully great effect)!