pyproject-rpm-macros/README.md

pyproject RPM macros

This is a provisional implementation of pyproject RPM macros for Fedora 30+.

These macros are useful for packaging Python projects that use the PEP 517 pyproject.toml file, which specifies the package's build dependencies (including the build system, such as setuptools, flit or poetry).

Usage

If your upstream sources include pyproject.toml and you want to use these macros, BuildRequire them:

BuildRequires: pyproject-rpm-macros

This will bring in python3-devel, so you don't need to require python3-devel explicitly.

In order to get automatic build dependencies on Fedora 31+, run %pyproject_buildrequires in the %generate_buildrequires section:

%generate_buildrequires
%pyproject_buildrequires

Only build dependencies according to PEP 517 and PEP 518 will be added. All other build dependencies (such as non-Python libraries or test dependencies) still need to be specified manually.

Then, build a wheel in %build with %pyproject_wheel:

%build
%pyproject_wheel

And install the wheel in %install with %pyproject_install:

%install
%pyproject_install

Adding run-time and test-time dependencies

To run tests in the %check section, the package's runtime dependencies often need to also be included as build requirements. If the project's build system supports the prepare-metadata-for-build-wheel hook, this can be done using the -r flag:

%generate_buildrequires
%pyproject_buildrequires -r

For projects that specify test requirements using an extra provide, these can be added using the -x flag. For example, if upstream suggests installing test dependencies with pip install mypackage[testing], the test deps would be generated by:

%generate_buildrequires
%pyproject_buildrequires -r -x testing

For projects that specify test requirements in their tox configuration, these can be added using the -t flag (default tox environment) or the -e flag followed by the tox environment. The default tox environment (such as py37 assuming the Fedora's Python version is 3.7) is available in the %{toxenv} macro. For example, if upstream suggests running the tests on Python 3.7 with tox -e py37, the test deps would be generated by:

%generate_buildrequires
%pyproject_buildrequires -t

If upstream uses a custom derived environment, such as py37-unit, use:

%pyproject_buildrequires -e %{toxenv}-unit

Or specify more environments if needed:

%pyproject_buildrequires -e %{toxenv}-unit,%{toxenv}-integration

The -e option redefines %{toxenv} for further reuse. Use %{default_toxenv} to get the default value.

Note that -t implies -r, because tox normally assumes the package is installed including all the runtime dependencies.

The -t/-e option uses tox-current-env's --print-deps-to-file behind the scenes.

Running tox based tests

In case you want to run the tests as specified in tox configuration, you can use the %tox macro:

%check
%tox

The macro:

• Always prepends $PATH with %{buildroot}%{_bindir}
• If not defined, sets $PYTHONPATH to %{buildroot}%{python3_sitearch}:%{buildroot}%{python3_sitelib}
• If not defined, sets $TOX_TESTENV_PASSENV to *
• Runs tox with -q (quiet), --recreate and --current-env (from tox-current-env) flags
• Implicitly uses the tox environment name stored in %{toxenv} - as overridden by %pyproject_buildrequires -t

By using the -e flag, you can use a different tox environment(s):

%check
%tox
%if %{with integration_test}
%tox -e %{default_toxenv}-integration
%endif

If you wish to provide custom tox flags or arguments, add them after --:

%tox -- --flag-for-tox

If you wish to pass custom posargs to tox, use another --:

%tox -- --flag-for-tox -- --flag-for-posargs

Or (note the two sequential --s):

%tox -- -- --flag-for-posargs

Warning: This macro assumes you have used %pyproject_buildrequires -t or -e in %generate_buildrequires. If not, you need to add:

BuildRequires: python3dist(tox-current-env)

Limitations

%pyproject_install currently installs all wheels in $PWD. We are working on a more explicit solution.

This macro changes shebang lines of every Python script in %{buildroot}%{_bindir} to #! %{__python3} %{py3_shbang_opt} (#! /usr/bin/python3 -s). We plan to preserve existing Python flags in shebangs, but the work is not yet finished.

Extras are currently ignored.

Some valid Python version specifiers are not supported.

The -x flag does not yet support multiple (comma-separated) extras.