PEP 723: Embedding pyproject.toml in single-file scripts

I was kind of waffling on this for a bit but the current version is really nice and it feels clean to me. :+1:

The TOML document MUST NOT contain multi-line double-quoted strings, as that would conflict with the Python string containing the document. Single-quoted multi-line TOML strings may be used instead.

I’m a little unclear on what you are trying to avoid here. The terminology is a little confusing, but a standard double-quoted string (i.e. "foo") is totally fine inside of a triple-double-quoted ("""bar""") string. Of course trying to nest a triple-double-quoted string in there wouldn’t work, but it’s not useful toml and would break the script anyway. So what’s the danger here?

To me, any string that’s both a) a valid python string and b) valid TOML should be fine, and I’m not sure you need to restrict things more (except in terms of the actual contents)

edit: maybe you are worried about implicitly-concatenated strings, like the pathological

__pyproject__ = ("""[project]
"""
    """
dependencies = ["numpy"]
"""
)

But I think you can prevent this by not allowing the parentheses (a single string shouldn’t need them, and multiple strings are silly). I would prefer that restriction to “no double-quotes”, since I’d use them in my pyproject.toml files.

On that note, you should probably make it explicit that the value must be a string literal, i.e. no dynamic formatting is allowed.

Non-script running tools MAY choose to read from their expected [tool] sub-table. If a single-file script is not the sole input to a tool then behavior SHOULD NOT be altered based on the embedded metadata. For example, if a linter is invoked with the path to a directory, it SHOULD behave the same as if zero files had embedded metadata.

I’m not convinced this is the right idea–imagining the “directory full of one-off scripts” scenario, I think I’d want to run e.g. black and have it respect the metadata embedded in each of the scripts. Maybe I tweaked a formatting rule for one script because it made things easier to read, for instance.

Possibly the answer is “don’t run black on a bunch of unrelated tools” but in that case perhaps it should refuse to process my file, rather than applying defaults? I don’t know if this specific behavior should be specified in the PEP, or maybe it should be left undefined for tools to experiment with.

Note that this example used a library that preserves TOML formatting. This is not a requirement for editing by any means but rather is a “nice to have” especially since there are unlikely to be embedded comments.

Per recent discussions in the PEP 722 thread, I think embedded comments are going to be a common request. But writing a comment-preserving automatic TOML editor isn’t required for this PEP, I think.

1 Like