From the PEP722 thread:
I think at least part of the reason we’re also considering PEP 723, and why the conversation got to this point, is because a lot of people imagine a different use case. I think that use case looks more like “building multiple binaries from the same directory”, which in turn is much more heavily dependent on the discussion in Projects that aren’t meant to generate a wheel and pyproject.toml.
But the PEP 722 use case doesn’t involve “building” at all, in any meaningful sense. If using a single-file script ever involves needing to know anything more than a) what third-party libraries are needed and b) what Python version is needed, at that point it’s hard to fathom that a tool calling itself a “script-runner” can be helpful.
It’s all well and good to challenge the notion of what a “project” is, and the utility of forcing separate projects into separate folders with specific structures, etc. etc. But if there’s supposed to be some underlying goal of helping to “transition” projects from something that can stand alone in one file to something that requires any kind of “building”, then I think this approach, such as it is so far, fails.
I’m currently +1 on PEP 722 and -1 on this. This is my refutation of the “benefits” section of PEP 723:
Ecosystem confusion
I reserve my objection that configuring a single-file script so that a script runner knows what to do with it, fundamentally, is not packaging. The distribution step in these cases typically appears to look more like attaching a script to an email sent privately, or using a third-party file-sharing service that isn’t necessarily specific to code.
The original intent in PEP 722 was expressly not to facilitate or automate such distribution. The Rationale section starts out: “Because a key requirement is writing single-file scripts, and simple sharing by giving someone a copy of the script”. PEP 723 doesn’t include its own Rationale section, so I can only assume this is still in effect.
Extensibility
I strongly suspect that the two points mentioned here are already an exhaustive list as far as script-runners are concerned. In fact, even including a version number here is not helpful because, again, there is no intent to facilitate or automate distribution.
So, let’s consider those two points. I don’t think even they are significant. First off, the script version. If I write my script to depend on my coworker’s script, and I don’t have the right version, a script runner cannot in principle help me with this.
In this hypothetical, the work flow currently doesn’t involve any automation, isn’t designed for automation, and needs to be completely reworked before automation is possible within the existing ecosystem. My friend and I would both at minimum have to learn how to use a package index, a build tool and an install tool; and the organization might insist that we could only do this with a private package index. Keep in mind, previously we didn’t have to know any of this stuff about the packaging ecosystem (at least, not as long as the script runner could talk to PyPI for us) - more evidence that what we were doing was not packaging.
So that leaves us with only the required Python version. First off, if I am writing the scripts for myself, then I already know what version of Python is needed. If I am sharing scripts within an organization, there’s a good chance that the organization is updating everyone’s system’s Python version in lockstep, if it ever changes at all. I might even be forbidden from installing a separate version privately. But supposing there were a use case for this - if running my script depends on the available version of Python meeting some criterion, then that Python version is a dependency! It just isn’t one that prior PEPs decided should go in the same TOML section as third-party dependencies.
Broader applicability
I can’t imagine anyone would want TOML-specific syntax highlighting to show up within the magic embedded comment that explains the project dependencies. This section is supposed to be about what the dependencies are, not about the demands of TOML syntax. If anything, I would want syntax highlighting that is specific to the syntax of requirements specifiers.
As for package managers, they don’t “gain the ability to run scripts” magically. They still need to implement a run tool. To do so, they would need to regex the script, pass some data to the TOML parser, extract the keys that represent dependencies, and then install them. Using TOML avoids the need to parse a new format, but it comes at the cost of filtering through a data structure, the extensibility of which is still questionably motivated. The PEP722 format is trivial to parse and doesn’t specify anything extra.
Similarly, version checkers don’t to my knowledge already parse pyproject.toml. Having dependency information directly in the file is advantageous for them because of IDE integration, but if the project does grow to have an actual pyproject.toml then… well, that’s a whole other kettle of fish.
Aside from all of that, I’m concerned about the temptation for tools to try to maintain the “embedded TOML”. At a minimum, that will make commit logs look messier.
Assuming that the role of pyproject.toml gets rethought - that we take seriously the idea of project files not intended to build a wheel, and especially consider the idea of using the TOML files as a config format that can have more than one in the same directory - then I absolutely do see value in being able to create such TOML based on something embedded in a single-file script.
But I don’t see, any more, benefit in the embedded text looking like TOML. I still think that the way to go is to have a single tool that creates a skeleton TOML file from the embedded file contents. I think it’s probably about as easy either way. I think that’s much more considerate of the people for whom PEP 722 is intended. And I’m still volunteering to write and maintain it.