PEP 621: how to specify dependencies?

Not really imo: PEP 621: how to specify dependencies?

I think one of the major gaps here is that to some of us it’s obvious that the exploded table is more readable, but to others that’s not obvious at all :-). How is one of these more self-explanatory to the naive reader?

# exploded table
[dependencies]
some-package = ">= 1.2"
another-package = {"version >= 0.3", python = "<3"}

# PEP 508
dependencies = [
    "some-package >= 1.2"
    "another-package; python_version < '3'"
]

I just don’t see how slightly different quoting, or the choice of python versus python_version, is going to make one of them more self-explanatory for naive users.

I can see that you and @sdispater and others are passionate about the exploded form being better, so I know I must be missing something. Can you help us bridge that gap? What is it that you’re fighting for, that makes this decision so important to you?

5 Likes

This specification provides input to an artifact (sdist or wheel). If you have an artifact, its defined metadata wins.

If you just have an archive/directory of files or repository, and there’s a pyproject.toml, you can trust it (and don’t have to write heuristics for all the other ways you might try and discover the same information, such as looking for setup.cfg or parsing arbitrary sections of pyproject.toml).

I’d expect tools to validate when they generate package metadata from pyproject.toml, so they need to be able to parse and generate whatever format the user input is in, PEP 508 or not. The two formats are not much different in this regard since both need to be parsed and made sense of.

Mine doesn’t :grin: Deliberately

I’m targeting users who can read and follow specs themselves and don’t want to fight with their tools. So any metadata keys or values they provide go straight into the output. They can test it themselves.

Maybe it’s only me, but I spend more time hacking around the packaging tools than just using them. So I wrote a backend that wouldn’t make me do it :wink:

1 Like

Agreed, we don’t want more doubts like this: Helping dependabot and github detect python dependencies

1 Like

I think it’s pretty clear that we don’t have a clear concensus here, and (it seems to me like) things are escalating and getting a bit more emotionally charged here.

Which brings me to – How do we move forward on this?

  • someone properly specifies exploded-tables approach, for a proper A/B comparision of the two formats and [TBD approach] is used to determine what to do?
  • leave this out of PEP 621, for a future PEP (cough PEP 517 editable installs cough)?
  • something else?

I think this is the only viable approach :+1: That future PEP can contain this A/B test, etc.

If this is left out then we need to think through how it will ever get introduced in the future. If it isn’t in dynamic now then the transition of introducing it later is going to always be muddled compared to the rest of the metadata as the one thing that can be “sneaked” in by the build tool without being declared in dynamic.

Honestly, I would rather defer the PEP than propose it without this part of it included (which is fine; if I have to wait until I can find a teacher to A/B test this in front of two separate classrooms of students to see which is easier for new programmers or take a live poll at PyCon US when that’s even feasible again then so be it). Otherwise I think we are simply punting on a hard question that is going to make implementation and transition harder just to avoid painful choices rather than just finding a way to answer this amicably (or decisively).

4 Likes

IMO it is best to defer the PEP until we can have some kind of provisional structure to dependency specification. It is probably the most useful part of static metadata specification (license being the distant second, which PEP 621 is also not specifying), and it’s not worth the effort to plan a transition if the other stuffs aren’t that urgent on their own. Personally I’d see it most reasonable to

  1. Put this on hold.
  2. Propose at least one draft PEP to specify the exploded TOML format (or more generally “a structured format to specify dependencies for a Python project”).
  3. Run that A/B test.
  4. (Optional) Finish the SPDX specification in the mean time
  5. Include whatever was decided in the above steps to PEP 621, and accept it.

(I am willing to find sometime to propose one format for step 2, but no promises :slightly_smiling_face:)

1 Like

For those who are suggesting that we run some sort of A/B test, I’m curious to know, what results would give us a definitive answer on this?

If the A/B test showed no difference in preferences or a poll gave something close to 50/50, what would the choice be? What if there’s a mild preference for one or the other? What if there’s a strong preference for A among new users and a strong preference for B among established users?

One of the reasons that I think we shouldn’t bother with attempting to gather more data is that I don’t think that the arguments hinge significantly on questions of fact about the merits of either system, I think they come down to a difference of opinion about how important the various factors are.

Even if it turns out that everyone universally expresses a mild preference for exploded TOML format in isolation (i.e. when shown the two side by side), I’d still be strongly in favor of the PEP 508 representation because I think we should value consistency and it’s impossible to be consistent using the exploded TOML format.

Are there any among us who believe that there will be a strong and universal preference for either exploded TOML or PEP 508? I think there’s a large amount of circumstantial evidence that people are just not that bothered by either format.

2 Likes

Administrative note: I’ve gone into full-on PEP delegate mode at this point. No-one has objected to me making the decision on this PEP, or pushed to take on the role in my place, so I plan on making the decision myself. So please consider my comments from now on in that context¹.

All of this discussion is still circling around the key point, which is that ultimately, someone has to submit a PEP and that will get accepted or rejected. @brettcannon presented PEP 621 in this thread, so I expect him to be the one to formally submit the PEP for approval. He’ll have to get acceptance for what gets submitted from the various co-authors, or reduce the list of authors to reflect the people who do support the submitted PEP.

The decision will be made solely on the basis of what gets submitted. And if nothing gets submitted, nothing gets approved.

One of the key features of the PEP process is that at some point, the PEP authors make a unilateral decision that the PEP is good to go, and submit it. The decision on the PEP has to take into account whether the PEP accurately addresses community comments, but it’s absolutely acceptable for a PEP author to say "there was a lot of discussion between X and Y, but ultimately I chose X and this is why"². The PEP delegate then decides, and sometimes that means accepting something that didn’t achieve consensus. That’s fine, it’s how we avoid paralysis on difficult decisions.

There is, of course, another option. One group of people could submit a PEP that says “PEP 508 strings” and another group submit a PEP saying “exploded format”. The decision then goes to me as to which to approve³.

To be clear, even the option to not include dependencies needs some significant work. It would weaken the PEP significantly (in my view) if it simply stated that dependencies were omitted from the PEP “because we couldn’t reach consensus”. Some things that would need to be covered, for example:

  • The PEP would need to explicitly say that backends MUST provide a tool-specific means for projects to declare dependencies
  • The PEP would need updating to reflect the fact that it was covering all core metadata except Requires-Dist.
  • Would projects be required to state dynamic = ["dependencies"]? If not, what happens when we later introduce dependencies? Will projects suddenly have no dependencies (because they don’t specify the dependencies key, and don’t mention it in dynamic)?
  • Should the [project] table be versioned, to allow for dependencies to be added later?

How would such an A/B comparison work? Assuming you’re using the term in the way I understand it, you’d need to have two implementations of setuptools, one with PEP 508 dependencies and one with expanded tables. You’d need to split a sample of users in two, impartially, with one group getting the PEP 508 version, and the other group getting the expanded tables, and then you’d need to measure the effectiveness of each approach (whatever “effectiveness” means). And if you don’t do something as rigorous as that, what’s to stop people challenging the validity of the results you get? That’s even if we assume you get significantly different results - if the difference is small, we’re back to square one.

I understand the desire to break the deadlock by appealing to objective facts. But I really don’t think “objective facts” are something we can determine in this situation (at least not in a way that will allow us to conclusively decide the issue).

Maybe this debate just demonstrates that there is no correct answer here, and we shouldn’t be standardising this at all - leave tools able to make their own choices, and let them innovate and explore options freely. To be honest, I think the current version of the PEP is weak in this regard - it doesn’t present a strong argument for why we need a standard input format, and maybe that’s the real issue here.


¹ On that note, I’ll formally confirm here that I would like to be removed from the list of authors, so that I can take on the role of PEP delegate without a conflict of interest.
² Pun intended :wink:
³ I would expect anyone submitting a PEP to do so in good faith, that is, to accept the decision if their PEP gets rejected. So this isn’t just a way of escalating the stakes.

1 Like

I’ll also note that I’m not sure that an A/B test of the two systems in isolation would even satisfy me anyway, because for me (and I think for many others), a key element of the question is whether there will be one system for specifying dependencies (PEP 508) or two (PEP 508 + exploded TOML). I think we all agree that we can never go to a system that only uses exploded TOML because of the many places that do not specify dependencies in a TOML file.

So the question of “Which do you like better, exploded TOML or PEP 508?” misses the point compared to, “Which do you like better, exploded TOML in PEP 621 and PEP 508 everywhere else, or PEP 508 everywhere?”

This is just one of the many hitches that makes me think that gathering more data would not help much.

4 Likes

If people aren’t finding the motivation to standardize all of this compelling like I do then the PEP is effectively dead. And I’m not saying this to be bitter as that may be the learning we take away from this exercise. But if others don’t feel the same way I do about coming up with a singular way for common metadata to be specified then I should withdraw PEP 621 and leave it there more as a suggestion for others on how they could choose to structure how tools specify metadata in pyproject.toml for their build tool.

I think this also means that we are deciding as a community that we are standardizing not on the UX of packaging, but on what packaging produces (and APIs on how to trigger tools to produce those artifacts). Once again, that’s a lesson learned so this has not been wasted effort, but it does mean we are choosing to let tools do their own thing as long as what they produce works with other tools and that’s the touch point we are going to standardize on which is different from how other communities have chosen to do things.

2 Likes

Indeed. However, I think it is sufficient to make sure to express the “there will be a transition needed” when presenting this, and taking inputs on that front. Is there some reason that is not the case?

Hmm… I think I used the wrong term there (whoops!). What I was thinking was: clearly writing down what the exact formats for specifying the dependencies would be. We don’t have concensus on how the PEP-508-form or TOML-form for specifying these would look like (do we have table of name = "..." or a TOML array-of-strings?).

We have some examples of the PEP 508 format using a list of strings, while others have a tables-with-strings. No one has clearly stated what the exploded-table format would be, which has led to… uhm… suboptimal variants of the same being used in comparisions.

Then we can continue debating this, with a clear definition of what we’re debating about. :slight_smile:


As an aside, I also don’t see any good reasons to do this prototyping w/ setuptools.

While I’m not volunteering to do the prototyping myself right now, I’d personally use flit as the base for the prototyping and not setuptools. It’s a more modern codebase [citation needed] with fewer historical “quirks”, it already uses TOML and it would avoid the minefield that is https://github.com/pypa/setuptools/issues/1688.


Administrative note: I’ve gone into full-on PEP delegate mode at this point.

Yay?

There is, of course, another option. One group of people could submit a PEP that says “PEP 508 strings” and another group submit a PEP saying “exploded format”. The decision then goes to me as to which to approve³.

Given that the authors for this PEP don’t have concensus among themselves on this topic, I think this might be the way to go.

Which brings me to a PEP-process Question: Would it be OK to split out the dependency-related parts of this PEP? The other parts definitely have sufficient concensus among the authors and I’d like to preserve the list of authors to indicate that (including Paul as well).

I’m thinking of 2 separate PEPs (one w/ TOML tables, one w/ PEP 508) with PEP 621 deferring to whichever gets accepted. Basically, we’d require accepting PEP 621 + one-of(PEP XXX, PEP YYY) prior to the actual implementation/rollout of any of these changes. Post acceptance of PEP XXX, PEP 621 would get updated to add a historical note on why it defers to PEP XXX for the dependency specification.

This is a good example of the potential for hidden bias. Which tool you use will likely affect the audience you get to look at the proposals. And that will influence the results. I’m not saying you’re deliberately doing this, nor am I saying that using setuptools is better. Just that getting objective data is hard.

Initially, I was going to say “yes”, but the more I think about the administrative issues, the less happy I am. I think you’re putting too much emphasis on the author list here - the important idea here is community consensus, not a big list of authors. Most PEPs have only one author, and that’s no barrier to getting consensus. I can tell you that I won’t be interested in the author list when making a decision, if that helps :slight_smile:

I’d suggest developing the two proposals as just write-ups of the “dependencies” sections, and then just submitting two PEPs that are identical except for that section. It’s easy enough to do a diff to confirm no other changes got “sneaked in”.

The relevant “people” here are backend developers (setuptools, flit and poetry being the major ones here). I’m assuming they are motivated to standardise (i.e., whatever gets agreed and accepted, they will adopt) - otherwise this PEP is indeed dead¹.

My concerns about the motivation section are more about how it presents the change to other people. As (for example) a setuptools user who has no particular expectation of switching to another backend, the PEP doesn’t really tell me why I’m being asked to rewrite all of my configuration, or worse still, why I have to move some of my config to pyproject.toml, but leave the rest in setup.cfg.

This is why I just say the PEP is “weak” - it doesn’t need to act as a sales push for the new format, but it could do better at explaining the reasons to people in that sort of situation.

¹ My biggest worry is that this debate has been so contentious that backend developers won’t accept the decision on the PEP, and will simply ignore it and do their own thing with dependencies…

I’m glad this is getting standardized. I’d say, even if (worst case scenario) only setuptools uses it, it still has value. No need to split into 2 PEPs, there is no rush to finish it quickly (it could even stay a draft until toml is in the standard library, and the whole content of setup.cfg can be moved to pyproject.toml for example). Point is: PyPA should standardize what they do as much as possible, with input from outside and patience, this is how to “fix the Python packaging ecosystem”.

Hmm… maybe?

Honestly, why I suggested this is that, I don’t know who should be authors in the 2-almost-completely-same PEPs (eg: is everyone OK with being listed on both? if not, keeping track of that.), what variant should be in PEP 621 (“the original PEP”) and other similar questions.

To me, figuring out these details feels like more social overhead than “just” having PEP 621 defer to 2 PEPs that get written separately w/ separate author lists, sidestepping all of those issues. :slight_smile:

Further, I do have some anecdotal experience that regular Python devs do place a decent amount of weight on “who wrote the PEP” (i.e. noticed when talking to not-python-packaging-people that they do look at who wrote the PEP and that has some importance). Plus, I think it’s nice that we have a PEP author list that indicates who all collaborated on this.


Edit: If I were to go back in time and ask that question again, I’d say “would you be opposed to <what I proposed above>” since I’d like to do that unless you have major-ish concerns. :slight_smile:

I don’t think this is a terrible outcome. Certainly I care far more about sdists having standardised metadata than source repositories (and would vote for “identical to wheels plus a you’ll-have-to-build-for-this sentinel value”).

Everything in the source repository is UX, and we’re trying to do a lot of innovation upfront here, when it’s really not that bad to let the tools do it.

Maybe the right thing is to strip down the specified fields to the ones that are absolutely static (as static as the source commit), being name and homepage… is that it? Some of us have workflows with auto-generated license files, there’s dispute about authorship vs maintainership, and obviously dependencies are controversial.

I suspect if native compilation weren’t so hard we’d have settled on a single tool years ago, and would be discussing its interface rather than a spec. That’s where the more recent languages are at.

The second example within your parenthetical suggests how to do this. We have a PEP for the DSL format, and can include it by reference. Someone needs to write the equivalent of that PEP for the TOML version and get it accepted so we can include it by reference in 621 (and everywhere else that’ll need to be updated to avoid the proliferation of standarised formats myself and others are worried about).

1 Like

Let’s say that I wouldn’t reject the PEPs just because they were presented that way. But I’d have to review each PEP on its own merits, so it’s up to you to make sure they stand up to that :slight_smile:

But I’ll reiterate what I said before - either the PEP authors make a decision and submit one PEP, or multiple groups of people submit multiple PEPs and I decide. Submit too many PEPs with too many weird interactions, and I’ll just reject the lot.

It really isn’t my job as PEP delegate to tell you how to present the case - and I’m not too bothered about the details of the formal process, so do whatever you think explains your proposal best.

If you want a strong guide as to what I would find most persuasive, I’ll say this. Stop worrying about process, and about how to present the choice, and concentrate for now on getting an “exploded format” proposal that’s specific, documented, and agreeable to everyone who’s arguing for “exploded format”. Present a unified alternative. Stop worrying about persuading people who prefer PEP 508, and focus on clarifying what alternative you are suggesting. Once we all know what the two options are, then we can revisit the question of which is best for the purpose of PEP 621.

2 Likes