kub-cli 0.2.0__py3-none-any.whl

kub_cli/img_cli.py

@@ -0,0 +1,306 @@
+# SPDX-FileCopyrightText: 2026 University of Strasbourg
+# SPDX-FileContributor: Christophe Prud'homme
+# SPDX-FileContributor: Cemosis
+# SPDX-License-Identifier: Apache-2.0
+
+"""Typer CLI for kub-img image management."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from . import __version__
+from .errors import KubCliError
+from .logging_utils import configureLogging
+from .img_tools import KubImgManager, resolveImgConfig
+
+
+imgApp = typer.Typer(
+    add_completion=False,
+    help="Manage kub runtime images for Apptainer and Docker.",
+)
+
+
+def buildImgManager(
+    *,
+    runtime: str | None,
+    image: str | None,
+    runner: str | None,
+    verbose: bool | None,
+    showConfig: bool,
+) -> KubImgManager:
+    config = resolveImgConfig(
+        runtime=runtime,
+        image=image,
+        runner=runner,
+        verbose=verbose,
+    )
+    configureLogging(config.verbose)
+
+    if showConfig:
+        print(json.dumps(config.toDict(), indent=2, sort_keys=True))
+
+    return KubImgManager(config=config)
+
+
+def exitOnError(error: KubCliError) -> None:
+    typer.secho(str(error), fg=typer.colors.RED, err=True)
+    raise typer.Exit(code=error.exit_code) from error
+
+
+@imgApp.callback(invoke_without_command=True)
+def root(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False,
+        "--version",
+        is_eager=True,
+        help="Show kub-cli version and exit.",
+    ),
+) -> None:
+    if version:
+        typer.echo(f"kub-cli {__version__}")
+        raise typer.Exit(code=0)
+
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit(code=0)
+
+
+@imgApp.command("pull")
+def pullImageCommand(
+    source: str | None = typer.Argument(
+        None,
+        metavar="SOURCE",
+        help=(
+            "Optional pull source. "
+            "For Apptainer use oras://... (never docker://). "
+            "If omitted, source is derived from configuration."
+        ),
+    ),
+    runtime: str | None = typer.Option(
+        None,
+        "--runtime",
+        metavar="{auto,apptainer,docker}",
+        help="Container runtime selection.",
+    ),
+    image: str | None = typer.Option(
+        None,
+        "--image",
+        metavar="IMAGE",
+        help="Runtime image path/reference (destination for pull).",
+    ),
+    runner: str | None = typer.Option(
+        None,
+        "--runner",
+        metavar="PATH",
+        help="Runtime executable path or command name.",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Overwrite destination image when runtime is Apptainer.",
+    ),
+    disableCache: bool = typer.Option(
+        False,
+        "--disable-cache",
+        help="Disable cache when runtime is Apptainer.",
+    ),
+    apptainerFlags: list[str] | None = typer.Option(
+        None,
+        "--apptainer-flag",
+        metavar="FLAG",
+        help="Additional apptainer pull flags (repeatable).",
+    ),
+    dockerFlags: list[str] | None = typer.Option(
+        None,
+        "--docker-flag",
+        metavar="FLAG",
+        help="Additional docker pull flags (repeatable).",
+    ),
+    dryRun: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Print the pull command without executing it.",
+    ),
+    verbose: bool | None = typer.Option(
+        None,
+        "--verbose/--no-verbose",
+        help="Enable or disable verbose logging.",
+    ),
+    showConfig: bool = typer.Option(
+        False,
+        "--show-config",
+        help="Print effective kub-cli configuration as JSON.",
+    ),
+) -> None:
+    try:
+        manager = buildImgManager(
+            runtime=runtime,
+            image=image,
+            runner=runner,
+            verbose=verbose,
+            showConfig=showConfig,
+        )
+        exitCode = manager.pullImage(
+            runtime=runtime,
+            source=source,
+            force=force,
+            disableCache=disableCache,
+            apptainerFlags=apptainerFlags or [],
+            dockerFlags=dockerFlags or [],
+            dryRun=dryRun,
+        )
+    except KubCliError as error:
+        exitOnError(error)
+
+    raise typer.Exit(code=exitCode)
+
+
+@imgApp.command("info")
+def infoCommand(
+    runtime: str | None = typer.Option(
+        None,
+        "--runtime",
+        metavar="{auto,apptainer,docker}",
+        help="Container runtime selection.",
+    ),
+    image: str | None = typer.Option(
+        None,
+        "--image",
+        metavar="IMAGE",
+        help="Runtime image path/reference.",
+    ),
+    runner: str | None = typer.Option(
+        None,
+        "--runner",
+        metavar="PATH",
+        help="Runtime executable path or command name.",
+    ),
+    jsonOutput: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit image info as JSON.",
+    ),
+    verbose: bool | None = typer.Option(
+        None,
+        "--verbose/--no-verbose",
+        help="Enable or disable verbose logging.",
+    ),
+    showConfig: bool = typer.Option(
+        False,
+        "--show-config",
+        help="Print effective kub-cli configuration as JSON.",
+    ),
+) -> None:
+    try:
+        manager = buildImgManager(
+            runtime=runtime,
+            image=image,
+            runner=runner,
+            verbose=verbose,
+            showConfig=showConfig,
+        )
+        exitCode = manager.printInfo(runtime=runtime, jsonOutput=jsonOutput)
+    except KubCliError as error:
+        exitOnError(error)
+
+    raise typer.Exit(code=exitCode)
+
+
+@imgApp.command("apps")
+def appsCommand(
+    runtime: str | None = typer.Option(
+        "apptainer",
+        "--runtime",
+        metavar="{apptainer}",
+        help="Runtime selection for app listing (Apptainer only).",
+    ),
+    image: str | None = typer.Option(
+        None,
+        "--image",
+        metavar="IMAGE",
+        help="Apptainer image path.",
+    ),
+    runner: str | None = typer.Option(
+        None,
+        "--runner",
+        metavar="PATH",
+        help="Apptainer executable path or command name.",
+    ),
+    verbose: bool | None = typer.Option(
+        None,
+        "--verbose/--no-verbose",
+        help="Enable or disable verbose logging.",
+    ),
+    showConfig: bool = typer.Option(
+        False,
+        "--show-config",
+        help="Print effective kub-cli configuration as JSON.",
+    ),
+) -> None:
+    try:
+        manager = buildImgManager(
+            runtime=runtime,
+            image=image,
+            runner=runner,
+            verbose=verbose,
+            showConfig=showConfig,
+        )
+        exitCode = manager.printApps(runtime=runtime)
+    except KubCliError as error:
+        exitOnError(error)
+
+    raise typer.Exit(code=exitCode)
+
+
+@imgApp.command("path")
+def pathCommand(
+    runtime: str | None = typer.Option(
+        None,
+        "--runtime",
+        metavar="{auto,apptainer,docker}",
+        help="Runtime selection for resolved image path/reference.",
+    ),
+    image: str | None = typer.Option(
+        None,
+        "--image",
+        metavar="IMAGE",
+        help="Image path/reference override.",
+    ),
+    runner: str | None = typer.Option(
+        None,
+        "--runner",
+        metavar="PATH",
+        help="Runtime executable path or command name.",
+    ),
+    verbose: bool | None = typer.Option(
+        None,
+        "--verbose/--no-verbose",
+        help="Enable or disable verbose logging.",
+    ),
+    showConfig: bool = typer.Option(
+        False,
+        "--show-config",
+        help="Print effective kub-cli configuration as JSON.",
+    ),
+) -> None:
+    try:
+        manager = buildImgManager(
+            runtime=runtime,
+            image=image,
+            runner=runner,
+            verbose=verbose,
+            showConfig=showConfig,
+        )
+        exitCode = manager.printImagePath(runtime=runtime)
+    except KubCliError as error:
+        exitOnError(error)
+
+    raise typer.Exit(code=exitCode)
+
+
+def imgMain() -> None:
+    imgApp(prog_name="kub-img")

kub_cli/img_integration.py

@@ -0,0 +1,265 @@
+# SPDX-FileCopyrightText: 2026 University of Strasbourg
+# SPDX-FileContributor: Christophe Prud'homme
+# SPDX-FileContributor: Cemosis
+# SPDX-License-Identifier: Apache-2.0
+
+"""Internal helpers to invoke the kub-img utility via subprocess."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+from typing import Any, Literal
+
+from .config import KubConfig, SUPPORTED_RUNTIMES
+from .errors import KubCliError, RuntimeSelectionError
+from .logging_utils import LOGGER, formatCommand
+from .runtime import (
+    deriveApptainerOrasReference,
+    getRuntimeCandidateImage,
+    getRunnerValue,
+    tryResolveRunnerExecutable,
+)
+
+
+ImageRuntime = Literal["apptainer", "docker"]
+
+
+@dataclass(frozen=True)
+class KubImgPullRequest:
+    """Resolved arguments for a kub-img pull operation."""
+
+    runtime: ImageRuntime
+    image: str
+    source: str
+
+
+@dataclass(frozen=True)
+class KubImgInfoRequest:
+    """Resolved arguments for a kub-img info operation."""
+
+    runtime: ImageRuntime
+    image: str
+
+
+@dataclass(frozen=True)
+class KubImgCommandRunner:
+    """Invoke `kub-img` as a subprocess safely."""
+
+    executable: str = "kub-img"
+    verbose: bool = False
+
+    def resolveExecutable(self) -> str:
+        executablePath = Path(self.executable).expanduser()
+        hasPathSeparator = executablePath.parent != Path(".")
+
+        if executablePath.is_absolute() or hasPathSeparator:
+            if executablePath.exists() and os.access(executablePath, os.X_OK):
+                return str(executablePath)
+            raise KubCliError(f"kub-img executable not found or not executable: '{executablePath}'")
+
+        resolved = shutil.which(self.executable)
+        if resolved is None:
+            raise KubCliError(
+                "kub-img executable not found in PATH. Install kub-cli with the kub-img entrypoint."
+            )
+
+        return resolved
+
+    def pullImage(self, request: KubImgPullRequest, *, dryRun: bool = False) -> int:
+        executable = self.resolveExecutable()
+        command = [
+            executable,
+            "pull",
+            "--runtime",
+            request.runtime,
+            "--image",
+            request.image,
+            request.source,
+        ]
+
+        if self.verbose:
+            command.append("--verbose")
+            LOGGER.debug("Running kub-img pull command: %s", formatCommand(command))
+
+        if dryRun:
+            print(formatCommand(command))
+            return 0
+
+        try:
+            completed = subprocess.run(command, check=False)
+        except OSError as error:
+            raise KubCliError(f"Unable to execute kub-img pull command: {error}") from error
+
+        if completed.returncode != 0:
+            raise KubCliError(
+                f"kub-img pull failed with exit code {completed.returncode}.",
+                exit_code=completed.returncode,
+            )
+
+        return 0
+
+    def inspectImageInfo(self, request: KubImgInfoRequest) -> dict[str, Any]:
+        executable = self.resolveExecutable()
+        command = [
+            executable,
+            "info",
+            "--runtime",
+            request.runtime,
+            "--image",
+            request.image,
+            "--json",
+        ]
+
+        if self.verbose:
+            command.append("--verbose")
+            LOGGER.debug("Running kub-img info command: %s", formatCommand(command))
+
+        try:
+            completed = subprocess.run(
+                command,
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+        except OSError as error:
+            raise KubCliError(f"Unable to execute kub-img info command: {error}") from error
+
+        if completed.returncode != 0:
+            stderrText = completed.stderr.strip()
+            message = (
+                f"kub-img info failed with exit code {completed.returncode}. "
+                f"{stderrText}".strip()
+            )
+            raise KubCliError(message, exit_code=completed.returncode)
+
+        try:
+            payload = json.loads(completed.stdout)
+        except json.JSONDecodeError as error:
+            raise KubCliError(
+                "kub-img info returned non-JSON output while --json was requested."
+            ) from error
+
+        if not isinstance(payload, dict):
+            raise KubCliError("kub-img info JSON output must be an object.")
+
+        return payload
+
+
+def resolveImageRuntime(config: KubConfig) -> ImageRuntime:
+    """Resolve runtime for image pull/info operations."""
+
+    configured = config.runtime.strip().lower()
+    if configured not in SUPPORTED_RUNTIMES:
+        supported = ", ".join(sorted(SUPPORTED_RUNTIMES))
+        raise RuntimeSelectionError(
+            f"Invalid runtime value '{config.runtime}'. Use one of: {supported}."
+        )
+
+    if configured in {"apptainer", "docker"}:
+        return configured
+
+    apptainerRunnerValue = getRunnerValue(config, "apptainer")
+    apptainerRunner = tryResolveRunnerExecutable(apptainerRunnerValue)
+    if apptainerRunner is not None:
+        try:
+            resolveApptainerLocalImageReference(config)
+            return "apptainer"
+        except KubCliError:
+            pass
+
+    dockerRunnerValue = getRunnerValue(config, "docker")
+    dockerRunner = tryResolveRunnerExecutable(dockerRunnerValue)
+    dockerImage = getRuntimeCandidateImage(config, "docker")
+    if dockerRunner is not None and dockerImage is not None:
+        return "docker"
+
+    raise RuntimeSelectionError(
+        "Unable to resolve runtime in auto mode for image operations. "
+        "Neither Apptainer nor Docker runner is available."
+    )
+
+
+def buildKubImgInfoRequest(config: KubConfig) -> KubImgInfoRequest:
+    runtime = resolveImageRuntime(config)
+
+    if runtime == "docker":
+        dockerImage = getRuntimeCandidateImage(config, "docker")
+        if dockerImage is None:
+            raise KubCliError(
+                "No Docker image configured for image info. "
+                "Set --image, KUB_IMAGE_DOCKER, or KUB_IMAGE."
+            )
+        return KubImgInfoRequest(runtime="docker", image=dockerImage)
+
+    apptainerImage = resolveApptainerLocalImageReference(config)
+    return KubImgInfoRequest(runtime="apptainer", image=apptainerImage)
+
+
+def buildKubImgPullRequest(config: KubConfig) -> KubImgPullRequest:
+    runtime = resolveImageRuntime(config)
+
+    if runtime == "docker":
+        dockerImage = getRuntimeCandidateImage(config, "docker")
+        if dockerImage is None:
+            raise KubCliError(
+                "No Docker image configured for pull. "
+                "Set --image, KUB_IMAGE_DOCKER, or KUB_IMAGE."
+            )
+
+        return KubImgPullRequest(
+            runtime="docker",
+            image=dockerImage,
+            source=dockerImage,
+        )
+
+    destinationImage = resolveApptainerLocalImageReference(config)
+
+    explicitApptainerReference = config.imageApptainer
+    if explicitApptainerReference is not None and explicitApptainerReference.startswith("oras://"):
+        source = explicitApptainerReference
+    else:
+        dockerImage = getRuntimeCandidateImage(config, "docker")
+        if dockerImage is None:
+            raise KubCliError(
+                "Unable to derive Apptainer ORAS source: no Docker image is configured. "
+                "Set KUB_IMAGE_DOCKER (or runtime image config)."
+            )
+        source = deriveApptainerOrasReference(dockerImage)
+
+    if source.startswith("docker://"):
+        raise KubCliError(
+            "Apptainer image pull source must use oras://, not docker://."
+        )
+
+    return KubImgPullRequest(
+        runtime="apptainer",
+        image=destinationImage,
+        source=source,
+    )
+
+
+def resolveApptainerLocalImageReference(config: KubConfig) -> str:
+    candidates = [config.imageOverride, config.imageApptainer, config.image]
+
+    for candidate in candidates:
+        if candidate is None:
+            continue
+
+        normalized = candidate.strip()
+        if not normalized:
+            continue
+
+        if "://" in normalized:
+            continue
+
+        return normalized
+
+    raise KubCliError(
+        "No local Apptainer image path configured. "
+        "Set --image or KUB_IMAGE_APPTAINER to a .sif file path."
+    )