Addendum for PEP 722 to use TOML

Packaging
2

Should we open a new discussion thread for feedback on this second proposal?

If not, please find my comments below.

Any Python script may assign a variable named __pyproject__ to a multi-line double-quoted string containing a valid TOML document
…
This regular expression may be used to parse the metadata:
(?ms)^__pyproject__ *= *"""$(.+?)^"""$

I think it worth to emphasize the double-quoted part on this definition or even explicitly say that single-quotes are forbidden[1]

  • The name and version fields MUST be defined dynamically by tools if the user does not define them

I believe that name and version are not relevant in the scenario in which the user just wants to run a script (this is different from a packaging perspective). I don’t think it makes sense to force tools to define them automatically. There might be simply no use for them to define it (I think this is OK as an implementation detail for an specific tool, but not all the tools have to comply with that).

[project] table

The [project] table is designed with the packaging use-case in mind[2], and therefore might expose information that is not relevant in the case of “running a single-file script”. Moreover, the type of information necessary to “run a single-file script” and the type of information necessary for packaging[2:1] might diverge (even more) with time. Right now we already see divergence in the PEP draft: the PEP makes a few considerations to “special case” the [project] table for the “running single-file script” use case (like adding exceptions for dynamic behaviour)[3].

If the idea is to re-use the pyproject.toml spec and the TOML language, it would be better to follow whatever comes up from the discussion on Projects that aren't meant to generate a wheel and `pyproject.toml`, instead of necessarily the [project] table. For example, if the outcome of the other discussion is to use a [run] table, then maybe this PEP should use a [run] table too.

Benefits

The PEP has a benefits section that kind of presents a comparison (maybe not too explicit) with the other PEP. Would it make sense to have a pros/cons section? The draft list some pros, and I can see a few cons that could make sense to make explicit in the PEP:

  • The use of TOML language makes it more difficult to parse the definition block and may require 3rd-part dependencies. While this is not a problem for Python >= 3.11 (thanks to tomllib), it might impose implementation difficulties for tools implemented in other versions of Python or other languages.
  • Users may expect other tools to interpret embedded pyproject.toml for functionalities not related to “running a single-file script”. They might be surprised when the expectations are not met.
  • Since dunder attributes have (usually) special meaning in Python, users might expect that this is handled by Python itself and not a third party tool. They might be surprised when the expectations are not met.

(probably there are more cons listed in this thread)

  1. The provided reference implementation becomes incompatible if single quotes are allowed. ↩︎

  2. Here I use the term “packaging” to express “the process of bundling files together to create a python distribution archive (sdist or wheel) file”. ↩︎ ↩︎

  3. Also it does not specify what tools are expected to do if they find keys like optional-dependencies or entry-points. ↩︎

5 Likes