utils.docker.image package

Submodules

utils.docker.image.discovery module

class utils.docker.image.discovery.ImageRef(role: str, service: str, name: str, version: str, source: str, registry: str = 'docker.io', source_file: str = 'meta/services.yml')

Bases: object

Role-declared container image reference.

Fields:

role: e.g. svc-db-postgres service: e.g. postgres name: canonical image name without registry, e.g. postgis/postgis version: e.g. 17-3.5 source: full pull ref, e.g. docker.io/library/postgres:16 registry: source registry hostname, e.g. docker.io, quay.io source_file: file the ref was read from, role-relative for a role

image and repository-relative for a runner image

name: str
registry: str = 'docker.io'
role: str
service: str
source: str
source_file: str = 'meta/services.yml'
version: str
utils.docker.image.discovery.canonical_image_name(image: str) → str

Canonical image name without registry and without tag/digest.

Strips any known registry prefix so that the name can be used uniformly regardless of the source registry:

quay.io/keycloak/keycloak -> keycloak/keycloak ghcr.io/mastodon/mastodon -> mastodon/mastodon docker.io/postgres -> postgres postgres -> postgres

utils.docker.image.discovery.docker_hub_source(image: str, version: str) → str

Build canonical Docker Hub source ref for skopeo.

postgres + 16 -> docker.io/library/postgres:16 postgis/postgis + 17 -> docker.io/postgis/postgis:17

utils.docker.image.discovery.image_source(image: str, version: str) → str

Full pull reference for skopeo (without the docker:// scheme).

Examples:

postgres          + 16      -> docker.io/library/postgres:16
postgis/postgis   + 17-3.5  -> docker.io/postgis/postgis:17-3.5
quay.io/keycloak/keycloak + latest -> quay.io/keycloak/keycloak:latest
ghcr.io/mastodon/mastodon + latest -> ghcr.io/mastodon/mastodon:latest
utils.docker.image.discovery.is_docker_hub_image(image: str) → bool

Return True iff image is hosted on Docker Hub (kept for backward compat).

utils.docker.image.discovery.is_mirrorable_image(image: str) → bool

Return True for images from any supported public registry that we mirror.

utils.docker.image.discovery.iter_role_images(repo_root: Path) → Iterable[ImageRef]

Yield all ImageRef entries discovered across all roles in repo_root.

Source: roles/**/meta/services.yml → <entity>.{image,version}. Roles the updaters do not maintain (is_maintained) are left out.

See docs/contributing/artefact/image.md for the full format reference.

utils.docker.image.discovery.iter_runner_images(repo_root: Path) → Iterable[ImageRef]

Yield the images the CI runner pulls itself, outside every role.

Parameters:

repo_root – repository root holding the RUNNER_COMPOSE_FILES and default.env. A compose image that interpolates a variable, carries no tag or is pinned by digest yields nothing.

utils.docker.image.discovery.load_yaml(path: Path) → dict
utils.docker.image.discovery.normalize_docker_hub(image: str) → str

Remove Docker Hub registry prefix if present (backward compat).

utils.docker.image.discovery.split_name_and_suffix(image: str) → tuple[str, str]
Split image into base name and suffix:

repo/name:tag -> (repo/name, :tag) repo/name@sha.. -> (repo/name, @sha..) repo/name -> (repo/name, “”)

utils.docker.image.pin module

utils.docker.image.pin.is_digest(version: str) → bool

Whether version pins by content rather than by name.

Parameters:

version – the version: value a role declares for an image.

utils.docker.image.pin.pin_class(version: str) → str

Classify a pin as semver, digest or ref.

Parameters:

version – the version: value a role declares for an image.

Returns:

a tag that names no version the registry can order, so nothing can tell whether it moved.

Return type:

The class name. ref is the residue

utils.docker.image.pin.pull_reference(name: str, version: str) → str

Join an image name and a pin into the reference a registry accepts.

Parameters:

  • name – image name, with or without a registry prefix.

  • version – the version: value a role declares for an image.

utils.docker.image.pin.reference_separator(version: str) → str

The character that joins an image name to version in a pull ref.

Parameters:

version – the version: value a role declares for an image.

utils.docker.image.ref module

utils.docker.image.ref.dockerhub_repo(image: str) → str
utils.docker.image.ref.is_dockerhub(image: str) → bool
utils.docker.image.ref.is_valid_image_name(image: Any) → bool
utils.docker.image.ref.split_registry_and_name(image: str) → tuple[str | None, str] | None

Return (registry, repository_name) for a validated Docker image name.

utils.docker.image.runtime module

class utils.docker.image.runtime.PhpRuntime(version: str | None, lines: tuple[str, ...], packages: tuple[str, ...])

Bases: object

PHP found in an image’s build record.

Parameters:

  • version – PHP_VERSION the image sets, None when it sets none.

  • lines – major[.minor] lines named by distro PHP packages or a PHP_BASE build argument.

  • packages – unversioned distro packages that are the interpreter itself (php, php-cli, php-fpm, php-cgi, php-phpdbg, libapache2-mod-php); they name no line. Extension and library packages such as php-mysql or php-pear do not count.

lines: tuple[str, ...]
packages: tuple[str, ...]
version: str | None
utils.docker.image.runtime.build_instructions(image: str, reference: str, *, os_name: str, architecture: str) → list[str] | None

Return the build instructions of image:reference without pulling it.

Parameters:

  • image – image name, with or without registry host.

  • reference – tag or digest.

  • os_name – platform to resolve a multi-arch index to.

  • architecture – platform to resolve a multi-arch index to.

Returns:

The image’s history plus its final ENV lines, or None when the registry gave no answer. A Docker Hub tag is read through the Hub API, which a pull rate limit does not meter; every other image through its OCI config blob.

utils.docker.image.runtime.load_php_floors() → dict[str, str]

Return {"<major>.<minor>": "<lowest patched version>"} from the SPOT.

utils.docker.image.runtime.php_finding(runtime: PhpRuntime, floors: dict[str, str]) → str | None

Judge an image’s PHP against the floors.

Parameters:
Returns:

None when nothing is below its floor, otherwise the reason. The lines are judged next to PHP_VERSION, so an end-of-life package line fails an image whose PHP_VERSION is patched. Unversioned packages alone are no finding: their patch level is unknown.

utils.docker.image.runtime.php_runtime(instructions: list[str]) → PhpRuntime | None

Read the PHP an image ships from its build instructions.

Parameters:

instructions – see build_instructions().

Returns:

The last PHP_VERSION set, the lines of the distro PHP packages and PHP_BASE arguments, and the unversioned interpreter packages, or None when none of them appears.

Module contents