Sdists for pure-Python projects

I think the biggest problem is that there’s no consensus on what should be included in the first place. Everything needed to build the project is a minimum, obviously. Everything needed to run tests (locally) is often requested. Everything needed to build documentation is another common request. But going beyond that, there’s things like CI configuration files (e.g., the .github directory), VCS configuration (e.g., .gitignore), editor config (like .vscode).

Personally, I think that “everything in VCS” is a bad choice, because (a) it’s easy to get that by downloading from VCS (obviously!), and (b) it includes a bunch of stuff related to the maintainers’ workflow that probably won’t be of interest or value to consumers of the sdist (like CI, VCS, editor configuration). It’s convenient as a default for backends because it’s easy to define and implement, but we shouldn’t be making recommendations based on what’s easiest for us to implement, but on what’s best for the user.

I don’t think we need a PEP here, but I do think we need to get consensus and document the appropriate advice in the packaging guide.

One problem with all this, of course, is that identifying “what is needed to run the tests” (or to build the docs, or whatever) is impossible without some standards on how test suites or doc builds should be laid out, and how they should be executed. That’s something that frankly I don’t think is in scope for the packaging community - except in the trivial sense that everything is packaging if you’re trying to publish your project. So I suspect the best we can do is to make broad statements like “sdists should include everything needed to run your test suite locally”, combined with some examples of one or more common layouts. We’ll get people complaining “the documentation isn’t clear enough, there are too many options” again, but IMO we have to draw the line somewhere. Otherwise we’ll have to make an “official recommendation” between tox, nox, hatch, etc. for running your tests. And then we’ll never make any progress :slightly_frowning_face:

3 Likes