kub-cli 0.2.0__py3-none-any.whl

kub_cli/__init__.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: 2026 University of Strasbourg
+# SPDX-FileContributor: Christophe Prud'homme
+# SPDX-FileContributor: Cemosis
+# SPDX-License-Identifier: Apache-2.0
+
+"""kub-cli package."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+try:
+    __version__ = version("kub-cli")
+except PackageNotFoundError:
+    __version__ = "0.2.0"
+
+
+__all__ = ["__version__"]

kub_cli/__main__.py

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: 2026 University of Strasbourg
+# SPDX-FileContributor: Christophe Prud'homme
+# SPDX-FileContributor: Cemosis
+# SPDX-License-Identifier: Apache-2.0
+
+"""Module entrypoint for `python -m kub_cli`."""
+
+from .cli import metaMain
+
+
+if __name__ == "__main__":
+    metaMain()

kub_cli/cli.py

@@ -0,0 +1,292 @@
+# SPDX-FileCopyrightText: 2026 University of Strasbourg
+# SPDX-FileContributor: Christophe Prud'homme
+# SPDX-FileContributor: Cemosis
+# SPDX-License-Identifier: Apache-2.0
+
+"""Typer CLI entrypoints for kub-cli wrapper commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Sequence
+
+import typer
+
+from . import __version__
+from .commands import WrapperOptions, runWrapperCommand
+from .errors import KubCliError
+from .versioning import bumpProjectVersion
+
+
+CONTEXT_SETTINGS = {
+    "allow_extra_args": True,
+    "ignore_unknown_options": True,
+}
+
+
+def normalizeForwardedArgs(args: Sequence[str]) -> list[str]:
+    forwarded = list(args)
+    if forwarded and forwarded[0] == "--":
+        return forwarded[1:]
+    return forwarded
+
+
+def executeWrapperCommand(
+    *,
+    appName: str,
+    ctx: typer.Context,
+    runtime: str | None,
+    image: str | None,
+    bind: Sequence[str],
+    pwd: str | None,
+    runner: str | None,
+    dryRun: bool,
+    verbose: bool | None,
+    apptainerFlags: Sequence[str],
+    dockerFlags: Sequence[str],
+    envVars: Sequence[str],
+    showConfig: bool,
+) -> None:
+    forwardedArgs = normalizeForwardedArgs(ctx.args)
+    options = WrapperOptions(
+        runtime=runtime,
+        image=image,
+        binds=tuple(bind),
+        pwd=pwd,
+        runner=runner,
+        dryRun=dryRun,
+        verbose=verbose,
+        apptainerFlags=tuple(apptainerFlags),
+        dockerFlags=tuple(dockerFlags),
+        envVars=tuple(envVars),
+        showConfig=showConfig,
+    )
+
+    try:
+        exitCode = runWrapperCommand(
+            appName=appName,
+            forwardedArgs=forwardedArgs,
+            options=options,
+        )
+    except KubCliError as error:
+        typer.secho(str(error), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=error.exit_code) from error
+
+    raise typer.Exit(code=exitCode)
+
+
+def createWrapperApp(*, appName: str, helpText: str) -> typer.Typer:
+    app = typer.Typer(
+        add_completion=False,
+        no_args_is_help=False,
+        help=helpText,
+    )
+
+    @app.command(context_settings=CONTEXT_SETTINGS)
+    def wrapper(
+        ctx: typer.Context,
+        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 reference/path (runtime-dependent).",
+        ),
+        bind: list[str] | None = typer.Option(
+            None,
+            "--bind",
+            metavar="SRC:DST",
+            help="Bind mount or volume mapping (repeatable).",
+        ),
+        pwd: str | None = typer.Option(
+            None,
+            "--pwd",
+            metavar="PATH",
+            help="Working directory passed to runtime command.",
+        ),
+        runner: str | None = typer.Option(
+            None,
+            "--runner",
+            metavar="PATH",
+            help="Runtime executable path or command name.",
+        ),
+        dryRun: bool = typer.Option(
+            False,
+            "--dry-run",
+            help="Print the resolved command without running it.",
+        ),
+        verbose: bool | None = typer.Option(
+            None,
+            "--verbose/--no-verbose",
+            help="Enable or disable verbose wrapper logs.",
+        ),
+        apptainerFlags: list[str] | None = typer.Option(
+            None,
+            "--apptainer-flag",
+            metavar="FLAG",
+            help="Extra Apptainer flag (repeatable).",
+        ),
+        dockerFlags: list[str] | None = typer.Option(
+            None,
+            "--docker-flag",
+            metavar="FLAG",
+            help="Extra Docker flag (repeatable).",
+        ),
+        envVars: list[str] | None = typer.Option(
+            None,
+            "--env",
+            metavar="KEY=VALUE",
+            help="Environment variable assignment for the process/container (repeatable).",
+        ),
+        showConfig: bool = typer.Option(
+            False,
+            "--show-config",
+            help="Print effective kub-cli configuration as JSON.",
+        ),
+        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)
+
+        executeWrapperCommand(
+            appName=appName,
+            ctx=ctx,
+            runtime=runtime,
+            image=image,
+            bind=bind or [],
+            pwd=pwd,
+            runner=runner,
+            dryRun=dryRun,
+            verbose=verbose,
+            apptainerFlags=apptainerFlags or [],
+            dockerFlags=dockerFlags or [],
+            envVars=envVars or [],
+            showConfig=showConfig,
+        )
+
+    return app
+
+
+def createMetaApp() -> typer.Typer:
+    app = typer.Typer(
+        add_completion=False,
+        no_args_is_help=False,
+        help="kub-cli meta command.",
+    )
+
+    @app.callback(invoke_without_command=True)
+    def meta(
+        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(
+                "kub-cli thin wrapper. Use: kub-dataset, kub-simulate, kub-dashboard, kub-img."
+            )
+
+    @app.command("bump")
+    def bumpCommand(
+        part: str = typer.Argument(
+            "patch",
+            metavar="PART",
+            help="Semantic version part to bump: major, minor, patch.",
+        ),
+        toVersion: str | None = typer.Option(
+            None,
+            "--to",
+            metavar="VERSION",
+            help="Set an explicit semantic version (MAJOR.MINOR.PATCH).",
+        ),
+        projectRoot: Path = typer.Option(
+            Path("."),
+            "--project-root",
+            metavar="PATH",
+            help="Project root containing pyproject.toml.",
+        ),
+        dryRun: bool = typer.Option(
+            False,
+            "--dry-run",
+            help="Print planned version changes without writing files.",
+        ),
+    ) -> None:
+        try:
+            result = bumpProjectVersion(
+                projectRoot=projectRoot.resolve(),
+                part=part,
+                toVersion=toVersion,
+                dryRun=dryRun,
+            )
+        except KubCliError as error:
+            typer.secho(str(error), fg=typer.colors.RED, err=True)
+            raise typer.Exit(code=error.exit_code) from error
+
+        if result.changed:
+            action = "Planned" if dryRun else "Updated"
+            typer.echo(f"{action} version: {result.oldVersion} -> {result.newVersion}")
+        else:
+            typer.echo(f"Version unchanged: {result.newVersion}")
+
+        typer.echo(f"pyproject: {result.pyprojectPath}")
+        typer.echo(f"fallback: {result.initPath}")
+
+    return app
+
+
+datasetApp = createWrapperApp(
+    appName="kub-dataset",
+    helpText=(
+        "Run the kub-dataset app inside the configured container runtime "
+        "(Apptainer/Docker)."
+    ),
+)
+simulateApp = createWrapperApp(
+    appName="kub-simulate",
+    helpText=(
+        "Run the kub-simulate app inside the configured container runtime "
+        "(Apptainer/Docker)."
+    ),
+)
+dashboardApp = createWrapperApp(
+    appName="kub-dashboard",
+    helpText=(
+        "Run the kub-dashboard app inside the configured container runtime "
+        "(Apptainer/Docker)."
+    ),
+)
+metaApp = createMetaApp()
+
+
+def datasetMain() -> None:
+    datasetApp(prog_name="kub-dataset")
+
+
+def simulateMain() -> None:
+    simulateApp(prog_name="kub-simulate")
+
+
+def dashboardMain() -> None:
+    dashboardApp(prog_name="kub-dashboard")
+
+
+def metaMain() -> None:
+    metaApp(prog_name="kub-cli")

kub_cli/commands.py

@@ -0,0 +1,164 @@
+# SPDX-FileCopyrightText: 2026 University of Strasbourg
+# SPDX-FileContributor: Christophe Prud'homme
+# SPDX-FileContributor: Cemosis
+# SPDX-License-Identifier: Apache-2.0
+
+"""High-level command orchestration for kub-cli wrappers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from .config import KubConfig, KubConfigOverrides, loadKubConfig
+from .errors import ConfigError
+from .img_integration import (
+    KubImgCommandRunner,
+    buildKubImgInfoRequest,
+    buildKubImgPullRequest,
+)
+from .logging_utils import configureLogging
+from .runtime import KubAppRunner
+
+
+@dataclass(frozen=True)
+class WrapperOptions:
+    """Wrapper-specific options parsed from the CLI layer."""
+
+    runtime: str | None = None
+    image: str | None = None
+    binds: tuple[str, ...] = ()
+    pwd: str | None = None
+    runner: str | None = None
+    dryRun: bool = False
+    verbose: bool | None = None
+    apptainerFlags: tuple[str, ...] = ()
+    dockerFlags: tuple[str, ...] = ()
+    envVars: tuple[str, ...] = ()
+    showConfig: bool = False
+
+
+def runWrapperCommand(
+    *,
+    appName: str,
+    forwardedArgs: Sequence[str],
+    options: WrapperOptions,
+    cwd: Path | None = None,
+    env: Mapping[str, str] | None = None,
+    userConfigPath: Path | None = None,
+) -> int:
+    """Resolve config and execute one wrapped in-container app."""
+
+    effectiveConfig = resolveEffectiveConfig(
+        options=options,
+        cwd=cwd,
+        env=env,
+        userConfigPath=userConfigPath,
+    )
+
+    configureLogging(effectiveConfig.verbose)
+
+    if options.showConfig:
+        print(json.dumps(effectiveConfig.toDict(), indent=2, sort_keys=True))
+        if not forwardedArgs and not options.dryRun:
+            return 0
+
+    runner = KubAppRunner(config=effectiveConfig)
+    return runner.run(appName=appName, forwardedArgs=forwardedArgs, dryRun=options.dryRun)
+
+
+def pullSelectedRuntimeImage(
+    *,
+    options: WrapperOptions,
+    cwd: Path | None = None,
+    env: Mapping[str, str] | None = None,
+    userConfigPath: Path | None = None,
+) -> int:
+    """Invoke kub-img pull for the runtime/image selected by config precedence."""
+
+    effectiveConfig = resolveEffectiveConfig(
+        options=options,
+        cwd=cwd,
+        env=env,
+        userConfigPath=userConfigPath,
+    )
+    configureLogging(effectiveConfig.verbose)
+
+    request = buildKubImgPullRequest(effectiveConfig)
+    kubImgRunner = KubImgCommandRunner(verbose=effectiveConfig.verbose)
+    return kubImgRunner.pullImage(request, dryRun=options.dryRun)
+
+
+def inspectSelectedRuntimeImage(
+    *,
+    options: WrapperOptions,
+    cwd: Path | None = None,
+    env: Mapping[str, str] | None = None,
+    userConfigPath: Path | None = None,
+) -> dict[str, Any]:
+    """Invoke kub-img info for the runtime/image selected by config precedence."""
+
+    effectiveConfig = resolveEffectiveConfig(
+        options=options,
+        cwd=cwd,
+        env=env,
+        userConfigPath=userConfigPath,
+    )
+    configureLogging(effectiveConfig.verbose)
+
+    request = buildKubImgInfoRequest(effectiveConfig)
+    kubImgRunner = KubImgCommandRunner(verbose=effectiveConfig.verbose)
+    return kubImgRunner.inspectImageInfo(request)
+
+
+def resolveEffectiveConfig(
+    *,
+    options: WrapperOptions,
+    cwd: Path | None = None,
+    env: Mapping[str, str] | None = None,
+    userConfigPath: Path | None = None,
+) -> KubConfig:
+    """Build the effective config from defaults, files, env, then CLI overrides."""
+
+    overrideEnv = parseEnvAssignments(options.envVars)
+    overrides = KubConfigOverrides(
+        runtime=options.runtime,
+        image=options.image,
+        binds=options.binds,
+        workdir=options.pwd,
+        runner=options.runner,
+        verbose=options.verbose,
+        apptainerFlags=options.apptainerFlags,
+        dockerFlags=options.dockerFlags,
+        env=overrideEnv,
+    )
+
+    return loadKubConfig(
+        cwd=cwd,
+        env=env,
+        overrides=overrides,
+        userConfigPath=userConfigPath,
+    )
+
+
+def parseEnvAssignments(assignments: Sequence[str]) -> dict[str, str]:
+    envMapping: dict[str, str] = {}
+
+    for entry in assignments:
+        if "=" not in entry:
+            raise ConfigError(
+                f"Invalid --env assignment '{entry}'. Expected KEY=VALUE syntax."
+            )
+
+        key, value = entry.split("=", maxsplit=1)
+        normalizedKey = key.strip()
+        if not normalizedKey:
+            raise ConfigError(
+                f"Invalid --env assignment '{entry}'. Environment key cannot be empty."
+            )
+
+        envMapping[normalizedKey] = value
+
+    return envMapping