Python Packaging Guidelines (201x-era)

In Fedora we have multiple Python runtimes, one for each supported major Python release. At this point that’s one for python3.x and one for python2.7. However the Python 2 stack will be removed from Fedora and is deprecated. Upstream support for the python2 interpreter officially ends in 2020. If a piece of software supports python3, it MUST be packaged for python3. Software using python2 MUST NOT be newly packaged into Fedora without FESCo exception.

For guidelines on maintaining already existing python2 packages, see the appendix.

On Fedora /usr/bin/python is, if it is installed, a symbolic link to /usr/bin/python3. It was a symbolic link to /usr/bin/python2 on previous releases.

Packages in Fedora MUST NOT use /usr/bin/python. Instead packages for Python 3 MUST use /usr/bin/python3 (even if upstream supports both Python 2 and 3). As a result of that /usr/bin/python (as well as /usr/bin/env python and similar) MUST NOT be used in shebang lines or as a dependency of a package. All uses of unversioned python executables in shebang lines will fail the build. These shebangs MUST be fixed (for example by using the %py3_shebang_fix macro in the spec file). If it is necessary to disable the checks, please see the information in Shebang lines.

All Python runtimes have a virtual provide for python(abi) = $MAJOR.$MINOR. For example, the Python 3.7 runtime package has:

Python modules using these runtimes should have a corresponding "Requires" line on the Python runtime that they are used with. This is done automatically for files below /usr/lib[^/]*/python${PYVER}

Mirroring the policy for regular packages, the Python-version-specific subpackages of your package MUST NOT be removed in a release branch of Fedora.

The source package for a Python library MUST be named with the python- prefix. A built package however must include the Python major version in the name, using the python3- prefix. This is accomplished by adding a subpackage. See example below.

This rule does not apply to applications.

The character + in names of built packages (i.e. non-SRPM) that include .dist-info or .egg-info directories is reserved for Python Extras and MUST NOT be used for any other purpose. The + character triggers the automatic dependency generator for extras. Replace any + signs in the upstream name with -, or omit them when at the beginning of the name. As an exception, + characters are permitted at the end of the name.

Packages building for Python 3 will need BuildRequires: python3-devel. Most of them will also need BuildRequires: python3-setuptools. When in doubt, inspect the setup.py file for setuptools import.

Packages MUST NOT have dependencies (either build-time or runtime) on packages named with the unversioned python- prefix. Dependencies on Python packages instead MUST use names beginning with python3-.

For any module foo intended to be used in Python 3 with import foo, the package that includes it should provide python3-foo. This is of course always the case if the subpackage is named python3-foo (as in the examples below). If the subpackage has some other name, then Provides: python3-foo should be added explicitly (via %py_provides python3-foo, see below).

When building a Python package, RPM looks for .dist-info and .egg-info files or directories in the %files sections of all packages. If one or more are found, RPM parses them to find the standardized name (i.e. dist name, name on PyPI) of the packaged software, and then automatically creates two Provides: tags in the following format:

The 3.Y is the Python version used (usually 3.6 and higher), and between the parentheses is the name of the software in a canonical format used by Python tools and services such as setuptools, pip and PyPI. The canonical name is obtained by switching the standardized name to lower case and converting all runs of non-alphanumeric characters to single “-” characters. Example: “The $$$ Tree” becomes “the-tree”.

When packaging software which is available from PyPI, you can make use of the %pypi_source macro. This macro accepts from zero to three arguments and evaluates to an appropriate URL for the source file on PyPI. The arguments are:

In most cases it is not necessary to specify any arguments.

The following macros are defined for you in all supported Fedora and EPEL releases:

During %install or when listing %files you can use the %{python3_sitearch} and %{python3_sitelib} macros to specify where the installed modules are to be found. For instance:

Use of the macros has several benefits:

A great amount of extension modules for Python (Python modules written in a compiled language such as C or C++) are written using the Cython language and compiler.

Majority of such packages contains the generated C (or C++) sources in the source tarball.

Tightening the general Fedora policy, packages MUST NOT use pre-generated Cython sources. They MUST be deleted in %prep and regenerated during the build.

Any exception to this rule should be considered a bootstrapping.

When packaging Python modules, several types of files are included:

The source files MUST be included in the same package as the byte compiled versions.

Packagers SHOULD NOT simply glob everything under the sitelib or sitearch directories. The following SHOULD NOT be used:

And packages MUST NOT include the top-level __pycache__ directory (see below).

Python will automatically try to byte compile files when it runs in order to speed up startup the next time it is run. These files are saved in files with the extension of .pyc (compiled Python). These files will be located inside a directory named __pycache__.

The .pyc files contain byte code that is portable across OSes. If you do not include them in your packages, Python will try (and generally fail) to create them when the user runs the program. If the system administrator runs the program, then the files will be successfully written, causing stray .pyc files which will not be removed when the package is removed. To prevent that the byte compiled files need to be compiled and included in the %files section. Normally, byte compilation is done for you by the brp-python-bytecompile script. This script runs after the %install section of the spec file has been processed and byte compiles any .py files that it finds in %{python3_sitelib} or %{python3_sitearch} (this recompilation puts the proper filesystem paths into the modules otherwise tracebacks would include the %{buildroot} in them).

You must include the .pyc files in your package. If the build process creates a __pycache__ directory in a subdirectory of %{python3_sitearch} or %{python3_sitelib}, you must also include all items in the __pycache__ directory. You MUST NOT include the directories %{python3_sitearch}/__pycache__ or %{python3_sitelib}/__pycache__ because they are already owned by the python3-libs package.

All that you need to do is include the files in the %files section (replacing %{python3_sitelib} with the appropriate macro for your package):

or, if the Python code installs directly into %{python3_sitelib}, use the %pycached macro to include the bytecode cache files:

That evaluates roughly to

The following is a very simple spec file for a Python module.

The following briefly summarizes the guidelines for reviewers to go over: