Python package

A Python package provides support for processing a Python supported module.

LIBFOO_TYPE = 'python'

Only the build and installation phases are used when processing the sources for a Python package (i.e. no configuration stage is invoked). The LIBFOO_PYTHON_SETUP_TYPE configuration dictates which build approach is performed for a package. The installation stage for all Python packages uses the installer module. When a Python package is processed, it will use the same Python interpreter used by releng-tool.

Note

For environments where releng-tool has been installed using pipx, a user will need to install any required build backend desired using the pipx inject command. For example, packages requiring Flit can install the build backend for their isolated environment using:

pipx inject releng-tool flit-core

A developer can override what Python interpreter to use by configuring the LIBFOO_PYTHON_INTERPRETER option in a package:

LIBFOO_PYTHON_INTERPRETER = '/opt/my-custom-python-build/python'

The following sections outline configuration options are available for a Python package.

LIBFOO_BUILD_DEFS

Provides a means to pass definitions into the build process. This option can is defined as a dictionary of string pairs. This field is optional.

LIBFOO_BUILD_DEFS = {
    # adds "--option=value" to the command
    '--option': 'value',
}

LIBFOO_BUILD_ENV

Provides a means to pass environment variables into the build process. This option is defined as a dictionary with key-value pairs where the key is the environment name and the value is the environment variable’s value. This field is optional.

LIBFOO_BUILD_ENV = {
    'OPTION': 'VALUE',
}

LIBFOO_BUILD_OPTS

Provides a means to pass command line options into the build process. This option can be defined as a dictionary of string pairs or a list with strings – either way defined will generate argument values to include in the build event. This field is optional.

LIBFOO_BUILD_OPTS = {
    # adds "--option value" to the command
    '--option': 'value',
}

# (or)

LIBFOO_BUILD_OPTS = [
    # adds "--some-option" to the command
    '--some-option',
]

LIBFOO_ENV

Added in version 0.17.

Provides a means to pass environment variables into all stages for a package. This option is defined as a dictionary with key-value pairs where the key is the environment name and the value is the environment variable’s value. This field is optional.

LIBFOO_ENV = {
    'OPTION': 'VALUE',
}

LIBFOO_INSTALL_DEFS

Removed in version 2.0: No longer applicable as all Python packages are installed using the installer module.

LIBFOO_INSTALL_ENV

Removed in version 2.0: No longer applicable as all Python packages are installed using the installer module.

LIBFOO_INSTALL_OPTS

Removed in version 2.0: No longer applicable as all Python packages are installed using the installer module.

LIBFOO_PYTHON_DIST_PATH

Added in version 2.0.

When a Python package is built, it will scan the dist/ directory in package’s output directory for a wheel package. It is possible for some Python packages to configure their projects to output built wheels into an alternative path. If an alternative path is configured, releng-tool will fail to find and install the package.

This option informs releng-tool what container folder hosts the provided wheel package. For example, if the Python package configures itself to output into build/dist, the following configuration can be used:

LIBFOO_PYTHON_DIST_PATH = 'build/dist'

LIBFOO_PYTHON_INSTALLER_LAUNCHER_KIND

Added in version 2.0.

Defines the launcher-kind to build when generating any executable scripts defined in the Python package’s project configuration (pyproject.toml). By default, the launcher-kind is chosen based on the host platform building the package. Supported options are dictated by installer. Options may include:

• posix

• win-amd64

• win-arm64

• win-arm

• win-ia32

For example, to explicitly build POSIX executable scripts, the following configuration can be defined:

LIBFOO_PYTHON_INSTALLER_SCHEME = 'posix'

LIBFOO_PYTHON_INSTALLER_SCHEME

Added in version 2.0.

Defines the installation scheme used for Python packages. By default, releng-tool uses the following scheme entries:

Path	Installation directory
data	prefix
include	prefix/include/python
platinclude	prefix/include/python
platlib	prefix/lib/python
platstdlib	prefix/lib/python
purelib	prefix/lib/python
scripts	prefix/bin
stdlib	prefix/lib/python

A package can be configured with a scheme native to use the default install target based on the native system:

LIBFOO_PYTHON_INSTALLER_SCHEME = 'native'

Packages can also use schemes supported by Python’s sysconfig module. For example:

LIBFOO_PYTHON_INSTALLER_SCHEME = 'posix_prefix'

A package may also define a custom scheme:

LIBFOO_PYTHON_INSTALLER_SCHEME = {
    'data':        '',
    'include':     'include/python',
    'platinclude': 'include/python',
    'platlib':     'lib/python',
    'platstdlib':  'lib/python',
    'purelib':     'lib/python',
    'scripts':     'bin',
    'stdlib':      'lib/python',
}

LIBFOO_PYTHON_INTERPRETER

Defines a specific Python interpreter when processing the build and installation stages for a package. If not specified, the system’s Python interpreter will be used. This field is optional.

LIBFOO_PYTHON_INTERPRETER = '<path>'

LIBFOO_PYTHON_SETUP_TYPE

Added in version 0.13.

Changed in version 0.14: Support added for poetry.

Changed in version 2.0: Use of installer is required for all package types.

Deprecated since version 2.0: Support for distutils packages is deprecated.

The setup type will configure how a Python package is built and installed. The default setup type used for a Python package is a distutils package. It is recommended to always configure a setup type for a Python package. The following outlines available setup types in releng-tool:

Type	Value
Flit	flit
Hatch	hatch
PDM	pdm
PEP 517 build	pep517
Poetry	poetry
Setuptools	setuptools
distutils	distutils (default)

For example:

LIBFOO_PYTHON_SETUP_TYPE = 'setuptools'

Host environments are required to pre-install needed packages in their running Python environment to support setup types not available in a standard Python distribution. For example, if a PDM setup type is set, the host system will need to have pdm Python module installed on the system.

The installer module will be used to install packages to their destination folders. For Setuptools/distutils packages, ensure wheel is available to help build as packages will be built with bdist_wheel.