utils.install package

Subpackages

Submodules

utils.install.collections module

Compare the pinned Galaxy requirements against what is on disk.

Imported by the lint bootstrap, which runs on a bare interpreter before any dependency is installed, so this module stays on the standard library. It also stays inside its own package: the Dockerfile copies it into the image beside utils/__init__.py and utils/install/__init__.py and nothing else, so importing any other utils submodule raises ModuleNotFoundError in the layer that runs it. The requirements files it reads are this repository’s own and hold one shape: a collections: list of - name: entries with an optional version:. A line that does not match that shape leaves the entry unpinned, which the caller treats as unsatisfied and installs.

utils.install.collections.declared_pins(requirements_file: Path) → list[tuple[str, str | None]]

The (fqcn, version) pairs a requirements file declares, in order.

Parameters:

requirements_file – the requirements.galaxy.yml to read.

utils.install.collections.main() → int

Exit 0 when every pinned collection is present at its pinned version.

Parameters:

  • argv[1] – path to requirements.galaxy.yml.

  • argv[2] – path to the collections directory.

utils.install.collections.unsatisfied(requirements_file: Path, collections_dir: Path) → list[str]

Requirements that COLLECTIONS_DIR does not already hold at the pinned version.

An entry without a pinned version can never be confirmed from disk and is always reported, so the caller falls through to a real install.

Parameters:

  • requirements_file – the requirements.galaxy.yml to read.

  • collections_dir – the -p target ansible-galaxy installs into.

utils.install.github_release module

GitHub-release asset helpers (latest-tag resolver + downloader).

utils.install.github_release.download_release_asset(url: str, output: str) → None
utils.install.github_release.resolve_latest_tag(latest_url: str, *, timeout: float = 30.0) → str

utils.install.interpreters module

Interpreter provisioning for the unit suites, baked into the image.

utils.install.interpreters.ensure_interpreters_present() → None

Install the interpreters the PHP and Ruby unit suites run on.

Raises:

RuntimeError – an interpreter is still absent after the install attempt.

utils.install.node module

Node.js runtime provisioning for the lint toolchain and the JavaScript unit suite.

utils.install.node.ensure_node_present() → None

Provide a node whose release line is still supported upstream.

Raises:

RuntimeError – node is still absent after the install attempt, or the upstream install failed its checks.

utils.install.node.expected_sha256(shasums: Path, name: str) → str

Return the checksum SHASUMS256.txt records for a file.

Parameters:

  • shasums – the downloaded SHASUMS256.txt.

  • name – file name to look up.

Raises:

RuntimeError – the file is not listed.

utils.install.node.install_upstream_lts() → str

Install the newest Node.js LTS from nodejs.org under PREFIX.

Returns:

The installed version.

Raises:

  • RuntimeError – the checksum does not match, or node on PATH is not the installed release afterwards.

  • subprocess.CalledProcessError – the signature does not verify.

utils.install.node.installed_line() → str

Return the release line of the node on PATH, such as v20.

Returns:

The major version prefixed with v, as the release schedule keys it.

utils.install.node.line_is_supported(line: str, schedule: dict, today: date) → bool

Tell whether a release line still receives upstream fixes.

Parameters:

  • line – release line such as v20.

  • schedule – the parsed nodejs/Release schedule.json.

  • today – the date the end of life is compared against.

Returns:

False for an unknown line and for a line past its end date.

utils.install.node.newest_lts(index: list) → str

Return the version of the newest LTS release in index.json.

Parameters:

index – the parsed https://nodejs.org/dist/index.json, newest first.

Raises:

RuntimeError – the index lists no LTS release.

utils.install.node.tarball_name(version: str, system: str, machine: str) → str

Return the Linux tarball name of a release for this host.

Parameters:

  • version – release version such as v24.22.1.

  • system – platform.system() of the host.

  • machine – platform.machine() of the host.

Raises:

RuntimeError – the host is not Linux, or Node.js publishes no Linux build for the machine.

utils.install.npm module

npm-based installer helpers.

utils.install.npm.ensure_npm_present() → None
utils.install.npm.npm_install_global(package: str) → None
utils.install.npm.npm_install_local_in_repo(repo_root: str) → None

utils.install.php module

PHP toolchain provisioning for the PHP unit suite.

utils.install.php.ensure_php_present() → None

Install the PHP toolchain and the Composer vendor tree.

Raises:

  • RuntimeError – php, composer or phpunit is still absent afterwards.

  • subprocess.CalledProcessError – composer install failed.

utils.install.php.ensure_php_toolchain() → None

Install the PHP interpreter, Composer and the extensions PHPUnit needs.

phpunit/phpunit declares _PHPUNIT_EXTENSIONS as platform requirements and Composer refuses to resolve the vendor tree without them, so they are part of the toolchain rather than of the suite consuming it. A distro ships them as packages separate from the interpreter, which is why a present php binary does not imply they are there.

Composer needs an archive extractor for its dist downloads. Without one it silently falls back to --prefer-source and mirror-clones every dependency, which blows its 300 s process timeout on phpunit.git. Arch ships no zip extension and no php-zip package, so the extractor has to be the unzip binary rather than the extension.

Raises:

RuntimeError – php, composer, unzip or one of the extensions is still absent.

utils.install.pip module

Pip-based installer with venv / sudo / –user fallback logic.

utils.install.pip.detect_python_bin() → str
utils.install.pip.detect_python_scripts_dir(python_bin: str) → str
utils.install.pip.detect_python_user_scripts_dir(python_bin: str) → str
utils.install.pip.install_pip_pkg(pip_spec: str) → None
utils.install.pip.pip_supports_break_system_packages(python_bin: str) → bool
utils.install.pip.python_runs_in_venv(python_bin: str) → bool

utils.install.primitives module

Shared low-level install helpers.

utils.install.primitives.download_file(url: str, output: str, *, timeout: float = 60.0) → None

Fetch url into output, retrying only transient transport failures.

Parameters:

  • url – source to read.

  • output – path the body is written to.

  • timeout – per-attempt socket timeout in seconds.

Raises:

HTTPError – immediately for any status outside _RETRYABLE_STATUS, so a stale version pin fails on the first attempt instead of after the backoff.

utils.install.primitives.ensure_dir_on_path(directory: str) → None
utils.install.primitives.install_with_optional_sudo(cmd: Sequence[str]) → None
utils.install.primitives.log(msg: str) → None
utils.install.primitives.run_privileged(cmd: Sequence[str]) → None
utils.install.primitives.warn(msg: str) → None
utils.install.primitives.which(cmd: str) → bool

utils.install.ruby module

Ruby runtime provisioning for the Ruby unit suite.

utils.install.ruby.ensure_minitest_present() → None

Make minitest loadable, installing its package if ruby lacks it.

Raises:

RuntimeError – no package mapping for the detected package manager, or minitest is still not loadable after the install.

utils.install.ruby.ensure_ruby_present() → None

Install the Ruby interpreter and minitest through the system package manager.

Raises:

RuntimeError – ruby or minitest is still absent after the install attempt.

utils.install.ruby.minitest_loadable() → bool

Return whether the installed ruby can require minitest.

Returns:

True when ruby -e 'require "minitest"' exits 0.

utils.install.system_pkg module

System-package-manager dispatch (pacman / apt-get / dnf / yum / brew).

utils.install.system_pkg.detect_package_manager() → str
utils.install.system_pkg.ensure_command_present(command_name: str) → None

Make a command available, installing it if the host lacks it.

Parameters:

command_name – executable name, must be a key of the installer mapping.

Raises:

RuntimeError – the command is still absent after the install attempt.

utils.install.system_pkg.ensure_php_extension_present(extension: str) → None

Make a PHP extension available, installing its package if absent.

A distro ships the interpreter and its extensions as separate packages, so a present php binary says nothing about them and ensure_command_present returns early on one. The extension is therefore probed against php -m.

Parameters:

extension – extension name as php -m reports it.

Raises:

RuntimeError – no mapping for this extension on the detected package manager, or the extension is still absent after the install.

utils.install.system_pkg.install_command_via_pkg(command_name: str) → None
utils.install.system_pkg.install_package_candidates(manager: str, packages: list[str], provides: str | None = None) → None

Install packages until provides is callable, or all candidates fail.

Parameters:

  • manager – the detected package manager.

  • packages – candidate package names, most specific first.

  • provides – the command the caller needs.

utils.install.system_pkg.loaded_php_extensions() → set[str]

Return the extensions the php CLI currently loads, lower-cased.

Returns:

the set reported by php -m, empty when php cannot be queried.

Module contents