PyPA mechanism for making "official recommendations"

Packaging
1

Following on from this point, I think one of the areas where users look to the PyPA for guidance, but don’t really get it, is around “best practices” - how to set up a new project, where to put files, how to set up a workflow, etc. The Packaging User Guide tries to give some help here, but it frankly isn’t opinionated enough, so people remain confused.

The problem is that the PyPA doesn’t actually have a good mechanism for deciding on, and endorsing, best practices. Our only real decision making process (outside of the PEP-delegate mechanism for standards) is consensus - and project workflow is a very personal choice, and as such, consensus is almost impossible to achieve. Getting a consensus on tox vs nox, or pytest vs unittest, or sphinx vs mkdocs, is likely to spawn huge discussion threads and even then, ultimately fail. Newer workflow tools like hatch, PDM and poetry would be even worse (and I don’t even want to think about discussions on whether to recommend conda or not :slightly_frowning_face:)

Do we want to somehow set up a process for developing, documenting, and maintaining a set of best practices? Maybe by delegating the authority to make choices to a small group of people (the PUG editors seem an obvious choice[1]) and then accepting their decisions (even if that means they choose someone else’s project rather than yours as the standard!). I would expect such a group to avoid public discussions on a lot of topics, simply because extended debates are counter-productive, and that’s perfectly fine, in my view. That’s what giving them the authority means.

Alternatively, does anyone have a different suggestion for how to improve our ability to provide best practice advice?

To be explicit, I do not mean this topic to be a debate on best practices, and I’d ask that any such comments get moved to a different thread rather than derailling the main question here, which is intended to be a PyPA governance question.

  1. Although I’d completely understand if they didn’t want to volunteer, as whoever does this is pretty much bound to get a certain level of hostility directed their way :slightly_frowning_face: ↩︎

6 Likes
2

I think this would be beneficial overall, yes. I don’t have opinions on what shape that process takes, at the moment.

1 Like
3

Not sure what “Sphinx vs mkdocs” has to do with packaging? I wouldn’t make the PyPA try to give recommendation on documentation tools.

4

Opinionated guidance on best practices is very useful for the average user, so from that perspective - yes.

On the other hand:

  • some of the contentious topics listed by @pf_moore are more about opinions than best practices,
  • it seems fairly clear that some best practices are different depending on what type of user or type of development is being addressed. A web dev who mostly works with a pure Python stack and considers themselves a developer needs different guidance than a scientist working with a stack of heavy dependencies.

So I’d say by all means write a (not the) best practices guide, and it’s fine if that would be in the Python Packaging User Guide. I’d suggest linking from there to a few other guides that are well-written and that may address a subsection of all Python users. E.g., the PyOpenSci packaging guide that @lwasser is developing/curating.

This is a good example. This is not to start a discussion, but to illustrate the problem of different user types: the answer here for scientific users is “neither” (envs per development task or running tests for multiple Python versions is too heavy-duty - there’s multiple other issues that I won’t go into here).

4 Likes
5

To be clear, I picked those examples as cases where I’m pretty sure we can’t get consensus, but where I know we’ve had people asking that the PyPA sample project include configuration for those things (which implies a desire for the PyPA to “take a stance”).

Beyond that, what you (and @jeanas) are saying is drifting into “discussing best practices”, which I explicitly don’t want to get into here.

The question remains, do we want a means for the PyPA to “have official opinions” on matters like package structure, workflow, etc? I’m hearing cautious approval so far. Assuming we do, then I have no idea what such a means would look like (the best I can come up with is the “delegated working party” idea I mentioned originally, and I’m not in love with that).

Such a mechanism could also be used to address the question “what is the scope of the PyPA’s authority” - which is another question I don’t think we have a workable consensus on (or if we do, we’ve been very ineffective at communicating it :slightly_smiling_face:), and which might answer questions like to what extent workflow automation tools like tox, nox, hatch, PDM and poetry are within the PyPA’s scope[1].

  1. Yes, I deliberately put those tools together to illustrate that the question isn’t clear cut! ↩︎

6

Another angle to this is we might want to move away from an open tent model, tweaking the requirements for being a PyPA project and amending the member projects while keeping that in mind.

2 Likes
7

There would leave several open questions still, but I think this would be a good idea.

8

If there’s reluctance to converge on one packaging toolchain and make it the de jure standard, how would opinionated best practises not create a de facto standard that ends up being the same thing?

2 Likes
9

I don’t follow. The problem here is that (as far as we can determine) users want the PyPA to endorse a standard workflow/project structure, but the PyPA has no means to do so if we can’t get consensus. The whole point here is to get “the same thing” in spite of not having consensus.

Of course, it’s a valid question as to whether we should bless a particular workflow/project structure if there’s no consensus. But given that we don’t even have a mechanism to (formally) say that we won’t make a recommendation, we’re in a position where users remain confused and frustrated, and we don’t have a way to clarify things.

Hence my suggestion that we need to create such a mechanism.

1 Like
10

Exactly, most users want there to be no packaging tools, no environment managers, and so on, it should all just be a built-in “python thing” that no one has to think twice about. Yet we have e.g. all of flit, hatch, poetry, etc. and nothing is given any special treatment. It seemed to me a deviation from this hands-off approach to make opinionated suggestions what “best practises” are.

(Personally, I think its overdue to just pick one tool for each job and make it the standard. Leave it open for people to e.g. choose different build backend, but if I don’t want to choose one, don’t make me choose one.)

1 Like
11

It could be useful. In practice, I’m unsure how much of the problem would be solved just by having a recommendation and how much depends on the details of what that recommendation is.

One of the biggest questions I would have is whether a PyPA-based recommendation would actually be willing to consider recommending non-PyPA solutions as better than PyPA ones.

Another practical issue that seems to be lurking in some of these discussions is that I think there are not many people with comprehensive familiarity with a wide range of tools. In discussions about build backends and installers we see input from different people talking about different tools, and most are to some degree comparing one or two other tools with pip. But for a thoroughgoing recommendation it would undoubtedly be better to comprehensively compare everything with everything else, which would be quite a bit of work.

Personally I am less interested in what best practices are now than in what we would want best practices to be like, and then making progress towards making that a reality.

2 Likes
12

Just a reminder, this topic is not about discussing what any “best practices” might be, it’s about discussing whether we want the PyPA as an organisation to have a process for making such recommendations. Once we have such a process, then we can talk about whether we should use it for recommending particular project layouts/workflows. And only after we’ve done that will we need to discuss what those recommendations might be. One step at a time.

13

Okay, so in light of what you said here, let me just restate in a different way something I have said in other ways repeatedly on these threads (and that I think at a least a couple others have said in less forceful ways):

No, there is no use in PyPA doing that. There is no use in PyPA doing anything whatsoever if PyPA does not control the packaging components of the official Python.org installations of Python and the packaging documentation on Python.org. What matters is not who does it, but what is done, and what needs to be done is fixing the packaging tools available from Python.org, and/or the official documentation on Python.org[1]. If PyPA cannot do that, then there is no use in it recommending anything. Recommendations from PyPA that do not affect the official documentation on Python.org are no more useful than yet another “here’s what I think about packaging” post on someone’s blog.

End users do not care about PyPA. Any bureaucratic distinction between Python and PyPA or other organizations is immaterial to end users. When end users install Python, they consider, and should rightly consider, themselves to be using Python, period, and believe, and should rightly believe, that they can find accurate and comprehensive documentation for using Python on Python.org. And, in general, they can! But not for packaging.

  1. which is a stated goal ↩︎

14

Yes. I think Python users want to see recommendations about best practices for tooling and workflows for Python packaging. Consistent, clear and all centralized in one place (as opposed to the current status which is full of inconsistent, outdated, misguided, ill-informed advice spread all over the internet in blogs, videos, StackOverflow, etc.).

And yes, in my opinion, PyPA seems to be in a good and legitimate position to be the organization to do that.
If possible by including the “scientific Python” communities [1] and hopefully closing that gap, even if this reunification happens in small steps over a longer period of time. But if this does not happen, I would not see it as a failure either, some different communities crystallized naturally, maybe it would be too violent and doomed to fail to try and go against this. As long as we are only talking about recommendations and best practices, it seems perfectly fine to have more than one school of thought each addressing a specific set of relatively unique needs. This is the work on the standards that will take care of keeping things compatible between communities.

If a more formal process is necessary to get there then let’s have it. And there is relatively good momentum right now, let’s take advantage of it.
On the other hand, I also feel like there is a lot of very low-hanging fruit and very uncontroversial decisions that can be handled very promptly without waiting for a formal process to be in place. I do not know how heavy such a process could be but I am a bit worried putting a process in place would take too long and some crucial momentum and motivation might get lost here.

[1] Probably not the best terminology choice, I know it has a lot more nuances than just PyPA on one side and “scientific Python” on the other, but hopefully you know what I mean.

4 Likes
15

That’s a very good point. I think the practical problem here (as opposed to the procedural one that my post was flagging) is that no-one is currently doing anything about that low-hanging fruit. In the absence of anything more formal, anyone in the community can state that there is consensus over X and create whatever PRs or PEPs they choose based on that. But as long as everyone is assuming that “the PyPA” should be the ones taking action, nothing happens - because there is no “PyPA” in that sense currently, just a collection of individuals[1].

  1. The PyPA is sort of quantum - sometimes it acts like an organisation, other times it acts like a herd of cats :slightly_smiling_face: ↩︎

2 Likes
16

We do have PyPA members who are also Python Core Developers, and “own” those pieces.

So, we do have control over that.

packaging.python.org is maintained by the PyPA. The distutils documentation on docs.python.org is also something that we can update relatively easily, in terms of the mechanics of the change.

Right, and the proposal is the PyPA would do this, and that we figure out what in a latter stage if we have agreement on the first step.

I don’t understand this because I’m reading this as a contradiction. If users don’t care about the separation, then they would also not care about the issues caused by the separation. And then you describe exactly why the issues matter to users!

I appreciate what you’re trying to say, don’t get me wrong – but I’m also reading that as having internal contradictions. I’d love to have my cake and eat it too. I can’t; no matter how much I want to.

The thing is we can do the things that you’ve set as preconditions for this. So, yes, we are positioned uniquely to make these recommendations and to make them stick, if we do things well-enough.

The issue is that we have not been able to do that because we don’t have a mechanism to do so. And, to give that process legitimacy beyond just “X likes it”. And, whether people think we should be doing this is literally what this discussion is about!

1 Like
17

I don’t think we want “official” best practices at all, for all the same reasons others have said, but in my own words: those “best practices” will be wrong enough of the time to cause problems, and because they look official, users will assume that the problem is with themselves and that they ought to be using a different language/ecosystem.

We’ve already seen plenty of examples given here where the proposed structure doesn’t even include the best practice for some of our communities, so it seems incredibly unlikely that we’d get through this without officially alienating some (I suspect high) proportion of our users.

The other aspect is how quickly these things go out of date. In a really significant way, the standard library was best practice at one point. Now we believe it no longer is, which to me is evidence that best practices need to be kept up to date

I would much prefer to see a project that collates suggested workflows from anyone - including strong opinions about which tools to use! - and lets users vote/comment on them or propose alternatives. This could be as simple as a GitHub discussion board, frankly. Add in a requirement that the author list the pros/cons of their own workflow, and a description of what they use it for, and we’re at least getting close to a resource that any Python user can look at to find someone similar to themselves and what worked for them.

Once upon a time, distutils and unittest were best practice. Updating that recommendation continues to be a real pain. Please let’s not repeat that.

4 Likes
18

That is a risk indeed. Maybe the first step would be to avoid the term “best practices” entirely (which sounds way too definitive) in favor of something like “PyPA recommendations”, no need to promise things that can not be delivered. The language of such recommendations should make it immediately clear that it does not aim to cover all use cases. I doubt anyone can honestly claim to know what the best practice for someone else’s use case should be without knowing their use case.

[Maybe it is worth changing the title of this discussion thread?]

2 Likes
19

Agreed, it was a bad choice of words on my part. Also, the motivating case for this was recommending that projects use a virtual environment called .venv located in the project directory, which is (IMO) far less controversial than tool recommendations. Again, I was probably mistaken in introducing that possibility, although I did want to make the point that users are asking for such recommendations, so “consensus is sufficient” genuinely doesn’t work (unless you accept that simply not saying anything is acceptable, which may be true as @steve.dower suggests, but it does nothing to help users wanting to know what the PyPA says :slightly_frowning_face:).

Done.

1 Like
20

That is a possibility - and it could be a PyPA project (and linked from packaging.python.org) if we want to bless it as the “PyPA position”. But as usual, the question is, who’s going to do that? It can be a PyPA project if the maintainers want it to be, but it still needs maintainers in the first place!