Skip to main content

Python Packaging Guidelines

This document describes the Python module packaging guidelines for openRuyi. For the relevant build system, please refer to Pyproject.

Naming​

Packages for Python libraries must use the python- prefix.

For the package name (DISTNAME), use the name the upstream project uses on PyPI. You must add the following macro at the top of the spec file:

%global srcname DISTNAME

In short, the srcname macro represents the project’s name on PyPI. The name must also follow the normalized name rules in PEP 503: use lowercase letters, and replace _ and . with -. For example, if the upstream project name is aiohttp_socks, use aiohttp-socks as the package name and srcname.

Source URL​

Whenever possible, you should use the source archive published by the upstream project on PyPI as the source URL, except for packages that do not provide source archives on PyPI or are otherwise unavailable there. For example, python-pyperclip:

%global srcname pyperclip

Source0:        https://files.pythonhosted.org/packages/source/p/%{srcname}/%{srcname}-%{version}.tar.gz

If the package name (DISTNAME) differs from the name used in the download URL, you should define the pypi_name macro at the top of the spec file. For example, python-aiohttp-socks:

%global srcname aiohttp-socks
%global pypi_name aiohttp_socks

Source0:        https://files.pythonhosted.org/packages/source/a/%{pypi_name}/%{pypi_name}-%{version}.tar.gz
Warning

The pypi_name macro specifies the filename of the project’s downloadable source archive on PyPI; It does not represent the actual project name on PyPI. For that purpose, you should use the srcname macro.

Another example is python-pytest-rerunfailures:

%global srcname pytest-rerunfailures
%global pypi_name pytest_rerunfailures

Source0:        https://files.pythonhosted.org/packages/source/p/%{srcname}/%{pypi_name}-%{version}.tar.gz

the pypi_name macro specifies the filename of the project’s downloadable source archive on PyPI.

Dependencies​

Packages should not declare an explicit runtime dependency on python3, because the following dependencies are added automatically in the corresponding cases:

  • When you install files into %{python3_sitelib} or %{python3_sitearch}, the build system automatically generates a dependency on python(abi) = 3.X.

  • If the package contains executable Python scripts, the build system automatically generates a dependency on /usr/bin/python3.

BuildRequires: pkgconfig(python3)​

Every package that uses Python and/or installs Python modules must include BuildRequires: pkgconfig(python3) in the spec file, even if the build process does not explicitly invoke Python.

Provides: python3-DISTNAME​

Since openRuyi does not split python3 into a separate subpackage, but instead provides it directly from the main package, if the package is architecture-independent, you should add the following entries to the spec file:

Provides:       python3-DISTNAME = %{version}-%{release}
%python_provide python3-DISTNAME

If the package is architecture-dependent, you should add the following entries to the spec file instead:

Provides:       python3-%{srcname} = %{version}-%{release}
Provides:       python3-%{srcname}%{?_isa} = %{version}-%{release}
%python_provide python3-%{srcname}

Here, you can replace DISTNAME with the previously defined macro, which is typically %{srcname}.

RPM Macros for Python Modules​

This section lists several commonly used RPM macros for packaging Python modules.

Build Macros​

%pyproject_buildrequires​

Use this macro in the %generate_buildrequires section of the spec file to generate the package's BuildRequires.

%pyproject_wheel​

Use this macro to build the package. In most cases, it is the only macro you need in the %build section. It requires the BuildRequires generated by %pyproject_buildrequires.

%pyproject_install​

Use this macro to install packages built by %pyproject_wheel builds. It also requires the BuildRequires generated by %pyproject_buildrequires.

%pyproject_save_files​

Use this macro to generate the file list corresponding to the specified importable modules and save it as %{pyproject_files}. The generated list does not include README files. If the package metadata declares license files, the list includes them.

%pyproject_check_import​

Use this macro to read the list of importable Python modules generated by %pyproject_save_files. Maintainers can use it as a smoke test to quickly detect issues such as missing runtime dependencies, incorrect installation paths, or failures when loading extension modules.

%pyproject_files​

This macro expands to the path of the file list written by %pyproject_save_files. Example usage:

%files -n python-DISTNAME -f %{pyproject_files}