Discussion: support for pyproject.toml configuration

Over the last few months, I’ve been using setup.cfg more, and I find the syntax and types and such to be super counter-intuitive. I don’t find TOML to be a breeze per se, but it’s at least a lot clearer to me how to specify a string, a list, etc. We also hear a lot of cries to move towards supporting pyproject.toml as the “one file” for setup configuration, in favor of setup.cfg. I’m not terribly opposed to this, but I want to open up the discussion for a few options:

1. Add pyproject.toml as the one true way to do declarative builds, moving all setuptools configuration over there and deprecating setup.cfg (partially what is discussed in #1160, and if we decide on that option we can move over to that issue).
2. Add pyproject.toml as a second supported way to do a declarative configuration, alongside setup.cfg.
3. Stay the course with setup.cfg indefinitely.

I am deeply concerned with the large amount of churn that we’re introducing into the Python packaging space, so I don’t want to make a lot of changes for the sake of changes, but I do think that at least having the option to use a pyproject.toml would be a real benefit, so I’m basically in favor of option 2.

I think the biggest downside of option 2 is that it means maintaining, testing and documenting three separate locations for all of our options - how to do it in setup.cfg, how to do it in pyproject.toml, and how to do it in setup.py. I think the hard part is going from 1 way to do everything to 2 ways. Our documentation is a mess anyway, but my beautiful vision for the future is that all our examples have “tabs” that allow you to toggle them between setup.cfg and setup.py. Adding a pyproject.toml in there would probably not be the worst thing.

[nschloe]

FWIW, PEP 621 for Storing project metadata in pyproject.toml has been provisionally accepted.

[jaraco]

I’d prefer option 1. I imagine during the deprecation period that the setup.cfg documentation could be removed, but a permalink to the old documentation made available for projects still relying on that technique.

One way to ease the transition could be for the setup.cfg code to generate a .toml file and consume then have the pyproject.toml consumer just load both files. That way, a project seeking to transition would only need to do one build, manually merge the two .toml files, and delete setup.cfg.

My second choice would be option 3. I’d really like to avoid supporting multiple formats that do essentially the same thing.

Another consideration I’d like to mention is the proposal I only recently started fleshing out in pypa/packaging-problems#248. Such an approach would be yet another declarative format. However, this proposed approach would enable project developers to supply metadata decoratively in the canonical format (or in a format suitable for the requisite build steps). If such an approach is deemed viable and comes to fruition, the value in migrating to pyproject.toml may prove small. I suggest postponing this transition at least until that more ambitious proposal is disposed or reaches fruition.