Packaging python RPMs

Recently I was working on a very specific task in the current project that I'm
working for Red Hat, the RHEL Lightspeed
ShellAI, this project is
relatively new but we wanted to start shipping development RPMs for our QE
friends to start playing around the tool and testing it in their pipeline.

I know my way around packaging and general python stuff, but man, I have to
tell you, this packaging task took me two entire days to get through. Let me
guide your through the details of the task very quickly.

TLDR; everything worked out at the end and this is the resulting PR:
https://github.com/rhel-lightspeed/shellai/pull/4

Details of the task

The project, ShellAI, is intended ot be shipped under RHEL 9 and the upcoming
RHEL 10. As a bonus target, we would like to get it running also on RHEL 8.

By the statement above, if you already worked with RHEL before, you already
guessed that the challenge will be the version of the dependencies that lives
in RHEL.

• RHEL 8 has Python 3.6
• RHEL 9 has Python 3.9
• and lastly, RHEL 10 has Python 3.12

We also would like to get development builds relatively frequently in order to
getting new features to be tested as we develop the tool.

For the development part, we would like to use
pdm to manage our dependencies and
builds. As we went through the taks we noticed that the pdm backend is not
shipped in the RHEL repositories, thus we went with default setuptools build
backend.

Since our system targets are "relatively new", we would like to modernize the
project and make sure that we are using new tools/structure and formats. For
that, we chose to do with a pyproject.toml, as it is generated via pdm init
when we bootstraped the proejct.

Problems with building the RPM

Initially, our idea was to use the most recent python features and project
structure, such as the pyproject.toml file instead of the legacy setup.py.
When you start a new project, everything is cool and new you get very excited
to use that stuff, the only problem is:

• They are very good for development process, but not for packaging.

Initially, when I began the task, I thought that we could use the new RPM
macros for build the project, since we are using pyproject.toml and pdm for
managing dependencies.

For that, the Fedora Documentation has a nice article called Python Packaging
Guidelines
where they go in details. While the guide covers almost every topic and case
you may need, even with a example
specfile.

With our main target being RHEL, we could imagine that following everything
from the guide would work as-is, right? No. The reason for that lies in the
versions shipped in the RHEL repositories. Even though that the new macros
pointed in the guide may work during the build, you won't be able to generate
the final RPM in the following targets:

• RHEL 8 will throw to you an error during the %generate_buildrequires, as the python3-setuptools version shipped in that release is super old and do not really recognize the new pyproject.toml format.
• RHEL 9 will be able to progress through most of the steps, but will fail %pyproject_wheel as it will build a package with the name UNKNOWN. This is happens because (again) the python3-setuptools shipped under RHEL 9 is old. It doesn't recognize most of the metadata that is generated by the pyproject.toml specf.

The solution

We had to create a legacy
setup.py
file in order to progress with the Python wheel builds, and to avoid data
duplication between the pyproject.toml and our legacy setup.py file, we
used tomllib, because of the
following reasons:

• The tomllib is available (through pypi and rpm packaging) in RHEL 8
• After Python 3.11, tomllib got bundled natively into the standard library

As you have seen above, we used tomllib to load the pyproject.toml file and
read the necessary fields and simply update our legacy setup.py. This way, we
are able to modify pyproject.toml and whenever we push a new build, we will
be able to keep consistency in our legacy setup.py as well.

Regarding the specfile, we had to go back and use what the documentation calls
“201x-era” Python packaging
guidelines.
Essentially, we are using the good old python setup.py build ... command
(through macros, obviously) to build the project.

That solution enabled us to keep consistency across the RHEL versions we want
to support, and, at the same time, keep using pdm and the shiny new features
we would like for development.