Thanks a lot for the context here @epage! I had no idea that this was such a recent change in cargo.
I agree (e.g. auto-populate that section from imports in the file), which is why I think it should be in a structured format.
Yeah, not recognizing //! as a doc comment is my lack of Rust familiarity showing. I don’t see the library case for python though (certainly not in the context of this PEP), and I think a module comment would actually be great for a number of reasons.
There was a concrete example @ofek was responding to…? But to update this in view of @epage’s inputs, how about something à la:
#!/usr/bin/env python
"""
This is the docstring of my script, which does X.
It has the following requirements:
```toml
[requirements]
requires-python = ">=3.9"
dependencies = [
"numpy>=1.22.4",
"requests",
]
```toml
"""
import numpy as np
import requests
print("Hello world!")
This would kill several birds with one stone:
- Still easy to extract (some specially marked section of the docstring)
- Still easy to parse and insert values into programmatically (because it’s a toml file)
- Still consistent with
pyproject.toml - Self-documenting in an already established, canonical place (plus, the docstring of a script sounds like a great place for putting requirements[1])
- Easy to copy & paste to or from actual toml files, because no extra characters (
#etc.) in front - Solves the “which Python version does this script need” problem that came up further upthread
This still has about the same list of things up for bikeshedding as above (e.g. what’s the marker around the toml file, is it [project] or [requirements] or …, etc.), but I hope it’s concrete enough to communicate the intent?
Which is why we’re not talking about the full pyproject.toml, but some reduced form of it. Though the ruff config is a great example IMO of why following existing patterns is better than creating new ones, because people will still want to want to lint their single-file scripts, and that way we’d have a canonical place to put the config (as an extension in the future, not for this PEP).
if it has to be within that script ↩︎