How would you like to declare runtime dependencies and Python requirements for PEP 723?

[pf_moore (Paul Moore)]

I was assuming that Brett’s comment

@brettcannon

If we decide this is the way to go, then we could rename # /// pyproject to something like # /// run if it would represent an implicit [run] if we ever put what’s in PEP 723 into pyproject.toml. And that could become what a hypothetical, future PEP proposes. But the name change would also help make clear that while we are taking TOML for a common syntax, it is technically separated from pyproject.toml.

implied that the section name was up for discussion. On re-reading I’m not so sure - Brett only uses /// run in the context of it being an implied match for a potential [run] section in pyproject.toml.

So I guess I’m still not clear:

1. As PEP delegate, is @brettcannon now allowing discussion of section names not associated with pyproject.toml?
2. What does that imply for the link between PEP 723 and pyproject.toml?

[pradyunsg (Pradyun Gedam)]

@pf_moore

What does that imply for the link between PEP 723 and pyproject.toml?

One of the outcomes of the poll (and discussion) here could be that we break this link entirely. I’m saying this based on some of the sentiment expressed in this discussion and the following from the first post:

(Assume the result may not end up in pyproject.toml .)

---

@pf_moore

As PEP delegate, is @brettcannon now allowing discussion of section names not associated with pyproject.toml?

Brett does not have magic powers to prevent people from doing certain things. If he does, please use them on something more important than this discussion.

More seriously, I agree that it’s useful to have clarity on whether such a change to the PEP would be deemed acceptable. Given that + the ongoing poll, I think it would be good to hold off on going too far down this path until the poll is resolved by sometime next week.

We’ve been talking about this topic for quite a while as a group and, IMO, it would be a good idea for us all to take a bit of a breather until this poll ends.

[brettcannon]

@pf_moore

The poll doesn’t mention [tool] sections, and in all the debate I think they’ve been forgotten.

I haven’t forgotten about them, I just don’t think it’s critical. We have to draw the line somewhere for when you shift to pyproject.toml. If that’s [tools] then I’m okay w/ that. At some point we may have to say that or wants are too sophisticated and you need to “upgrade” to pyproject.toml. So I’m personally flexible on this topic.

@pf_moore

@pradyunsg

If we’re trying to pick a color of the bikeshed here, here’s a proposal

I like this, and as you say it’s basically a bikeshed colour, so I don’t think it’s worth much debate. Anything would work, this is nice, great - job done.

However, there’s an ongoing poll with 5 days left to run, which might come up with a different result (this is essentially option 2). I think we have to wait for the poll to complete before actually doing anything. People who like this idea and haven’t already voted option 2 can vote (or change their vote) if they want to support it.

I agree; if you like Pradyun’s proposal, go w/ option 2.

@pradyunsg

This is literally script metadata, after all. Let’s call it that. That clearly indicates that it’s separate from project metadata or even how things are run or what a project is.

If we were to do this, I imagine we would have TypedDicts for script parsing output and pyproject.toml in packaging.

@pf_moore

As PEP delegate, is @brettcannon now allowing discussion of section names not associated with pyproject.toml?

Sure, but I was waiting to see the poll results first since option 3 doesn’t necessitate that. I’m also fine on choosing the name to avoid bikeshedding (if the poll suggests such an outcome).

@pradyunsg

@pf_moore

What does that imply for the link between PEP 723 and pyproject.toml?

One of the outcomes of the poll (and discussion) here could be that we break this link entirely. I’m saying this based on some of the sentiment expressed in this discussion and the following from the first post:

(Assume the result may not end up in pyproject.toml .)

Pradyun’s right: if the poll/discussion demonstrates folks want to “break this link” for what they consider better ergonomics, then so be it. If option 2 wins, that is definitely a sentiment I’m taking away from the poll since there’s no guarantee option 2 would get accepted for pyproject.toml (hence the line in the poll not assuming the results will ultimately influence pyproject.toml). I would still consider that a win as it at least got us to a consensus on this topic compared to when I had to decide between PEPs 722 &723.

@pradyunsg

We’ve been talking about this topic for quite a while as a group and, IMO, it would be a good idea for us all to take a bit of a breather until this poll ends.

There’s a reason I made the poll last a week.

[SnoopJ (James Gerity)]

I voted for Option 2 for its conciseness (read as: I would personally find it less annoying to include in a “script”), but I find some of the arguments along the lines of “what about such-and-such table?” to be compelling.

I have not been following the conversation closely, but discussion PEP 723 seems to be stuck between two conflicting interpretations of the PEP’s goals (though I understand that this is natural for a provisional PEP). Option 2 is in direct conflict with the current text of the PEP’s rationale, for instance (emphasis mine):

The following are some of the use cases that this PEP wishes to support:

…

• …by using the same format, the user can simply copy and paste the metadata into a pyproject.toml file…

I am left wondering what problems PEP 723 is most interested in solving.

If the principal concern is specifying runtime dependencies, I think an ad-hoc specification that “rhymes” with pyproject.toml is fair game, and the above quoted text should be deleted from the PEP.

If it’s meant to be truly arbitrary, I think the included metadata should be 1:1 with pyproject.toml as much as possible (i.e. I should be able to copy/paste with zero changes) to avoid coming up with a conflicting specification.

[brettcannon]

@SnoopJ

I am left wondering what problems PEP 723 is most interested in solving.

Making it easy to define details specifying what requirements a script has for execution.

Consistency w/ pyproject.toml would be great, but if the poll suggests people want to prioritize the ease in which the requirements are written then that trumps consistency. We can always try to bring anything new that’s introduced over to pyproject.toml in a later PEP.

[brettcannon]

FYI the poll results are out. I will think about them and post my thoughts this week.

[holdenweb (Steve Holden)]

Or perhaps include a conversion tool to translate the PEP 723 headers into a pyproject.toml, to make the transition less painful?

[pf_moore (Paul Moore)]

I’m still not clear on how the semantics match. IMO that’s far more important than the syntax (which as you say can be handled by a tool).

[brettcannon]

If you go back to my provisional acceptance of PEP 723, I laid out the following reasons for selecting it over PEP 722:

1. Allowing for [run] to be used in both scripts and pyproject.toml means simpler docs as the semantics of the keys only need to pe explained once

2. … allows for easier transitioning

3. Parsing is simpler since TOML is a standard

And so I made the acceptance of PEP 723 conditional on having pyproject.toml symmetry.

But then a few things happened. First, I came up w/ a simplification of what TOML format to support. Second, @pf_moore said he would have accepted the simplified proposal as a PEP 722/723 compromise (as well as other suggestions). Third, I came to think that I care more about the pyproject.toml connection more than most.

This led to my poll about options regarding PEP 723. Those results seemed to suggest I was right about me carrying more than others about pyproject.toml support. Then @pradyunsg posted his strawman take of option 2 which @pf_moore also liked.

So what’s wrong w/ option 2? From a quick glance it suggests that if option 2 had been around when PEPs 722 and 723 were being formulated that it would have been a single PEP and my life as PEP delegate would have been way simpler . But the wrinkle in all of this is Ofek wants a table to encompass everything. And I do get that desire from an organizational perspective and potentially ease of expansion in the future. It would require separate # /// sections for any other subsequent table, though, if it was meant to implicitly suggest some TOML table.

Pragmatically, I think what @pradyunsg proposed is a good solution. Something I saw in the user studies for the PEPs is that users looked at the table declaration sideways and then just chaulked it up to being required for some reason they just happened to not know. Now that’s not bad, but it isn’t great either. With Pradyun’s proposal, it’s a bit more straightforward, especially by calling the section “script” instead of “pyproject”. And if we are aiming at beginners while trying to make tooling around this easier, then I think I need to let go of my desire to have symmetry with pyproject.toml to lean into the simplicity aspect more. I think changing the section name definitely helped me let go of things and view this as a more isolated thing that has the potential to have symmetry with pyproject.toml (even if PEP 735 and dependency groups lands, I still think having a way to define Python requirements would be useful in pyproject.toml).

So, if @ofek is okay with the changes (please explicitly say yes or no, Ofek), I would like PEP 723 to be updated with Pradyun’s proposal:

1. Drop the [run] table and make dependencies and requires-python top-level
2. Rename # /// pyproject to # /// script

That would lead me to accepting PEP 723 unconditionally. This should also allow pipx, if it wants to, to maintain backwards-compatibility with what it has already shipped (but this was not a consideration in this decision, it’s just a nice side-effect).

I know @pf_moore mentioned above that he would be willing to help @ofek make the requisite changes to the PEP; hopefully Paul’s generous offer still stands if Ofek doesn’t have the time.

[ofek (Ofek Lev)]

I am absolutely fine with the aforementioned changes. Since this is unrelated to project metadata now and there is no overlap, can we please keep tool configuration since maintainers of said projects have expressed interest in such a feature?

[pradyunsg (Pradyun Gedam)]

@ofek

can we please keep tool configuration since maintainers of said projects have expressed interest in such a feature?

Yes, I read what Brett says to mean that since:

1. My proposal explicitly included tool configuration.
2. The PEP currently has language permitting the tool table, and a change to that has not been requested.

[ofek (Ofek Lev)]

If Paul is able to update the PEP I would greatly appreciate it, otherwise I won’t have time until after the holidays.

[pf_moore (Paul Moore)]

I’ll try to get some time to put together a PR (although TBH I will also have limited time over the holidays).

[brettcannon]

@pradyunsg

Yes, I read what Brett says to mean that since:

1. My proposal explicitly included tool configuration.
2. The PEP currently has language permitting the tool table, and a change to that has not been requested.

Correct.

@ofek

If Paul is able to update the PEP I would greatly appreciate it, otherwise I won’t have time until after the holidays.

@pf_moore

I’ll try to get some time to put together a PR (although TBH I will also have limited time over the holidays).

Don’t rush on my account! I’ll be around in January.

[pf_moore (Paul Moore)]

@brettcannon

So, if @ofek is okay with the changes (please explicitly say yes or no, Ofek), I would like PEP 723 to be updated with Pradyun’s proposal:

1. Drop the [run] table and make dependencies and requires-python top-level
2. Rename # /// pyproject to # /// script

That would lead me to accepting PEP 723 unconditionally.

I’m looking at this now, and one thing that’s implied, but not stated explicitly, is that this would mean that we no longer argue that the PEP 723 format is “embedding pyproject.toml”. So I’m assuming we remove the discussion in the rationale that makes this argument?

Also, am I right in thinking that the [tool] section would therefore now be in the # /// script block, not that we’d have a # /// script block for the dependency data and a # /// pyproject block solely for [tool]?

I’ve created a draft PR here based on Brett’s request and the above assumptions. I still need to make sure I didn’t break any hyperlinks with my edits, and do a proofreading pass, but if anyone has time to review the PR, I’d be very grateful.

[brettcannon]

@pf_moore

one thing that’s implied, but not stated explicitly, is that this would mean that we no longer argue that the PEP 723 format is “embedding pyproject.toml”. So I’m assuming we remove the discussion in the rationale that makes this argument?

Makes sense to me to remove it.

@pf_moore

Also, am I right in thinking that the [tool] section would therefore now be in the # /// script block, not that we’d have a # /// script block for the dependency data and a # /// pyproject block solely for [tool]?

Correct. I don’t think we want to proliferation of # /// sections.

@pf_moore

I’ve created a draft PR here based on Brett’s request and the above assumptions. I still need to make sure I didn’t break any hyperlinks with my edits, and do a proofreading pass, but if anyone has time to review the PR, I’d be very grateful.

I’ll go review it right now!

[brettcannon]

@pf_moore @ofek are you waiting on me for anything?

[pf_moore (Paul Moore)]

No, I just forgot to move the PR from draft mode. Sorry, I’ll do that today.

Edit: I did merge the PR, about 2 weeks ago. Was there something else you were referring to?

[brettcannon]

@pf_moore

Edit: I did merge the PR, about 2 weeks ago. Was there something else you were referring to?

Just trying to figure out the next step. Are you just waiting on me to do a more final acceptance? Something else?

[hugovk (Hugo van Kemenade)]

Yes, I belive the next step is for you to fully accept the PEP:

@brettcannon

So, if @ofek is okay with the changes (please explicitly say yes or no, Ofek), I would like PEP 723 to be updated with Pradyun’s proposal:

1. Drop the [run] table and make dependencies and requires-python top-level
2. Rename # /// pyproject to # /// script

That would lead me to accepting PEP 723 unconditionally.

python/peps#3601 updated 1 and 2.