hpc-runner 0.2.0__py3-none-any.whl

hpc_runner/__init__.py

@@ -0,0 +1,57 @@
+"""hpc-runner: HPC job submission across multiple schedulers."""
+
+try:
+    from hpc_runner._version import __version__
+except ImportError:
+    __version__ = "0.0.0.dev0"
+
+from hpc_runner.core.config import HPCConfig, get_config, load_config, reload_config
+from hpc_runner.core.exceptions import (
+    ConfigError,
+    ConfigNotFoundError,
+    HPCToolsError,
+    JobNotFoundError,
+    SchedulerError,
+    SubmissionError,
+    ValidationError,
+)
+from hpc_runner.core.job import Job
+from hpc_runner.core.job_array import JobArray
+from hpc_runner.core.resources import Resource, ResourceSet
+from hpc_runner.core.result import ArrayJobResult, JobResult, JobStatus
+from hpc_runner.schedulers import get_scheduler, list_schedulers, register_scheduler
+from hpc_runner.workflow import DependencyType, Pipeline, PipelineJob
+
+__all__ = [
+    # Version
+    "__version__",
+    # Core
+    "Job",
+    "JobArray",
+    "JobResult",
+    "ArrayJobResult",
+    "JobStatus",
+    "Resource",
+    "ResourceSet",
+    # Config
+    "load_config",
+    "get_config",
+    "reload_config",
+    "HPCConfig",
+    # Schedulers
+    "get_scheduler",
+    "register_scheduler",
+    "list_schedulers",
+    # Workflow
+    "Pipeline",
+    "PipelineJob",
+    "DependencyType",
+    # Exceptions
+    "HPCToolsError",
+    "SchedulerError",
+    "SubmissionError",
+    "JobNotFoundError",
+    "ConfigError",
+    "ConfigNotFoundError",
+    "ValidationError",
+]

hpc_runner/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
+
+__commit_id__ = commit_id = None

hpc_runner/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI for hpc-tools."""

hpc_runner/cli/cancel.py

@@ -0,0 +1,38 @@
+"""Cancel command - cancel running jobs."""
+
+import rich_click as click
+from rich.console import Console
+
+from hpc_runner.cli.main import Context, pass_context
+
+console = Console()
+
+
+@click.command()
+@click.argument("job_id")
+@click.option("--force", is_flag=True, help="Cancel without confirmation")
+@pass_context
+def cancel(
+    ctx: Context,
+    job_id: str,
+    force: bool,
+) -> None:
+    """Cancel a job.
+
+    JOB_ID is the job ID to cancel.
+    """
+    from hpc_runner.schedulers import get_scheduler
+
+    scheduler = get_scheduler(ctx.scheduler)
+
+    if not force:
+        if not click.confirm(f"Cancel job {job_id}?"):
+            console.print("[yellow]Cancelled[/yellow]")
+            return
+
+    success = scheduler.cancel(job_id)
+
+    if success:
+        console.print(f"[green]Job {job_id} cancelled[/green]")
+    else:
+        console.print(f"[red]Failed to cancel job {job_id}[/red]")

hpc_runner/cli/config.py

@@ -0,0 +1,109 @@
+"""Config command - manage configuration."""
+
+from pathlib import Path
+
+import rich_click as click
+from rich.console import Console
+from rich.syntax import Syntax
+
+from hpc_runner.cli.main import Context, pass_context
+
+console = Console()
+
+
+@click.group()
+def config_cmd() -> None:
+    """Manage configuration."""
+    pass
+
+
+@config_cmd.command("show")
+@pass_context
+def show(ctx: Context) -> None:
+    """Show current configuration."""
+    from hpc_runner.core.config import find_config_file
+
+    config_path = ctx.config_path or find_config_file()
+
+    if config_path is None:
+        console.print("[yellow]No configuration file found[/yellow]")
+        console.print("Using default settings")
+        console.print("\nSearch locations:")
+        console.print("  1. ./hpc-tools.toml")
+        console.print("  2. ./pyproject.toml [tool.hpc-tools]")
+        console.print("  3. <git root>/hpc-tools.toml")
+        console.print("  4. ~/.config/hpc-tools/config.toml")
+        return
+
+    console.print(f"[bold]Config file:[/bold] {config_path}")
+    console.print()
+
+    # Read and display the config file
+    content = config_path.read_text()
+    syntax = Syntax(content, "toml", theme="monokai", line_numbers=True)
+    console.print(syntax)
+
+
+@config_cmd.command("init")
+@click.option("--global", "global_config", is_flag=True, help="Create in ~/.config/hpc-tools/")
+@pass_context
+def init(ctx: Context, global_config: bool) -> None:
+    """Create a new configuration file."""
+    if global_config:
+        config_dir = Path.home() / ".config" / "hpc-tools"
+        config_dir.mkdir(parents=True, exist_ok=True)
+        config_path = config_dir / "config.toml"
+    else:
+        config_path = Path.cwd() / "hpc-tools.toml"
+
+    if config_path.exists():
+        if not click.confirm(f"{config_path} already exists. Overwrite?"):
+            console.print("[yellow]Cancelled[/yellow]")
+            return
+
+    # Write default config
+    default_config = '''# hpc-tools configuration
+
+[defaults]
+# Default job settings
+cpu = 1
+mem = "4G"
+time = "1:00:00"
+# queue = "batch"
+
+# Modules to always load
+modules = []
+
+[schedulers.sge]
+# SGE-specific settings
+parallel_environment = "smp"
+memory_resource = "mem_free"
+time_resource = "h_rt"
+merge_output = true
+
+# Tool-specific configurations
+# [tools.python]
+# modules = ["python/3.11"]
+
+# Job type configurations
+# [types.gpu]
+# queue = "gpu"
+# resources = [{name = "gpu", value = 1}]
+'''
+
+    config_path.write_text(default_config)
+    console.print(f"[green]Created {config_path}[/green]")
+
+
+@config_cmd.command("path")
+@pass_context
+def path(ctx: Context) -> None:
+    """Show path to active configuration file."""
+    from hpc_runner.core.config import find_config_file
+
+    config_path = ctx.config_path or find_config_file()
+
+    if config_path:
+        console.print(str(config_path))
+    else:
+        console.print("[yellow]No configuration file found[/yellow]")

hpc_runner/cli/main.py

@@ -0,0 +1,76 @@
+"""Main CLI entry point using rich-click."""
+
+from pathlib import Path
+
+import rich_click as click
+from rich.console import Console
+
+# Configure rich-click
+click.rich_click.SHOW_ARGUMENTS = True
+
+# Global console for Rich output
+console = Console()
+
+# Context object to pass state between commands
+class Context:
+    def __init__(self) -> None:
+        self.config_path: Path | None = None
+        self.scheduler: str | None = None
+        self.verbose: bool = False
+
+pass_context = click.make_pass_decorator(Context, ensure=True)
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.option(
+    "--config",
+    type=click.Path(exists=True, path_type=Path),
+    help="Path to configuration file",
+)
+@click.option(
+    "--scheduler",
+    type=str,
+    help="Force scheduler (sge, slurm, pbs, local)",
+)
+@click.option(
+    "--verbose",
+    is_flag=True,
+    help="Enable verbose output",
+)
+@click.version_option(package_name="hpc-runner")
+@pass_context
+def cli(ctx: Context, config: Path | None, scheduler: str | None, verbose: bool) -> None:
+    """HPC job submission tool.
+
+    Submit and manage jobs across different HPC schedulers (SGE, Slurm, PBS)
+    with a unified interface.
+
+    Any unrecognized short options are passed directly to the underlying
+    scheduler, allowing use of native flags like -N, -n, -q, etc.
+    """
+    ctx.config_path = config
+    ctx.scheduler = scheduler
+    ctx.verbose = verbose
+
+
+# Import and register subcommands (must be after cli is defined to avoid circular imports)
+from hpc_runner.cli.cancel import cancel  # noqa: E402
+from hpc_runner.cli.config import config_cmd  # noqa: E402
+from hpc_runner.cli.monitor import monitor  # noqa: E402
+from hpc_runner.cli.run import run  # noqa: E402
+from hpc_runner.cli.status import status  # noqa: E402
+
+cli.add_command(run)
+cli.add_command(status)
+cli.add_command(cancel)
+cli.add_command(config_cmd, name="config")
+cli.add_command(monitor)
+
+
+def main() -> None:
+    """Entry point for console script."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

hpc_runner/cli/monitor.py

@@ -0,0 +1,30 @@
+"""CLI command for launching the interactive job monitor."""
+
+import rich_click as click
+
+
+@click.command()
+@click.option(
+    "--refresh",
+    "-r",
+    default=10,
+    type=int,
+    help="Auto-refresh interval in seconds",
+)
+def monitor(refresh: int) -> None:
+    """Launch interactive job monitor TUI.
+
+    Opens a terminal UI for monitoring HPC jobs across schedulers.
+    Shows active and completed jobs with filtering and search.
+
+    \b
+    Keyboard shortcuts:
+      q      Quit
+      r      Manual refresh
+      u      Toggle user filter (me/all)
+      Tab    Switch tabs
+    """
+    from hpc_runner.tui import HpcMonitorApp
+
+    app = HpcMonitorApp(refresh_interval=refresh)
+    app.run()

hpc_runner/cli/run.py

@@ -0,0 +1,292 @@
+"""Run command - submit jobs to the scheduler."""
+
+from typing import TYPE_CHECKING
+
+import rich_click as click
+from rich.console import Console
+from rich.panel import Panel
+from rich.syntax import Syntax
+
+from hpc_runner.cli.main import Context, pass_context
+
+if TYPE_CHECKING:
+    from hpc_runner.core.job import Job
+
+console = Console()
+
+
+@click.command(
+    context_settings={
+        "ignore_unknown_options": True,
+        "allow_interspersed_args": True,
+    }
+)
+@click.argument("args", nargs=-1, type=click.UNPROCESSED)
+# All hpc-runner options are long-form only
+@click.option("--job-name", "job_name", help="Job name")
+@click.option("--cpu", type=int, help="Number of CPUs")
+@click.option("--mem", help="Memory requirement (e.g., 16G)")
+@click.option("--time", "time_limit", help="Time limit (e.g., 4:00:00)")
+@click.option("--queue", help="Queue/partition name")
+@click.option("--nodes", type=int, help="Number of nodes (MPI jobs)")
+@click.option("--ntasks", type=int, help="Number of tasks (MPI jobs)")
+@click.option("--directory", type=click.Path(exists=True), help="Working directory")
+@click.option("--job-type", "job_type", help="Job type from config")
+@click.option("--module", "modules", multiple=True, help="Modules to load (repeatable)")
+@click.option("--stderr", help="Separate stderr file (default: merged)")
+@click.option("--output", help="Stdout file path pattern")
+@click.option("--array", help="Array job specification (e.g., 1-100)")
+@click.option("--depend", help="Job dependency specification")
+@click.option("--inherit-env/--no-inherit-env", "inherit_env", default=True, help="Inherit environment variables")
+@click.option("--interactive", is_flag=True, help="Run interactively (srun/qrsh)")
+@click.option("--local", is_flag=True, help="Run locally (no scheduler)")
+@click.option("--dry-run", "dry_run", is_flag=True, help="Show what would be submitted")
+@click.option("--wait", is_flag=True, help="Wait for job completion")
+@click.option("--keep-script", "keep_script", is_flag=True, help="Keep job script for debugging")
+@pass_context
+def run(
+    ctx: Context,
+    args: tuple[str, ...],
+    job_name: str | None,
+    cpu: int | None,
+    mem: str | None,
+    time_limit: str | None,
+    queue: str | None,
+    nodes: int | None,
+    ntasks: int | None,
+    directory: str | None,
+    job_type: str | None,
+    modules: tuple[str, ...],
+    stderr: str | None,
+    output: str | None,
+    array: str | None,
+    depend: str | None,
+    inherit_env: bool,
+    interactive: bool,
+    local: bool,
+    dry_run: bool,
+    wait: bool,
+    keep_script: bool,
+) -> None:
+    """Submit a job to the scheduler.
+
+    COMMAND is the command to execute. Use quotes for complex commands:
+
+    \b
+        hpc run "make -j8 all"
+        hpc run python script.py --arg value
+
+    Any unrecognized options starting with '-' are passed directly to the
+    underlying scheduler. This allows using native flags:
+
+    \b
+        hpc run -N 4 -n 16 "mpirun ./sim"     # Slurm nodes/tasks
+        hpc run -q batch.q -l gpu=2 "train"   # SGE queue/resources
+    """
+    import shlex
+
+    from hpc_runner.core.job import Job
+    from hpc_runner.schedulers import get_scheduler
+
+    # Parse args into command and scheduler passthrough args
+    command_parts, scheduler_args = _parse_args(args)
+
+    if not command_parts:
+        raise click.UsageError("Command is required")
+
+    # Use shlex.join to preserve quoting for args with spaces/special chars
+    cmd_str = shlex.join(command_parts)
+
+    # Get scheduler
+    scheduler_name = "local" if local else ctx.scheduler
+    scheduler = get_scheduler(scheduler_name)
+
+    # Create job from config or parameters
+    if job_type:
+        job = Job.from_config(job_type, command=cmd_str)
+    else:
+        job = Job(command=cmd_str)
+
+    # Apply CLI overrides
+    if job_name:
+        job.name = job_name
+    if cpu:
+        job.cpu = cpu
+    if mem:
+        job.mem = mem
+    if time_limit:
+        job.time = time_limit
+    if queue:
+        job.queue = queue
+    if nodes:
+        job.nodes = nodes
+    if ntasks:
+        job.tasks = ntasks
+    if directory:
+        job.workdir = directory
+    if modules:
+        job.modules = list(modules)
+    if stderr:
+        job.stderr = stderr
+    if output:
+        job.stdout = output
+    if depend:
+        job.dependency = depend
+
+    # inherit_env is always set (has a default), so always apply it
+    job.inherit_env = inherit_env
+
+    # Add scheduler passthrough args
+    if scheduler_args:
+        job.raw_args = scheduler_args
+        if ctx.verbose:
+            console.print(f"[dim]Scheduler passthrough: {' '.join(scheduler_args)}[/dim]")
+
+    # Handle array jobs
+    if array:
+        _handle_array_job(job, array, scheduler, dry_run, ctx.verbose)
+        return
+
+    if dry_run:
+        _show_dry_run(job, scheduler, scheduler_args, interactive=interactive)
+        return
+
+    # Submit the job
+    result = scheduler.submit(job, interactive=interactive, keep_script=keep_script)
+
+    if interactive:
+        if result.returncode == 0:
+            console.print("[green]Job completed successfully[/green]")
+        else:
+            console.print(f"[red]Job failed with exit code: {result.returncode}[/red]")
+    else:
+        console.print(f"Submitted job [bold cyan]{result.job_id}[/bold cyan]")
+
+        if ctx.verbose:
+            console.print(f"  Scheduler: {scheduler.name}")
+            console.print(f"  Job name: {job.name}")
+            console.print(f"  Command: {job.command}")
+
+        if wait:
+            console.print("[dim]Waiting for job completion...[/dim]")
+            final_status = result.wait()
+            console.print(f"Job completed with status: [bold]{final_status.name}[/bold]")
+
+
+def _parse_args(args: tuple[str, ...]) -> tuple[list[str], list[str]]:
+    """Parse args into command parts and scheduler passthrough args.
+
+    Scheduler args are any args that:
+    - Start with '-' and are not recognized hpc-runner options
+    - Include their values (e.g., "-N 4" becomes ["-N", "4"])
+
+    The command is everything after the first non-option arg or after '--'.
+
+    Args:
+        args: Raw arguments from click
+
+    Returns:
+        Tuple of (command_parts, scheduler_args)
+    """
+    command_parts: list[str] = []
+    scheduler_args: list[str] = []
+
+    args_list = list(args)
+    i = 0
+    in_command = False
+
+    while i < len(args_list):
+        arg = args_list[i]
+
+        # '--' signals end of options
+        if arg == "--":
+            in_command = True
+            i += 1
+            continue
+
+        if in_command:
+            command_parts.append(arg)
+            i += 1
+            continue
+
+        # Check if this looks like an option
+        if arg.startswith("-"):
+            # This is a scheduler passthrough option
+            scheduler_args.append(arg)
+
+            # Check if next arg is the value (not another option)
+            if i + 1 < len(args_list) and not args_list[i + 1].startswith("-"):
+                # Handle special case: is this a flag or does it take a value?
+                # Heuristic: if next arg doesn't start with '-', treat as value
+                # unless the current arg uses '=' syntax
+                if "=" not in arg:
+                    i += 1
+                    scheduler_args.append(args_list[i])
+            i += 1
+        else:
+            # First non-option arg starts the command
+            in_command = True
+            command_parts.append(arg)
+            i += 1
+
+    return command_parts, scheduler_args
+
+
+def _show_dry_run(
+    job: "Job", scheduler, scheduler_args: list[str], interactive: bool = False
+) -> None:
+    """Display what would be submitted."""
+    mode = "interactive" if interactive else "batch"
+    console.print(
+        Panel.fit(
+            f"[bold]Scheduler:[/bold] {scheduler.name}\n"
+            f"[bold]Mode:[/bold] {mode}\n"
+            f"[bold]Job name:[/bold] {job.name}\n"
+            f"[bold]Command:[/bold] {job.command}",
+            title="Dry Run",
+            border_style="blue",
+        )
+    )
+
+    if scheduler_args:
+        console.print(f"\n[bold]Scheduler passthrough args:[/bold] {' '.join(scheduler_args)}")
+
+    console.print("\n[bold]Generated script:[/bold]")
+    if interactive and hasattr(scheduler, "_generate_interactive_script"):
+        script = scheduler._generate_interactive_script(job, "/tmp/example_script.sh")
+    else:
+        script = scheduler.generate_script(job)
+    syntax = Syntax(script, "bash", theme="monokai", line_numbers=True)
+    console.print(syntax)
+
+
+def _handle_array_job(job, array_spec: str, scheduler, dry_run: bool, verbose: bool) -> None:
+    """Handle array job submission."""
+    from hpc_runner.core.job_array import JobArray
+
+    # Parse array spec (e.g., "1-100", "1-100:10", "1-100%5")
+    # Basic parsing - could be enhanced
+    parts = array_spec.replace("%", ":").split(":")
+    range_parts = parts[0].split("-")
+
+    start = int(range_parts[0])
+    end = int(range_parts[1]) if len(range_parts) > 1 else start
+    step = int(parts[1]) if len(parts) > 1 else 1
+    max_concurrent = int(parts[2]) if len(parts) > 2 else None
+
+    array_job = JobArray(
+        job=job,
+        start=start,
+        end=end,
+        step=step,
+        max_concurrent=max_concurrent,
+    )
+
+    if dry_run:
+        console.print(f"[bold]Array job:[/bold] {array_job.range_str} ({array_job.count} tasks)")
+        _show_dry_run(job, scheduler, [])
+        return
+
+    result = array_job.submit(scheduler)
+    console.print(f"Submitted array job [bold cyan]{result.base_job_id}[/bold cyan]")
+    console.print(f"  Tasks: {array_job.count} ({array_job.range_str})")