dockhand-cli 0.3.1__py3-none-any.whl

dockhand/__init__.py

@@ -0,0 +1,335 @@
+from typing import Annotated, List
+
+import typer
+
+from dockhand.build import execute_build
+from dockhand.client import get_client
+from dockhand.config import DockerResubmitConfig, cli_config
+from dockhand.constants import CONFIG_FILENAME
+from dockhand.download import execute_download
+from dockhand.history import execute_history
+from dockhand.manage import execute_logs, execute_prune, execute_queue, execute_remove, execute_stats, execute_stop
+from dockhand.queue import ts_make_urgent
+from dockhand.resubmit import execute_resubmit
+from dockhand.submit import execute_submit
+from dockhand.tunnel import execute_tunnel
+from dockhand.volumes import execute_volumes
+
+__version__ = "0.2.0"
+
+cli = typer.Typer(pretty_exceptions_show_locals=False)
+
+
+class DockerDefault:
+    def __init__(self, key: str):
+        self.key = key
+
+    def __call__(self):
+        return getattr(cli_config.docker, self.key, None)
+
+    def __str__(self):
+        value = getattr(cli_config.docker, self.key, None)
+        return str(value)
+
+
+class SyncDefault:
+    def __call__(self):
+        return cli_config.sync
+
+    def __str__(self):
+        return str(cli_config.sync)
+
+
+def profile_callback(profile: str | None):
+    if profile is not None:
+        cli_config.load_profile(profile)
+
+
+def version_callback(value: bool):
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@cli.callback()
+def main(
+    profile: Annotated[
+        str, typer.Option("--profile", callback=profile_callback, help="Optional profile from config.")
+    ] = None,
+    version: Annotated[bool, typer.Option("--version", callback=version_callback)] = False,
+):
+    pass
+
+
+@cli.command()
+def submit(
+    commands: List[str],
+    imagename: Annotated[str, typer.Option(default_factory=DockerDefault("imagename"))],
+    gpus: Annotated[str, typer.Option(default_factory=DockerDefault("gpus"))],
+    sync: Annotated[bool, typer.Option(default_factory=SyncDefault())],
+    ports: Annotated[List[str], typer.Option("-p")] = [],
+    urgent: Annotated[bool, typer.Option("--urgent", help="Move to front of queue.")] = False,
+    slots: Annotated[int, typer.Option("--slots", help="Queue slots to reserve (e.g. number of CPUs).")] = None,
+):
+    """Sync code and queue a container run with the given command(s)."""
+    cli_config.check_docker(msg=f"docker requires a Docker configuration in '{CONFIG_FILENAME}'")
+    execute_submit(
+        cli_config.docker,
+        commands,
+        sync=sync,
+        imagename=imagename,
+        gpus=gpus,
+        ports=ports or None,
+        urgent=urgent,
+        slots=slots,
+    )
+
+
+@cli.command()
+def run(
+    commands: List[str],
+    imagename: Annotated[str, typer.Option(default_factory=DockerDefault("imagename"))],
+    gpus: Annotated[str, typer.Option(default_factory=DockerDefault("gpus"))],
+    ports: Annotated[List[str], typer.Option("-p")] = [],
+    urgent: Annotated[bool, typer.Option("--urgent", help="Move to front of queue.")] = False,
+    slots: Annotated[int, typer.Option("--slots", help="Queue slots to reserve (e.g. number of CPUs).")] = None,
+):
+    """Queue a container run without syncing code first."""
+    cli_config.check_docker(msg=f"docker requires a Docker configuration in '{CONFIG_FILENAME}'")
+    execute_submit(
+        cli_config.docker, commands, sync=False,
+        imagename=imagename, gpus=gpus, ports=ports or None, urgent=urgent, slots=slots,
+    )
+
+
+@cli.command()
+def install(
+    dockerfile: Annotated[str, typer.Option(default_factory=DockerDefault("dockerfile"))],
+    imagename: Annotated[str, typer.Option(default_factory=DockerDefault("imagename"))],
+    sync: Annotated[bool, typer.Option(default_factory=SyncDefault())],
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Show docker build output.")] = False,
+):
+    """Install (build) the Docker image."""
+    cli_config.check_docker(msg=f"docker requires a Docker configuration in '{CONFIG_FILENAME}'")
+    execute_build(cli_config.docker, sync=sync, dockerfile=dockerfile, imagename=imagename, verbose=verbose)
+
+
+@cli.command()
+def logs(
+    id: Annotated[
+        str | None,
+        typer.Argument(help="Job ID. Defaults to last job."),
+    ] = None,
+    n: int | None = None,
+    follow: Annotated[bool, typer.Option("--follow", "-f", help="Stream output as the job runs.")] = False,
+):
+    """Show logs from a job (defaults to last)."""
+    cli_config.check_docker(msg=f"docker requires a Docker configuration in '{CONFIG_FILENAME}'")
+    job_id = int(id) if id is not None else None
+    execute_logs(cli_config.docker, job_id=job_id, n=n, follow=follow)
+
+
+@cli.command()
+def stop(
+    id: Annotated[
+        str | None,
+        typer.Argument(help="Job ID. Defaults to last running job."),
+    ] = None,
+):
+    """Stop a running job (defaults to last)."""
+    cli_config.check_docker(msg=f"docker requires a Docker configuration in '{CONFIG_FILENAME}'")
+    job_id = int(id) if id is not None else None
+    execute_stop(cli_config.docker, job_id=job_id)
+
+
+@cli.command()
+def jobs(
+    all: Annotated[
+        bool, typer.Option("--all", help="Show every job, including finished/failed (no 30-job limit).")
+    ] = False,
+    queue: Annotated[
+        bool,
+        typer.Option(
+            "--queue", help="Show the host's whole task-spooler queue, including other projects' jobs."
+        ),
+    ] = False,
+):
+    """List jobs, newest first (defaults to the last 30 active jobs)."""
+    cli_config.check_docker(msg=f"docker requires a Docker configuration in '{CONFIG_FILENAME}'")
+    if queue:
+        execute_queue(cli_config.docker)
+        return
+    execute_stats(cli_config.docker, all=all)
+
+
+@cli.command()
+def urgent(
+    id: Annotated[
+        str | None,
+        typer.Argument(help="Job ID to promote to the front of the queue. Defaults to last job."),
+    ] = None,
+):
+    """Promote a queued job to the front of the queue."""
+    cli_config.check_docker(msg=f"docker requires a Docker configuration in '{CONFIG_FILENAME}'")
+    from dockhand.history import get_history_entry, load_history
+    from dockhand.transport import entry_handle, transport_for_entry
+
+    if id is None:
+        history = load_history()
+        if not history:
+            typer.echo("No job history found. Provide a job ID.")
+            raise typer.Exit(1)
+        entry = history[-1]
+    else:
+        entry = get_history_entry(int(id))
+        if entry is None:
+            typer.echo(f"Job #{id} not found in history.")
+            raise typer.Exit(1)
+
+    local_id = entry["local_id"]
+    if transport_for_entry(entry).name != "task_spooler":
+        typer.echo(f"Job #{local_id} was not queued — 'urgent' only applies to queued jobs.")
+        raise typer.Exit(1)
+
+    with get_client() as client:
+        if ts_make_urgent(client, entry_handle(entry), cwd=cli_config.remote_path):
+            typer.echo(f"Job #{local_id} moved to front of queue.")
+        else:
+            typer.echo(f"Failed to promote job #{local_id}. It may have already started or finished.")
+            raise typer.Exit(1)
+
+
+@cli.command()
+def history():
+    """Show history of past Docker runs."""
+    cli_config.check_docker(msg=f"docker requires a Docker configuration in '{CONFIG_FILENAME}'")
+    execute_history(cli_config.docker)
+
+
+@cli.command()
+def volumes(
+    id: Annotated[
+        str | None,
+        typer.Argument(help="Job ID to use mounts from. Defaults to config."),
+    ] = None,
+    depth: Annotated[
+        int | None,
+        typer.Option("--depth", help="Maximum directory depth to display."),
+    ] = None,
+):
+    """List the full container filesystem as a tree."""
+    cli_config.check_docker(msg=f"docker requires a Docker configuration in '{CONFIG_FILENAME}'")
+    imagename, override_volumes = _resolve_volumes_overrides(id)
+    execute_volumes(cli_config.docker, depth=depth, imagename=imagename, volumes=override_volumes)
+
+
+@cli.command()
+def download(
+    path: Annotated[
+        str | None,
+        typer.Argument(help="Workdir-relative path to download (as shown by volumes)"),
+    ] = None,
+    local_path: Annotated[
+        str | None,
+        typer.Option("--local-path", "-l", help="Local destination path (defaults to project root)"),
+    ] = None,
+    list_only: Annotated[
+        bool,
+        typer.Option("--list", help="List files in docker-mounted volumes (same as volumes)"),
+    ] = False,
+    depth: Annotated[
+        int | None,
+        typer.Option("--depth", help="Maximum directory depth to display (only applies with --list)."),
+    ] = None,
+    id: Annotated[
+        str | None,
+        typer.Option("--id", help="Job ID to use mounts from (only applies with --list)."),
+    ] = None,
+):
+    """Download a file from a docker volume by its workdir-relative path.
+
+    Files are downloaded preserving their directory structure relative to project root."""
+    cli_config.check_docker(msg=f"docker requires a Docker configuration in '{CONFIG_FILENAME}'")
+    if list_only:
+        imagename, override_volumes = _resolve_volumes_overrides(id)
+        execute_volumes(cli_config.docker, depth=depth, imagename=imagename, volumes=override_volumes)
+        return
+    if path is None:
+        typer.echo("Error: Missing argument 'PATH'. Use --list to see available files.")
+        raise typer.Exit(1)
+    execute_download(cli_config.docker, path=path, local_path=local_path)
+
+
+@cli.command()
+def resubmit(
+    id: Annotated[
+        str | None,
+        typer.Argument(help="Job ID to resubmit. Defaults to last."),
+    ] = None,
+    commands: List[str] | None = None,
+    imagename: str | None = None,
+    gpus: str | None = None,
+):
+    """Resubmit a previous job (defaults to latest). Optionally with new parameters."""
+    cli_config.check_docker(msg=f"docker requires a Docker configuration in '{CONFIG_FILENAME}'")
+    config = DockerResubmitConfig(
+        container_id=id,
+        commands=commands,
+        imagename=imagename,
+        gpus=gpus,
+    )
+    execute_resubmit(cli_config.docker, config)
+
+
+@cli.command()
+def remove(
+    ids: Annotated[
+        List[str],
+        typer.Argument(help="Job IDs to remove from queue. Defaults to last queued job."),
+    ] = None,
+    from_history: bool = False,
+):
+    """Remove queued job(s) that haven't started yet (defaults to last)."""
+    cli_config.check_docker(msg=f"docker requires a Docker configuration in '{CONFIG_FILENAME}'")
+    job_ids = [int(i) for i in ids] if ids else None
+    execute_remove(cli_config.docker, job_ids=job_ids, from_history=from_history)
+
+
+@cli.command()
+def prune(
+    yes: Annotated[bool, typer.Option("--yes", "-y", help="Skip the confirmation prompt.")] = False,
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Show what would be removed without removing.")] = False,
+):
+    """Remove baked images no longer referenced by an active job."""
+    cli_config.check_docker(msg=f"docker requires a Docker configuration in '{CONFIG_FILENAME}'")
+    execute_prune(cli_config.docker, yes=yes, dry_run=dry_run)
+
+
+@cli.command()
+def tunnel(
+    container_id: str | None = None,
+    ports: Annotated[List[str], typer.Option("-p")] = [],
+):
+    """Forward docker container ports to localhost via SSH tunnel.
+
+    Defaults to ports from the last (or specified) run. Use -p to override."""
+    cli_config.check_docker(msg=f"docker requires a Docker configuration in '{CONFIG_FILENAME}'")
+    execute_tunnel(container_id=container_id, ports=ports or None)
+
+
+def _resolve_volumes_overrides(id: str | None) -> tuple[str | None, list | None]:
+    """Look up imagename and volumes from history for a given job ID."""
+    if id is None:
+        return None, None
+    from dockhand.history import get_history_entry
+
+    entry = get_history_entry(int(id))
+    if entry is None:
+        typer.echo(f"Warning: Job #{id} not found in history — using config defaults.")
+        return None, None
+    cfg = entry["config"]
+    return cfg.get("imagename"), cfg.get("volumes")
+
+
+if __name__ == "__main__":
+    cli()

dockhand/build.py

@@ -0,0 +1,35 @@
+"""Docker image building."""
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from dockhand.client import get_client
+from dockhand.config import DockerConfig, cli_config
+from dockhand.error import error_and_exit
+from dockhand.sync import execute_sync
+
+
+def execute_build(
+    config: DockerConfig,
+    sync: bool,
+    dockerfile: str | None = None,
+    imagename: str | None = None,
+    verbose: bool = False,
+):
+    """Build the Docker image."""
+    if sync:
+        execute_sync(confirm_changes=True)
+
+    dockerfile = dockerfile or config.dockerfile
+    imagename = imagename or config.imagename
+    cmd = f"docker build -f {dockerfile} -t {imagename} ."
+
+    with get_client() as client:
+        if verbose:
+            returncode, _ = client.run(cmd, cwd=cli_config.remote_path, capture=False)
+        else:
+            with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}")) as progress:
+                task = progress.add_task(description="Building image", total=None)
+                returncode, _ = client.run(cmd, cwd=cli_config.remote_path, capture=True)
+                progress.update(task, completed=True)
+
+    if returncode != 0:
+        error_and_exit(f"Build command failed with return code {returncode}.")

dockhand/client/__init__.py

@@ -0,0 +1,38 @@
+import socket
+
+from dockhand.client.base import Client
+from dockhand.client.local import LocalClient
+from dockhand.client.ssh import SSHClient
+from dockhand.config import cli_config
+
+
+def _is_localhost(hostname: str) -> bool:
+    """Check if hostname is localhost or resolves to 127.0.0.1/::1."""
+    if hostname in ("localhost", "127.0.0.1", "::1"):
+        return True
+    try:
+        # Resolve hostname to IP and check if it's loopback
+        ip = socket.gethostbyname(hostname)
+        return ip.startswith("127.")
+    except (socket.gaierror, socket.error):
+        # If resolution fails, assume it's not localhost
+        return False
+
+
+def get_client() -> Client:
+    # Check if hostname is localhost or not set - use local client
+    if cli_config.ssh is None or _is_localhost(cli_config.ssh.hostname):
+        return LocalClient()
+    else:
+        return SSHClient()
+
+
+def get_client_for_host(hostname: str) -> Client:
+    """Return a client connected to a specific host (e.g. from job history).
+
+    Uses SSH credentials from config but overrides the hostname. Falls back
+    to LocalClient if the hostname resolves to localhost.
+    """
+    if _is_localhost(hostname):
+        return LocalClient()
+    return SSHClient(hostname=hostname)

dockhand/client/base.py

@@ -0,0 +1,37 @@
+import abc
+
+
+class Client(abc.ABC):
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def __del__(self):
+        self.close()
+
+    @abc.abstractmethod
+    def run(self, command: str, cwd: str | None = None, capture: bool = False) -> tuple[int, str]:
+        """Run a command. When capture=True, suppress live output to the terminal."""
+        pass
+
+    @abc.abstractmethod
+    def close(self):
+        pass
+
+    @abc.abstractmethod
+    def remove(self, path: str):
+        pass
+
+    @abc.abstractmethod
+    def exists(self, path: str) -> bool:
+        pass
+
+    @abc.abstractmethod
+    def load(self, path: str) -> str:
+        pass
+
+    @abc.abstractmethod
+    def save(self, path: str, contents: str):
+        pass

dockhand/client/local.py

@@ -0,0 +1,45 @@
+import os
+import subprocess
+
+import typer
+
+from dockhand.client.base import Client
+
+
+class LocalClient(Client):
+    def close(self):
+        pass
+
+    def run(self, command: str, cwd: str | None = None, capture: bool = False) -> tuple[int, str]:
+        # Ignore the cwd parameter since we assume that the user is running the command from the correct directory.
+        outputs = []
+        with subprocess.Popen(
+            command,
+            shell=True,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            bufsize=1,
+            universal_newlines=True,
+        ) as process:
+            for line in process.stdout:
+                if not capture:
+                    typer.echo(line, nl=False)
+                outputs.append(line)
+            returncode = process.wait()
+        output = "".join(outputs)
+        return returncode, output
+
+    def remove(self, path: str):
+        os.remove(path)
+
+    def exists(self, path):
+        return os.path.exists(path)
+
+    def load(self, path: str) -> str:
+        with open(path, "r") as f:
+            return f.read()
+
+    def save(self, path: str, contents: str):
+        with open(path, "w") as f:
+            f.write(contents)

dockhand/client/ssh.py

@@ -0,0 +1,53 @@
+import fabric
+
+from dockhand.client.base import Client
+from dockhand.config import cli_config
+from dockhand.constants import CONFIG_FILENAME
+
+
+class SSHClient(Client):
+    def __init__(self, hostname: str | None = None):
+        super().__init__()
+
+        cli_config.check_ssh(msg=f"Please provide a SSH configuration in '{CONFIG_FILENAME}'.")
+
+        self.client = fabric.Connection(
+            host=hostname or cli_config.ssh.hostname,
+            user=cli_config.ssh.user,
+            connect_kwargs={"key_filename": cli_config.ssh.identityfile},
+        )
+
+    def close(self):
+        self.client.close()
+
+    def run(self, command: str, cwd: str | None = None, capture: bool = False) -> tuple[int, str]:
+        command = f'bash -l -c "{command}"'
+        hide = "both" if capture else None
+        if cwd is not None:
+            with self.client.cd(cwd):
+                result = self.client.run(command, warn=True, hide=hide)
+        else:
+            result = self.client.run(command, warn=True, hide=hide)
+        return result.exited, result.stdout
+
+    def remove(self, path: str):
+        sftp = self.client.sftp()
+        sftp.remove(path)
+
+    def exists(self, path):
+        sftp = self.client.sftp()
+        try:
+            sftp.stat(path)
+            return True
+        except FileNotFoundError:
+            return False
+
+    def load(self, path: str) -> str:
+        sftp = self.client.sftp()
+        with sftp.file(path, "r") as f:
+            return f.read().decode("utf-8")
+
+    def save(self, path: str, contents: str):
+        sftp = self.client.sftp()
+        with sftp.file(path, "w") as f:
+            f.write(contents)