Common Code¶

Common classes and values used around relenv.

exception relenv.common.BuildCommandError¶

Raised when a build command execution fails.

This indicates that a subprocess (compiler, linker, etc.) returned a non-zero exit code during the build process.

Example:

raise BuildCommandError(: f”Build command failed: {’ ‘.join(cmd)}”

)

exception relenv.common.ChecksumValidationError¶

Raised when file checksum verification fails.

This typically indicates file corruption or tampering. The error message should include the expected and actual checksums when available.

Example:

raise ChecksumValidationError(: f”Checksum mismatch for {filename}: ” f”expected {expected}, got {actual}”

)

exception relenv.common.ConfigurationError¶

Raised when required configuration is missing or invalid.

This typically occurs during build setup when recipes are incomplete or environment variables are not properly set.

Example:

raise ConfigurationError(: “Python recipe is missing download configuration”

)

exception relenv.common.DownloadError¶

Raised when downloading a file from a URL fails.

This encompasses network errors, HTTP errors, and other issues that prevent successfully retrieving a remote resource.

Example:: raise DownloadError(f”Failed to download {url}: {reason}”)

exception relenv.common.MissingDependencyError¶

Raised when a required build dependency is not found.

This typically occurs when expected files, directories, or system packages are missing from the build environment.

Example:

raise MissingDependencyError(: f”Unable to locate {dependency_name}”

)

exception relenv.common.PlatformError¶

Raised when operating on an unsupported platform.

Relenv supports Linux, macOS, and Windows. This exception is raised when attempting operations that are platform-specific or when running on an unsupported platform.

Example:: raise PlatformError(f”Unsupported platform: {sys.platform}”)

exception relenv.common.RelenvEnvironmentError¶

Raised when there are issues with the relenv environment.

This occurs when operations require being inside a relenv environment but the current environment is not properly configured.

Example:

raise RelenvEnvironmentError(: “Not in a relenv environment”

)

exception relenv.common.RelenvException¶: Base class for exeptions generated from relenv.

exception relenv.common.SignatureValidationError¶

Raised when GPG signature verification fails.

This indicates that a downloaded file’s cryptographic signature does not match the expected signature, suggesting tampering or an incomplete download.

Example:

raise SignatureValidationError(: f”GPG signature verification failed for {filename}”

)

exception relenv.common.ValidationError¶

Base class for validation-related errors.

Raised when data validation fails (checksums, signatures, etc.). This follows CPython’s convention of having intermediate base classes for related exception types.

class relenv.common.Version(data: str)¶

Version comparisons.

static parse_string(data: str) → tuple[int, int | None, int | None]¶: Parse a version string into major, minor, and micro integers.

class relenv.common.WorkDirs(root: str | PathLike[str])¶

Simple class used to hold references to working directories relenv uses relative to a given root.

Parameters:: root (str) – The root of the working directories tree

relenv.common.addpackage(sitedir: str, name: str | PathLike[str]) → list[str] | None¶: Add editable package to path.

relenv.common.archived_build(triplet: str | None = None) → Path¶

Finds a the location of an archived build.

Parameters:: triplet (str) – The build triplet to find
Returns:: The location of the archived build
Return type:: pathlib.Path

relenv.common.build_arch() → str¶: Return the current machine.

relenv.common.check_url(url: str, timestamp: float | None = None, timeout: float = 30) → bool¶: Check that the url returns a 200.

relenv.common.download_url(url: str, dest: str | PathLike[str], verbose: bool = True, backoff: int = 3, timeout: float = 60, progress_callback: Callable[[int, int], None] | None = None) → str¶

Download the url to the provided destination.

This method assumes the last part of the url is a filename. (https://foo.com/bar/myfile.tar.xz)

Parameters:

url (str) – The url to download
dest (str) – Where to download the url to
verbose (bool) – Print download url and destination to stdout
progress_callback (Optional[Callable[[int, int], None]]) – Optional callback(downloaded_bytes, total_bytes)

Raises:

urllib.error.HTTPError – If the url was unable to be downloaded

Returns:

The path to the downloaded content

Return type:

str

relenv.common.extract_archive(to_dir: str | PathLike[str], archive: str | PathLike[str]) → None¶

Extract an archive to a specific location.

Parameters:

to_dir (str) – The directory to extract to
archive (str) – The archive to extract

relenv.common.fetch_url(url: str, fp: BinaryIO, backoff: int = 3, timeout: float = 30, progress_callback: Callable[[int, int], None] | None = None) → None¶

Fetch the contents of a url.

This method will store the contents in the given file like object.

Parameters:: progress_callback (Optional[Callable[[int, int], None]]) – Optional callback(downloaded_bytes, total_bytes)

relenv.common.fetch_url_content(url: str, backoff: int = 3, timeout: float = 30) → str¶

Fetch the contents of a url.

This method will store the contents in the given file like object.

relenv.common.format_shebang(python: str, tpl: str = '#!/bin/sh\n"true" \'\'\'\'\n# shellcheck disable=SC2093\n"exec" "$(dirname "$(readlink -f "$0")"){}" "$0" "$@"\n\' \'\'\'\n') → str¶: Return a formatted shebang.

relenv.common.get_download_location(url: str, dest: str | PathLike[str]) → str¶

Get the full path to where the url will be downloaded to.

Parameters:

url (str) – The url to donwload
dest (str) – Where to download the url to

Returns:

The path to where the url will be downloaded to

Return type:

str

relenv.common.get_toolchain(arch: str | None = None, root: str | PathLike[str] | None = None) → Path | None¶

Get a the toolchain directory, specific to the arch if supplied.

On Linux, this function will extract the toolchain from ppbt if needed. If the toolchain already exists, it will be returned even if ppbt is not available (e.g., when running tests on non-Linux platforms that patch sys.platform to “linux”). This allows using existing toolchains without requiring ppbt to be installed.

Parameters:

arch (str) – The architecture to get the toolchain for
root (str) – The root of the relenv working directories to search in

Returns:

The directory holding the toolchain, or None if on Linux and the toolchain doesn’t exist and ppbt is unavailable

Return type:

pathlib.Path

relenv.common.get_triplet(machine: str | None = None, plat: str | None = None) → str¶

Get the target triplet for the specified machine and platform.

If any of the args are None, it will try to deduce what they should be.

Parameters:

machine (str) – The machine for the triplet
plat (str) – The platform for the triplet

Raises:

RelenvException – If the platform is unknown

Returns:

The target triplet

Return type:

str

relenv.common.list_archived_builds() → list[tuple[str, str, str]]¶: Return a list of version, architecture and platforms for builds.

relenv.common.makepath(*paths: str | PathLike[str]) → tuple[str, str]¶: Make a normalized path name from paths.

relenv.common.plat_from_triplet(plat: str) → str¶: Convert platform from build to the value of sys.platform.

relenv.common.relative_interpreter(root_dir: str | PathLike[str], scripts_dir: str | PathLike[str], interpreter: str | PathLike[str]) → Path¶: Return a relativized path to the given scripts_dir and interpreter.

relenv.common.runcmd(*args: Any, **kwargs: Any) → Popen[str]¶

Run a command.

Run the provided command, raising an Exception when the command finishes with a non zero exit code. Arguments are passed through to subprocess.run

Returns:: The process result
Return type:: subprocess.CompletedProcess
Raises:: RelenvException – If the command finishes with a non zero exit code

relenv.common.sanitize_sys_path(sys_path_entries: Iterable[str]) → list[str]¶: Sanitize sys.path to only include paths relative to the onedir environment.

relenv.common.toolchain_root_dir() → Path¶: Return the root directory used for cached toolchains.

relenv.common.work_dir(name: str, root: str | PathLike[str] | None = None) → Path¶

Get the absolute path to the relenv working directory of the given name.

Parameters:

name (str) – The name of the directory
root (str) – The root directory that this working directory will be relative to

Returns:

An absolute path to the requested relenv working directory

Return type:

pathlib.Path

relenv.common.work_dirs(root: str | PathLike[str] | None = None) → WorkDirs¶

Returns a WorkDirs instance based on the given root.

Parameters:: root (str) – The desired root of relenv’s working directories
Returns:: A WorkDirs instance based on the given root
Return type:: relenv.common.WorkDirs

relenv.common.work_root(root: str | PathLike[str] | None = None) → Path¶

Get the root directory that all other relenv working directories should be based on.

Parameters:: root (str) – An explicitly requested root directory
Returns:: An absolute path to the relenv root working directory
Return type:: pathlib.Path