New pybuild plugin for PEP-517 pyproject.toml projects
The Python world has developed new standards for building and
distributing modules. The previous approach of running setup.py has been
replaced by a build API described in PEP517 (and some associated
documents).
An increasing number of projects now use this approach to building -
there is no setup.py in the source package but instead a pyproject.toml
file that lists the build tools and build dependencies that are to be
used. In some cases, a vestigial setup.py is kept for compatibility, but
the upstream expects the package to be built without it.
With the upload of dh-python 5.20211213, we now have an *experimental*
plugin that should be able to build all pyproject.toml packages. The
plugin has been designed to feel as similar to the previous distutils
(setup.py) plugin as possible. To select this plugin:
- Remove any patches creating a workaround setup.py for the project
- Build-depend on `dh-python-pep517` as well as any build tools
specified by upstream in pyproject.toml (in build-system.requires)
such as python3-setuptools, flit, or python3-poetry-core
- debdiff or diffoscope the resulting deb to check that it isn't
missing anything / including things it shouldn't
You'll notice that the binary package contains a .dist-info directory,
rather than .egg-info. This is expected, and fulfils the same purpose
with a better-defined structure. Your package should include this
.dist-info directory if it provides a public Python module. As we expect
.dist-info to become more common, we have improved .dist-info parsing in
this dh-python upload. If you had to previously explicitly specify
binary package dependencies, you may find that you don't need to any
more. dh_python3 --depends-section=SECTION now supports dist-info extra
sections, too.
Since this is a new plugin and somewhat experimental, an explicit opt-in
is required. It is anticipated that this plugin will eventually replace
the distutils plugin in situations where both pyproject.toml and
setup.py exist as well as the specialized flit plugin that was included
in bullseye. This plugin has so far been tested against packages using
setuptools, scons, flit and poetry-core as build backends, and against
packages that are pure python and ones containing C extensions; however,
further testing and bug reports are most welcome ("reportbug dh-python";
discussion in #debian-python on irc.oftc.net).
For the curious, the plugin sequence is as follows
- build step: invokes the upstream build backend (using the
python3-build module) and unpacks the wheel created by the build
(using the python3-installer module) into the pybuild {build_dir}.
Scripts and entry points should be available after this stage.
- test step: runs just like the distutils plugin
- install step: copies the files into debian/tmp or debian/package
as requested by debhelper
Thanks to the many contributions that went into this work, in
particular Stuart Prescott, Stefano Rivera, and Scott Kitterman.
regards,
Debian Python People
Further reading:
PEP517 and related:
https://www.python.org/dev/peps/pep-0517/
https://www.python.org/dev/peps/pep-0518/
https://www.python.org/dev/peps/pep-0621/
pybuild documentation:
https://salsa.debian.org/python-team/tools/dh-python/-/blob/master/pybuild.rst
pybuild plugin:
https://salsa.debian.org/python-team/tools/dh-python/-/blob/master/dhpython/build/plugin_pep517.py
Reply to: