Should we switch to standards-based package builds?

[kandersolar]

This post is a brain dump of what I've learned about previous, current, and future best practice for python packaging. Nothing here is at all urgent as far as I'm aware, so feel free to bookmark this for a rainy day; I just wanted to lay it out while it's still fresh.

Evolution of the python packaging tools ecosystem

When you install a package via pip install ..., part of what's going on under the hood involves a distribution in the form of either an sdist or a bdist_wheel. We currently generate our sdist and bdist_wheel files (.tar.gz and .whl files on PyPI) using setuptools, the de facto standard in the python packaging community for many years now. setuptools, its particular interface (using either setup.py or setup.cfg), and the underlying distutils stdlib all have to maintain backwards compatibility with essentially the entire python ecosystem, making those projects difficult to maintain and extend as the needs of the python packaging community evolve. It's also difficult to switch away from setuptools to some other tool since pip only knows how to call setuptools.

Or at least that's what was claimed by PEP 517, the first in a sequence of Python Enhancement Proposals (PEPs) regarding standardization of a new backend-agnostic build interface for python packaging, where "backend" refers to any tool like setuptools that can turn a source tree into sdist and bdist_wheel distributions suitable to host on PyPI. I don't necessarily suggest reading them, but the most relevant PEPs to date are PEP 517, PEP 518, and PEP 621. The idea here is that rather than having pip run a build tool-specific command like python setup.py bdist_wheel to generate a wheel file, pip would instead look up the desired build tool in some static configuration file and activate that tool via a standardized interface. The configuration file defined in those PEPs is pyproject.toml.

Although setuptools used to be really the only reasonable option, the acceptance of those PEPs prompted several alternatives to come about, including in no particular order poetry, flit, enscons, hatch, pdm, and likely others I've not happened to hear about. I think all of these support the interface defined by those three PEPs (excepting poetry, which doesn't yet support PEP 621, see python-poetry/poetry#3332). Anyway the point is that setuptools is no longer the only practical option for building distributions, and in theory it's easy to switch between the alternatives so long as you use the standardized pyproject.toml and python -m build --sdist --wheel instead of the setuptools-specific python setup.py sdist bdist_wheel.

As of pypa/packaging.python.org#1031, the python packaging guide no longer mentions the setuptools-specific setup.py and setup.cfg files, instead sticking entirely to the standards-based interface and configuration described above. Furthermore, setuptools itself is also onboard with the new interface and pyproject.toml configuration (pypa/setuptools#3371 and pypa/setuptools#3214). So it seems like pyproject.toml is the future, and likely something we'll want or need to adopt at some point.

What does this mean for pvlib?

I see three things worth thinking about in light of the above info:

Should we change how we invoke setuptools, i.e. do we stop using python setup.py sdist bdist_wheel (keeping setup.py itself) and switch to python -m build --sdist --wheel? I think probably we should, there's little reason not to, plus it sets a good example for any projects that copy pvlib's setup (which is more than a few!). twoaxistracking already does this.

Should we change how we configure setuptools, i.e. do we switch from setup.py to pyproject.toml? I think there's basically no chance that our setup.py is going to stop working anytime soon, so there's no real rush to switch. I do think it's worth looking into switching at some point, but it might not even be possible to switch unless we dump the spa_c extension stuff (see this forum discussion). Note that pyproject.toml is evolving and gaining capabilities over time; if not today, I expect at some point it will be capable of doing what we need.

Should we change what backend we're using, i.e. do we switch from setuptools to one of the other backends like flit? I think until we're confident that pyproject.toml can do what we need, there's little point in considering alternative backends. And without a compelling reason to switch to another backend tool, I lean towards "don't fix what ain't broke" here.

[mdeceglie]

Last time I used pyproject.toml I was disappointed too learn that editable mode installs (pip install -e) didn't work. I haven't revisited the question to figure out if there is a solution, but it's something to consider. This is can be a big frustration for development.

[kandersolar]

Thanks for bringing that up @mdeceglie. I don't use editable installs myself so I had forgotten about this point. I think I remember seeing a workaround with a shim setup.py, but either way it seems like setuptools will support editable installs out of the box in the near future: https://discuss.python.org/t/help-testing-pep-660-support-in-setuptools/16904

[wholmgren]

I don't use editable installs myself so I had forgotten about this point.

Now I am dying to know what is your pvlib development workflow

[kandersolar]

https://xkcd.com/763/ and also https://xkcd.com/1172/ :P

[jules-ch]

Hello there, I think it's a good idea to switch to PEP517/518 based builds.
Most scientific python packages have switched to this.
It's pretty straight forward, the only bump into this road is the use of versionneer see : python-versioneer/python-versioneer#193

Pandas is commenting the build-backend of pyproject.toml for this reason : https://github.com/pandas-dev/pandas/blob/main/pyproject.toml

We can switch to setuptools-scm, matplotlib has made the switch : matplotlib/matplotlib#18971