That’s also a problem for the dependencies case, as name @ url is a valid PEP 508 requirement (see the second example here.
There’s clearly a lot of support for having comments, but it seems they aren’t as simple as they seem at first glance (specifically, @ncoghlan’s proposal as it stands is flawed because it doesn’t support the URL case).
And worse than that, there’s a different error (E265) that reports any comment that doesn’t start with precisely a hash and a space. As far as I can tell, this is motivated by a ridiculously strict reading of PEP 8. Worse still, it looks like ruff has this rule, too - thankfully off by default, but there’s no guarantee that will remain the case.
And while black doesn’t reformat ## comments (or #!), it does add a space in #%, #=, #[ and #] (and I suspect, anything other than space, # or ! after the first hash). So that blocks basically all of the “obvious” alternatives to ##.
There’s a lot to consider here, and it’s not obvious what the best solution is. One possibility is to revert to essentially the original proposal, which follows pipx and pip-run - a single hash, no comments, no internal blank lines:
# Script Dependencies:
# requests
# click
It’s limited, certainly. But it’s free of the flaws identified above, it’s proven in real world use, and it’s simple - which still remains a key goal for me.
There are other options, but I’m not particularly happy with any of them:
- Picking delimiters until we get one that seems to work seems both risky (because of that “seems to”) and arbitrary.
- Treating the flake8 issue as their problem, while it’s what I’d like to do, feels like it’ll just cause confusion and frustration for users.
- There’s even the possibility of using TOML embedded in a specially formatted comment. But that still has all the problems I raise in the PEP about using TOML, and no-one has come up with a satisfying counter-argument to those so far (I’m discounting the people supporting “embedded
pyproject.toml”, as they have mostly been simply saying they disagree, and not actually trying to persuade me to change PEP 722).
I need to think some more about this. I’d appreciate any feedback that people can provide, as long as it’s focused on just finding an alternative “embedded comment” syntax. People who prefer an embedded pyproject.toml have PEP 723, and people who want to debate PEP processes have a separate thread to pursue that discussion in. So it would make my life a lot easier if we could focus feedback on just this issue for now, until it’s resolved in a way that people interested in supporting PEP 722 are happy with.
When I’ve formulated my own thoughts, I’ll post them in a new thread (I think the “slow mode” rule of 8 hours between posts will make it too hard to discuss options, and hopefully by starting a new thread, we can keep things on topic without needing moderator intervention).