Welcome to the Python RPM Porting Guide

This document aims to guide you through the process of porting your Python 2 RPM package to Python 3.

Note

If you struggle with the porting of your package and would like help or more information, please contact us at the python-devel mailing list (also accessible through a web interface) and we will try to help you and/or improve the guide accordingly.

If you’ve spotted any errors, have any suggestions or think some section(s) could be expanded, please create an Issue or a Pull request on our GitHub.

Is your package ready to be ported?

First thing you need to figure out is if the software you’re packaging is ready to be packaged for Python 3.

Does upstream support Python 3?

Look upstream and try to find out if the software is released with Python 3 support. First look at the front page of the project, Python compatibility is oftentimes listed there. There is also a good chance the project will have this information listed on PyPI. If not, look at release notes or the changelog history. You can also look at issues and pull requests.

However, the important thing to note is that the Python 3 support needs to be released, not just committed in the version control system (git, mercurial,…).

Are the dependencies of your package ported to Python 3 for your distribution?

Before you start porting, it’s imperative that you check that all the dependencies of your package are also ported to Python 3 in the distribution you are packaging for (Fedora, CentOS, RHEL or any other RPM-based distribution).

You may encounter a situation where your software is Python 3 ready upstream, but it uses some dependencies that are packaged only for Python 2 in your distribution. In that case try to communicate with the maintainer of the needed package and try to motivate and/or help them with porting of the package.

What type of software are you packaging?

There are four distinct types of Python packages, each with different instructions for porting, so be mindful of which you chose.

In rare cases your package might not nicely fall into either of these categories. In that case use the relevant parts from multiple sections or contact us on the mailing list.

1. Applications that happen to be written in Python

The section for applications is for software where the user doesn’t care in which programming language it is written. For example, it doesn’t matter if it is written in Python 2 or 3 because the application should run the same.

Applications have to have an executable, which you can check by running dnf repoquery -l your-package-name | grep /usr/bin/.

If your package is not being imported by third-party projects (e.g. import some_module in a Python file), it is most likely an application.

Try running dnf repoquery --whatrequires your-package-name to see a list of packages that depend on yours. If there are none, your package is likely an application, because there would be little reason to package a module that nobody uses. However, if there are some packages that depend on yours, we cannot be sure if it’s an application-only package or not, as some of these packages might be depending on your application itself, instead of importing modules from your package.

See: Porting applications that happen to be written in Python

2. Python modules

If your package is being imported by third-party projects, but does not have any executables, you’re dealing with a Python module.

See: Porting Python modules

3. An application and a module in one package

Use this section if your package contains both a Python module, that is being imported by third-party projects, and also contains an application—an executable that doesn’t interact with Python code (it doesn’t even have to be programmed in Python).

See: Porting an application and a module in one package

4. Tools for programming in Python

This last section is for tools (executables) written in Python that themselves interact with Python code. If you need to package two versions of the executable, one for each major Python version, then this section is for you.

Examples: pip, pytest, nosetest.

See: Tools for programming in Python

Are you following the new Python package naming scheme?

If you have ported your package according to the guidance in previous sections, then it most certainly complies with the Python package naming guidelines. However, you might have done it before this guide came to life or even before the naming guidelines changed, which might mean that some name changes are required. This section is here to walk you through them.

See: New Python package naming scheme