Switch to setup.cfg for metadata?

[pfmoore]

Looking at the setuptools documentation, it seems that it's now possible to put project's metadata in setup.cfg (see http://setuptools.readthedocs.io/en/latest/setuptools.html#configuring-setup-using-setup-cfg-files). I don't know when this was introduced, but would it make sense to switch to this approach as the recommended method?

@jaraco Any comments? I don't know when this ability was introduced to setuptools, but it looks really easy to use, and (as far as I'm aware) didn't get as much publicity as maybe it should have...?

[jaraco]

It happened in v30.3.0. I was cautious to announce it because it's the kind of feature that everyone would want to adopt, but would not be available until most deployments had a late version of setuptools available. As we're 9 months in now, perhaps it's widespread enough to recommend it in a project such as this one. I personally haven't used it, so I'd like to hear from others who have before recommending it.

[pfmoore]

OK, cool. Over on the PUG issue, @dstufft mentioned possible problems with RTD (I don't know the details). And it will of course cause issues for people building from source with older versions of setuptools - that's always going to be a problem with new setuptools features, but I have no feel for upgrade rates.

[pfmoore]

See the discussion in pypa/packaging.python.org#378 - basically I've been persuaded that using setup.cfg probably isn't something we should be recommending in the PUG at this point.

[Gadgetoid]

Has the wisdom arrived at in these threads changed over the last two years? Do we have any idea what the prevelance of versions >= 30.3.0 might be?

I'm very keen to drop any reference to distutils in my packages, include install_requires=['setuptools>=30.3.0'] and steam forward with migrating metadata into setup.cfg. I don't necessarily have the same problem with random users doing an install from sdist distributions since I target the Raspberry Pi platform almost exclusively, but I've nonetheless found what appears to be a sensible trap for this edge-case.

It also looks like pip is capable of parsing install_requires before executing the package install and invoking setuptools (if and when this even happens during a .whl install I'm not totally sure) so adding setuptools to install_requires appears to me to be a sensible approach that will slowly march the userbase forward.

Here's the pattern that I've arrived at: https://github.com/pimoroni/boilerplate-python/blob/master/library/setup.py

[pfmoore]

@Gadgetoid You can do this in your own project without issues. The constraints on an "official recommendation" like the PyPA sample project are significantly different than those that apply to individual user projects.

Having said that, I think this could probably do with being revisited for sampleproject. 2 years is plenty of time for the relevant setuptools features to become mainstream.

[Gadgetoid]

@pfmoore thank you. I'm keenly aware that "just because I can, doesn't mean I should" and want to at least make somewhat informed decisions (since I'm shipping dozens of libraries and perhaps indirectly influencing how beginners might approach writing their own), so your feedback is appreciated.

[Ivoz]

In general, sampleproject is looking to make recommendations when they are

• Uncontroversial
• Pretty much the one-true-way-to-do-X (e.g, not making a advertisement for one testing framework over another, or poetry over pipenv, etc; at least while there is healthy competition amongst approaches which pypa doesn't want to bias)
• Safe and will work for the vast vast majority of users with their existing software
• Not subject to change in the near future

So that a beginner can copy-paste what's here, edit specifics to their project, and be practically 100% sure it will work. Since there are many warts and alternatives in different parts of the packaging ecosystem, we tend to want to stray away from parts where we might recommend X but then Y becomes the better things N months in the future. Play it safe.

One small issue I've always had with setup.cfg I've always had is that originally it was not intended to be a distributed-with-the-package file at all, but a file you could add into to a source distribution you'd downloaded to customise how it built1 (e.g on a per-system basis - look for libraries here on my particular computer). Then IIRC pbr decided it could take over that functionality to be used as a packaging description file (contradicting the above functionality) without any consultation. And then it's been dragged in that direction ever since, but without ever bothering to definitely resolve this issue.

Small note from the pyproject.toml PEP discussing it as well

[pfmoore]

Ironically, now that PEP 517 is available, using setuptools at all is no longer as uncontroversial as it once was - for simple projects flit is arguably a better choice.

IMO the strongest argument for not switching sampleproject to use setup.cfg is that so few setuptools-using projects have actually done so already. In my view sampleproject should be following trends, not setting them.

[di]

Given PEP 621, we might want to skip setup.cfg and move towards pyproject.toml as described in that PEP instead.

[bhrutledge]

Reviving this, since the packaging tutorial (which references this repo) now recommends setup.cfg. Would the maintainers accept a PR for this? There's already #57 and #96, but I'm guessing those need some work.

Given PEP 621, we might want to skip setup.cfg and move towards pyproject.toml as described in that PEP instead.

Looks like that's not supported in setuptools (yet): pypa/setuptools#2671

According to this blog post it seems like you can have the metadata in the pyproject.toml file itself without any issues.

@jonathan-s I don't think the pyproject.toml in that blog post is valid; it seems to be mixing Poetry-style metadata and dependencies configuration with a setuptools build-system.

[di]

I know it's been more than a year, but I think my previous comment still stands: if we're going to standardize around PEP 621 (and we should) then let's not introduce extra churn here by changing the recommendation twice.

[pfmoore]

Generally I'm +1 on that, but setuptools apparently has resource issues which mean it might be some time before they have PEP 621 support, and recommending an approach that's at least declarative in the interim would be an improvement. (The alternative is to switch to flit as the recommended "beginner" approach, although the way it uses VCS metadata might be astumbling block for new users).

[demberto]

Fast forward to 2022, setuptools 61.0.0 actually has experimental support for project metadata in pyproject.toml w.r.t PEP621

[pfmoore]

The packaging tutorial authors are currently debating how to incorporate PEP 621 in the docs. It's possible that rather than simply using setuptools with pyproject.toml, they may decide to use a different backend altogether (flit or hatch, for example).

As the main purpose of this project is to be an example of what the packaging guide recommends, we should wait for their decision and follow that.

[bhrutledge]

See Removing setup.cfg and setup.py from the packaging tutorial - Packaging - Discussions on Python.org

[di]

See also #166, which is a draft PR implementing this repo's move to pyproject.toml, blocked on setuptools supporting editable installs (and/or a decision on a different backend to recommend).