python-single-r1 — single-impl packages

The python-single-r1 eclass is used to install single-impl packages. It is probably the easiest eclass to use, and it is recommended over python-r1 whenever multi-impl support would add unnecessary complexity. However, for packages using distutils or a similar Python build system, distutils-r1 eclass should be used instead.

Eclass reference: python-single-r1.eclass(5)

Basic use for unconditional Python

The defining feature of this eclass is that it defines a pkg_setup phase. It normally calls python_setup function in order to determine the interpreter selected by user, and set the global environment appropriately.

This means that a most trivial package using an autotools-compatible build system along with unconditional dependency on Python could look like the following:

 # Copyright 1999-2024 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2

 EAPI=8

 PYTHON_COMPAT=( python3_{10..13} )

 inherit python-single-r1

 DESCRIPTION="Scripts to prepare and plot VOACAP propagation predictions"
 HOMEPAGE="https://www.qsl.net/h/hz1jw//pythonprop/"
 SRC_URI="mirror://sourceforge/${PN}/${P}.tar.gz"

 LICENSE="GPL-2+"
 SLOT="0"
 KEYWORDS="~amd64 ~x86"
 REQUIRED_USE="${PYTHON_REQUIRED_USE}"

 RDEPEND="
     ${PYTHON_DEPS}
     ...
 "
 BDEPEND="${RDEPEND}"

This ebuild demonstrates the absolute minimum working code. Only the four highlighted lines are specific to Python eclasses, plus the implicitly exported pkg_setup phase.

Dependencies

When depending on other Python packages, USE dependencies need to be declared in order to ensure that the dependencies would be built against the Python implementation used for the package. The exact dependency string depends on whether the target package is single-impl or multi-impl.

When depending on other single-impl packages, the eclass-defined ${PYTHON_SINGLE_USEDEP} variable can be used to inject the correct USE dependency:

RDEPEND="
    ...
    dev-python/basemap[${PYTHON_SINGLE_USEDEP}]
"

When depending on multi-impl packages, a more complex construct must be used. The python_gen_cond_dep generator function is used to copy the specified dependency template for all supported implementations, and substitute ${PYTHON_USEDEP} template inside it:

RDEPEND="
    ...
    $(python_gen_cond_dep '
        dev-python/matplotlib-python2[gtk2,${PYTHON_USEDEP}]
    ')
"

Please note that in this context, ${...} is used as a literal template substitution key, so it must be escaped to prevent bash from substituting it immediately. In the above example, single quotes are used for this purpose. When other variables are used, double quotes with explicit escapes have to be used:

RDEPEND="
    ...
    $(python_gen_cond_dep "
        dev-python/wxpython:${WX_GTK_VER}[\${PYTHON_USEDEP}]
    ")"

As demonstrated above, the USE dependency string can be combined with other USE dependencies. PYTHON_SINGLE_USEDEP can be used both inside and outside python_gen_cond_dep, while PYTHON_USEDEP only inside it.

Conditional Python use

The examples so far assumed that Python is used unconditionally. If Python support is conditional to a USE flag, appropriate USE conditionals need to be used in metadata variables, and pkg_setup needs to be rewritten to call the default implementation conditionally:

 # Copyright 1999-2024 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2

 EAPI=8

 PYTHON_COMPAT=( python3_{11..12} )

 inherit python-single-r1

 DESCRIPTION="Yet more Objects for (High Energy Physics) Data Analysis"
 HOMEPAGE="http://yoda.hepforge.org/"
 SRC_URI="http://www.hepforge.org/archive/${PN}/${P}.tar.bz2"

 LICENSE="GPL-2"
 SLOT="0/${PV}"
 KEYWORDS="~amd64 ~x86 ~amd64-linux ~x86-linux"
 IUSE="python root"
 REQUIRED_USE="
     python? ( ${PYTHON_REQUIRED_USE} )
     root? ( python )
 "

 RDEPEND="
     python? ( ${PYTHON_DEPS} )
     root? ( sci-physics/root:=[python=,${PYTHON_SINGLE_USEDEP}] )"
 DEPEND="${RDEPEND}
     python? (
         $(python_gen_cond_dep '
             dev-python/cython[${PYTHON_USEDEP}]
         ')
     )"

 pkg_setup() {
     use python && python-single-r1_pkg_setup
 }

 src_configure() {
     econf \
         $(use_enable python pyext) \
         $(use_enable root)
 }

A hybrid: build-time + conditional runtime

A fairly common pattern is for Python to be required unconditionally at build time but only conditionally at runtime. This happens e.g. when the package is calling some helper scripts at build time, and optionally installing Python bindings. In this case, the build time dependency is expressed unconditionally, and the runtime dependency is made USE-conditional:

 # Copyright 1999-2024 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2

 EAPI=8

 PYTHON_COMPAT=( python3_{10..13} )
 PYTHON_REQ_USE="threads(+)"

 inherit waf-utils python-single-r1

 DESCRIPTION="Samba talloc library"
 HOMEPAGE="https://talloc.samba.org/"
 SRC_URI="https://www.samba.org/ftp/${PN}/${P}.tar.gz"

 LICENSE="GPL-3 LGPL-3+ LGPL-2"
 SLOT="0"
 KEYWORDS="~alpha amd64 arm ~arm64 ~hppa ia64 ~m68k ~mips ppc ppc64 ~riscv ~s390 ~sh ~sparc x86 ~amd64-linux ~x86-linux ~x64-macos ~sparc-solaris ~x64-solaris"
 IUSE="+python"
 REQUIRED_USE="${PYTHON_REQUIRED_USE}"

 RDEPEND="
     ...
     python? ( ${PYTHON_DEPS} )
 "
 DEPEND="
     ${RDEPEND}
     ...
 "
 BDEPEND="
     ${PYTHON_DEPS}
     ...
 "

 WAF_BINARY="${S}/buildtools/bin/waf"

 src_configure() {
     local extra_opts=(
         $(usex python '' --disable-python)
     )
     waf-utils_src_configure "${extra_opts[@]}"
 }

Note that eclass-exported pkg_setup is used unconditionally here.

Multiple USE conditions

Finally, let’s give an example of a package where Python is needed for two independent conditions. To make it more complex, one of them applies to build time (tests) while the other to runtime (bindings).

 # Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2

 EAPI=8

 PYTHON_COMPAT=( python3_{10..13} )

 inherit cmake python-single-r1

 DESCRIPTION="Sound design and signal processing system for composition and performance"
 HOMEPAGE="https://csound.github.io/"
 SRC_URI="https://dev.gentoo.org/~fordfrog/distfiles/${P}-distributable.tar.xz"

 LICENSE="LGPL-2.1 doc? ( FDL-1.2+ )"
 SLOT="0"
 KEYWORDS="~amd64 ~x86"
 IUSE="python test"
 RESTRICT="!test? ( test )"
 REQUIRED_USE="
     python? ( ${PYTHON_REQUIRED_USE} )
     test? ( ${PYTHON_REQUIRED_USE} )"

 BDEPEND="
     python? ( dev-lang/swig )
     test? ( ${PYTHON_DEPS} )
 "
 RDEPEND="
     python? ( ${PYTHON_DEPS} )
 "

 pkg_setup() {
     if use python || use test ; then
         python-single-r1_pkg_setup
     fi
 }

 src_configure() {
     local mycmakeargs=(
         -DBUILD_PYTHON_INTERFACE=$(usex python)
         -DBUILD_PYTHON_OPCODES=$(usex python)
     )

     cmake_src_configure
 }

Please note that in general, the condition in pkg_setup must match the one in REQUIRED_USE, and that one is a superset of conditions used in dependencies.

Manual install

Some packages do not include Python files in their build systems, or do not install all of them. In this case, the necessary files can be installed via one of the installation helpers.

 # Copyright 1999-2020 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2

 EAPI=8

 PYTHON_COMPAT=( python3_{10..13} )

 inherit python-single-r1

 DESCRIPTION="Arabic dictionary based on the DICT protocol"
 HOMEPAGE="https://www.arabeyes.org/Duali"
 SRC_URI="mirror://sourceforge/arabeyes/${P}.tar.bz2"

 LICENSE="BSD"
 SLOT="0"
 KEYWORDS="~alpha amd64 ~hppa ~ia64 ~mips ~ppc ~sparc x86"
 REQUIRED_USE="${PYTHON_REQUIRED_USE}"

 DEPEND="${PYTHON_DEPS}"
 RDEPEND="${DEPEND}"

 src_install() {
     python_domodule pyduali
     python_doscript duali dict2db trans2arabic arabic2trans
 }