Python API of sp-variant

Here you can find the API reference for the Python implementation of the sp-variant tool (see Using sp-variant).

Introduction

The sp_variant.variant Python module exports several constants and functions, among them:

detect_variant() - return an object describing the detected distribution
get_variant() - get an object describing the specified distribution
get_by_alias() - same, but specify the StorPool builder alias for the distribution
get_all_variants() - get objects describing all supported distributions
command_run() - run a distribution-specific command

There is also a Rust API; for details, see the Rust crate page.

Variant

Build variant definitions and commands.

class spvariantapi.variant.Config(args: list[str] | None = None, command: str | None = None, noop: bool = False, repodir: pathlib.Path | None = None, repotype: RepoType = RepoType(name='contrib', extension='', url='https://repo.storpool.com/public/'), verbose: bool = False)

Runtime configuration for the sp-variant library functions.

args: list[str] | None = None: Additional arguments passed to the command.

command: str | None = None: The main argument: a command to execute, a variant specification to show, etc.

diag(msg: str) → None: Output a diagnostic message in verbose mode.

noop: bool = False: No-operation mode; display what would have been done.

repodir: pathlib.Path | None = None: The path to the directory containing the add-storpool-repo data files to install.

repotype: RepoType = RepoType(name='contrib', extension='', url='https://repo.storpool.com/public/'): Which StorPool repository to configure.

verbose: bool = False: Verbose operation; display diagnostic output.

class spvariantapi.variant.Variant(name: str, descr: str, parent: str, family: str, detect: Detect, supported: Supported, commands: Commands, min_sys_python: str, repo: DebRepo | YumRepo, package: dict[str, str], systemd_lib: str, file_ext: str, initramfs_flavor: str, builder: Builder)

The information about a Linux distribution version (build variant).

builder: Builder: The data specific to the StorPool builder containers.

commands: Commands: The OS commands to execute for particular purposes.

descr: str: The human-readable description of the variant.

detect: Detect: The ways to check whether we are running this variant.

family: str: The OS “family” that this distribution belongs to.

file_ext: str: The filename extension of the OS packages (“deb”, “rpm”, etc.).

initramfs_flavor: str: The type of initramfs-generating tools.

min_sys_python: str: The minimum Python version that we can depend on.

name: str: The name of the variant, e.g. ALMA9, UBUNTU2204, etc.

package: dict[str, str]: The names of the packages to be used for this variant.

parent: str: The name of the variant that this one is based on.

repo: DebRepo | YumRepo: The StorPool repository files to install.

supported: Supported: The aspects of StorPool operation supported for this build variant.

systemd_lib: str: The name of the directory to install systemd unit files to.

exception spvariantapi.variant.VariantError: Base class for errors that occurred during variant processing.

spvariantapi.variant.detect_variant(cfg: Config = Config(args=None, command=None, noop=False, repodir=None, repotype=RepoType(name='contrib', extension='', url='https://repo.storpool.com/public/'), verbose=False)) → Variant: Detect the build variant for the current host.

spvariantapi.variant.get_all_variants(cfg: Config = Config(args=None, command=None, noop=False, repodir=None, repotype=RepoType(name='contrib', extension='', url='https://repo.storpool.com/public/'), verbose=False)) → dict[str, spvariantapi.defs.Variant]: Return information about all the supported variants.

spvariantapi.variant.get_all_variants_in_order(cfg: Config = Config(args=None, command=None, noop=False, repodir=None, repotype=RepoType(name='contrib', extension='', url='https://repo.storpool.com/public/'), verbose=False)) → list[spvariantapi.defs.Variant]: Return information about all supported variants in detect order.

spvariantapi.variant.get_by_alias(alias: str, cfg: Config = Config(args=None, command=None, noop=False, repodir=None, repotype=RepoType(name='contrib', extension='', url='https://repo.storpool.com/public/'), verbose=False)) → Variant: Return the variant with the specified name.

spvariantapi.variant.get_variant(name: str, cfg: Config = Config(args=None, command=None, noop=False, repodir=None, repotype=RepoType(name='contrib', extension='', url='https://repo.storpool.com/public/'), verbose=False)) → Variant: Return the variant with the specified name.

spvariantapi.variant.list_all_packages(var: Variant, patterns: Iterable[str] | None = None) → list[defs.OSPackage]: Parse the output of the “list installed packages” command.

spvariantapi.variant.update_namedtuple(data: _TNamedTuple, updates: dict[str, Any]) → _TNamedTuple: Create a new named tuple with some updated values.

Definitions

Common definitions for the OS/distribution variant detection library.

class spvariantapi.defs.Builder(alias: str, base_image: str, branch: str, kernel_package: str, utf8_locale: str)

StorPool builder data.

alias: str: The builder name.

base_image: str: The base Docker image that the builder is generated from.

branch: str: The branch used by the sp-pkg tool to specify the variant.

kernel_package: str: The base kernel OS package.

utf8_locale: str: The name of the locale to use for clean UTF-8 output.

class spvariantapi.defs.Commands(package: CommandsPackage, pkgfile: CommandsPkgFile)

Variant-specific commands, mainly related to the packaging system.

package: CommandsPackage: Commands related to installing packages from upstream repositories.

pkgfile: CommandsPkgFile: Commands related to installing packages from locally-fetched files.

class spvariantapi.defs.CommandsPackage(update_db: list[str], install: list[str], list_all: list[str], purge: list[str], remove: list[str], remove_impl: list[str])

Variant-specific commands related to OS packages.

install: list[str]: Install one or more packages from the upstream repositories.

list_all: list[str]: List the currently installed packages.

purge: list[str]: Remove a package and all its files, including configuration ones.

remove: list[str]: Remove a package and all its files, possibly leaving configuration ones.

remove_impl: list[str]: Remove a package using the low-level OS package manager.

update_db: list[str]: Make the package manager fetch new data from the upstream repositories.

class spvariantapi.defs.CommandsPkgFile(dep_query: list[str], install: list[str])

Variant-specific commands related to OS package files.

dep_query: list[str]: List the packages that the one in the specified package file depends on.

install: list[str]: Install a package from a locally-fetched file.

class spvariantapi.defs.Config(args: list[str] | None = None, command: str | None = None, noop: bool = False, repodir: pathlib.Path | None = None, repotype: RepoType = RepoType(name='contrib', extension='', url='https://repo.storpool.com/public/'), verbose: bool = False)

Runtime configuration for the sp-variant library functions.

args: list[str] | None = None: Additional arguments passed to the command.

command: str | None = None: The main argument: a command to execute, a variant specification to show, etc.

diag(msg: str) → None: Output a diagnostic message in verbose mode.

noop: bool = False: No-operation mode; display what would have been done.

repodir: pathlib.Path | None = None: The path to the directory containing the add-storpool-repo data files to install.

repotype: RepoType = RepoType(name='contrib', extension='', url='https://repo.storpool.com/public/'): Which StorPool repository to configure.

verbose: bool = False: Verbose operation; display diagnostic output.

class spvariantapi.defs.DebRepo(codename: str, vendor: str, sources: str, keyring: str, req_packages: list[str])

Debian package repository data.

codename: str: The distribution codename (e.g. “buster”).

keyring: str: The GnuPG keyring file to copy to /usr/share/keyrings/.

req_packages: list[str]: OS packages that need to be installed before apt-get update is run.

sources: str: The APT sources list file to copy to /etc/apt/sources.list.d/.

vendor: str: The distribution vendor (“debian”, “ubuntu”, etc.).

class spvariantapi.defs.Detect(filename: str, regex: Pattern[str], os_id: str, os_version_regex: Pattern[str])

Check whether this host is running this particular OS variant.

filename: str: The name of the file to read.

os_id: str: The “ID” field in the /etc/os-release file.

os_version_regex: Pattern[str]: The regular expression pattern for the “VERSION_ID” os-release field.

regex: Pattern[str]: The regular expression pattern to look for in the file.

class spvariantapi.defs.OSPackage(name: str, version: str, arch: str, status: str)

The attributes of a currently-installed or known OS package.

arch: str: The system-dependent package architecture name.

name: str: The package name.

status: str: The system-dependent status of the package (installed, half-installed, removed, etc).

version: str: The package version.

class spvariantapi.defs.RepoType(name: str, extension: str, url: str)

Attributes common to a StorPool package repository.

extension: str: The extension to be used in filenames for configuring the package manager.

name: str: The name of the StorPool package repository.

url: str: The base URL of the StorPool package repository.

class spvariantapi.defs.Supported(repo: bool)

The aspects of the StorPool operation supported for this build variant.

repo: bool: Is there a StorPool third-party packages repository?

class spvariantapi.defs.Variant(name: str, descr: str, parent: str, family: str, detect: Detect, supported: Supported, commands: Commands, min_sys_python: str, repo: DebRepo | YumRepo, package: dict[str, str], systemd_lib: str, file_ext: str, initramfs_flavor: str, builder: Builder)

The information about a Linux distribution version (build variant).

builder: Builder: The data specific to the StorPool builder containers.

commands: Commands: The OS commands to execute for particular purposes.

descr: str: The human-readable description of the variant.

detect: Detect: The ways to check whether we are running this variant.

family: str: The OS “family” that this distribution belongs to.

file_ext: str: The filename extension of the OS packages (“deb”, “rpm”, etc.).

initramfs_flavor: str: The type of initramfs-generating tools.

min_sys_python: str: The minimum Python version that we can depend on.

name: str: The name of the variant, e.g. ALMA9, UBUNTU2204, etc.

package: dict[str, str]: The names of the packages to be used for this variant.

parent: str: The name of the variant that this one is based on.

repo: DebRepo | YumRepo: The StorPool repository files to install.

supported: Supported: The aspects of StorPool operation supported for this build variant.

systemd_lib: str: The name of the directory to install systemd unit files to.

exception spvariantapi.defs.VariantConfigError: Invalid parameters passed to the variant routines.

exception spvariantapi.defs.VariantError: Base class for errors that occurred during variant processing.

class spvariantapi.defs.VariantUpdate(name: str, descr: str, parent: str, detect: Detect, updates: dict[str, Any])

The changes to be applied to the parent variant definition.

descr: str: The description of the new variant.

detect: Detect: The ways to detect the new variant.

name: str: The name of the new variant.

parent: str: The variant that the new one is based on.

updates: dict[str, Any]: The changes to be applied to the parent variant’s structure.

class spvariantapi.defs.YumRepo(yumdef: str, keyring: str)

Yum/DNF package repository data.

keyring: str: The keyring file to copy to /etc/pki/rpm-gpg/.

yumdef: str: The file with .repo extension to copy to /etc/yum.repos.d/.

spvariantapi.defs.jsonify(obj: Any) → Any: Return a more readable representation of an object.