hpc-runner 0.1.1__py3-none-any.whl → 0.2.1__py3-none-any.whl

hpc_runner/core/descriptors.py

@@ -1,56 +1,110 @@
-"""Base descriptor pattern for scheduler arguments."""
+"""Descriptor pattern for job attributes and scheduler arguments."""
 
 from abc import ABC, abstractmethod
-from typing import Any, Callable, Generic, TypeVar
+from typing import Any, Generic, TypeVar
 
 T = TypeVar("T")
 
 
+# =============================================================================
+# Job Attribute Descriptor
+# =============================================================================
+
+
+class JobAttribute(Generic[T]):
+    """Descriptor for Job attributes that enables iteration and rendering.
+
+    This descriptor provides:
+    - Clean attribute access on Job instances
+    - Class-level access returns the descriptor itself
+    - Support for default values
+    - Registration for iteration by schedulers
+
+    Example:
+        class Job:
+            name = JobAttribute('name')
+            cpu = JobAttribute('cpu', default=1)
+
+        job = Job()
+        job.name = "test"
+        print(job.name)  # "test"
+        print(Job.name)  # <JobAttribute 'name'>
+    """
+
+    def __init__(self, name: str, *, default: T | None = None):
+        self.public_name = name
+        self.default = default
+        self._private_name: str | None = None
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        self._private_name = f"_{name}"
+
+    def __get__(self, obj: Any, objtype: type | None = None) -> T | "JobAttribute[T]":
+        if obj is None:
+            return self
+        return getattr(obj, self._private_name, self.default)
+
+    def __set__(self, obj: Any, value: T | None) -> None:
+        setattr(obj, self._private_name, value)
+
+    def __repr__(self) -> str:
+        return f"<JobAttribute '{self.public_name}'>"
+
+
+# =============================================================================
+# Scheduler Argument Base Class
+# =============================================================================
+
+
 class SchedulerArg(ABC, Generic[T]):
-    """Base descriptor for scheduler arguments.
-
-    Attributes:
-        flag: The scheduler's command-line flag name
-        converter: Function to convert Python value to string
-        validator: Optional validation function
-        doc: Documentation string
-        env_var: Optional environment variable override
+    """Base class for scheduler-specific argument renderers.
+
+    Each scheduler backend (SGE, Slurm, PBS) will have subclasses that know
+    how to render job attribute values into that scheduler's syntax.
+
+    Subclasses must implement:
+    - to_args(value) -> list of command-line arguments
+    - to_directive(value) -> script directive string or None
+
+    Example:
+        class SGEJobNameArg(SchedulerArg[str]):
+            def to_args(self, value):
+                return ["-N", value] if value else []
+
+            def to_directive(self, value):
+                return f"#$ -N {value}" if value else None
     """
 
     def __init__(
         self,
         flag: str,
         *,
-        converter: Callable[[T], str] = str,
-        validator: Callable[[T], bool] | None = None,
         doc: str = "",
-        env_var: str | None = None,
     ):
         self.flag = flag
-        self.converter = converter
-        self.validator = validator
         self.doc = doc
-        self.env_var = env_var
-        self._name: str | None = None
-
-    def __set_name__(self, owner: type, name: str) -> None:
-        self._name = name
-
-    def __get__(self, obj: Any, objtype: type | None = None) -> T | None:
-        if obj is None:
-            return self  # type: ignore[return-value]
-        return obj.__dict__.get(self._name)  # type: ignore[arg-type]
-
-    def __set__(self, obj: Any, value: T | None) -> None:
-        if value is not None and self.validator:
-            if not self.validator(value):
-                raise ValueError(f"Invalid value for {self._name}: {value}")
-        obj.__dict__[self._name] = value  # type: ignore[index]
 
     @abstractmethod
     def to_args(self, value: T | None) -> list[str]:
-        """Convert value to command-line arguments."""
+        """Convert value to command-line arguments.
+
+        Args:
+            value: The job attribute value (may be None)
+
+        Returns:
+            List of command-line argument strings, empty list if value is None
+        """
 
     @abstractmethod
     def to_directive(self, value: T | None) -> str | None:
-        """Convert value to script directive (e.g., #SBATCH, #$)."""
+        """Convert value to a script directive.
+
+        Args:
+            value: The job attribute value (may be None)
+
+        Returns:
+            Directive string (e.g., "#$ -N jobname") or None if value is None
+        """
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__} flag='{self.flag}'>"

hpc_runner/core/exceptions.py

@@ -27,3 +27,12 @@ class ConfigNotFoundError(ConfigError):
 
 class ValidationError(HPCToolsError):
     """Validation error for job parameters."""
+
+
+class AccountingNotAvailable(SchedulerError):
+    """Job accounting/history is not enabled on this cluster.
+
+    Raised when attempting to query historical job data (e.g., via qacct
+    for SGE or sacct for Slurm) but the scheduler's accounting system
+    is not configured or accessible.
+    """

hpc_runner/core/job.py

@@ -1,13 +1,11 @@
-"""Job model for HPC job submission."""
+"""Job model - pure data container with no scheduler knowledge."""
 
 from __future__ import annotations
 
 import os
-import re
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Iterator
 
+from hpc_runner.core.descriptors import JobAttribute
 from hpc_runner.core.resources import ResourceSet
 
 if TYPE_CHECKING:
@@ -15,84 +13,192 @@ if TYPE_CHECKING:
     from hpc_runner.schedulers.base import BaseScheduler
 
 
-@dataclass
 class Job:
-    """Represents a job to be submitted.
-
-    Attributes:
-        command: The command to execute (string or list)
-        name: Job name (auto-generated if not provided)
-        cpu: Number of CPUs/cores/slots
-        mem: Memory requirement (e.g., "16G", "4096M")
-        time: Wall time limit (e.g., "4:00:00", "1-00:00:00")
-        queue: Queue/partition name
-        nodes: Number of nodes (for MPI jobs)
-        tasks: Number of tasks (for MPI jobs)
-        resources: Additional resource requests
-        modules: Environment modules to load
-        modules_path: Additional module paths
-        inherit_env: Inherit current environment
-        workdir: Working directory (default: current)
-        stdout: Stdout file path (supports templates)
-        stderr: Stderr file path (None = merge with stdout)
-        raw_args: Raw scheduler arguments (passthrough)
-        sge_args: SGE-specific raw arguments
-        slurm_args: Slurm-specific raw arguments
-        pbs_args: PBS-specific raw arguments
+    """HPC job specification.
+
+    This is a pure data container. It has no knowledge of any specific
+    scheduler's syntax. Rendering to scheduler-specific formats is handled
+    by the scheduler classes.
+
+    Attributes are defined using JobAttribute descriptors, which enables:
+    - Clean attribute access: job.name, job.cpu, etc.
+    - Iteration over set attributes via iter_attributes()
+    - Class-level introspection: Job.name returns the descriptor
+
+    Example:
+        job = Job(
+            command="python train.py",
+            name="training_run",
+            cpu=4,
+            mem="16G",
+            time="4:00:00",
+        )
+
+        # Direct access
+        print(job.name)  # "training_run"
+        print(job.cpu)   # 4
+
+        # Iterate over set attributes
+        for attr, value in job.iter_attributes():
+            print(f"{attr}={value}")
     """
 
-    command: str | list[str]
-    name: str | None = None
-    cpu: int | None = None
-    mem: str | None = None
-    time: str | None = None
-    queue: str | None = None
-    nodes: int | None = None
-    tasks: int | None = None
-    resources: ResourceSet = field(default_factory=ResourceSet)
-    modules: list[str] = field(default_factory=list)
-    modules_path: list[str] = field(default_factory=list)
-    inherit_env: bool = True
-    workdir: Path | str | None = None
-    stdout: str | None = None
-    stderr: str | None = None  # None = merge with stdout
-
-    # Raw passthrough arguments
-    raw_args: list[str] = field(default_factory=list)
-    sge_args: list[str] = field(default_factory=list)
-    slurm_args: list[str] = field(default_factory=list)
-    pbs_args: list[str] = field(default_factory=list)
-
-    # Dependency management
-    dependencies: list[JobResult] = field(default_factory=list)
-    dependency_type: str = "afterok"  # afterok, afterany, after, afternotok
-
-    def __post_init__(self) -> None:
-        if self.name is None:
-            self.name = self._generate_name()
-        if isinstance(self.command, list):
-            self.command = " ".join(self.command)
-        if self.workdir is not None and not isinstance(self.workdir, Path):
-            self.workdir = Path(self.workdir)
+    # =========================================================================
+    # Attribute Descriptors
+    # =========================================================================
 
-    def _generate_name(self) -> str:
-        """Generate job name from command."""
-        user = os.environ.get("USER", "user")
-        # Extract first word of command, strip path
-        cmd_str = self.command if isinstance(self.command, str) else self.command[0]
-        cmd = cmd_str.split()[0]
-        cmd = Path(cmd).name
-        cmd = re.sub(r"[^a-zA-Z0-9_-]", "_", cmd)
-        return f"{user}_{cmd}"
+    # Job identification
+    name = JobAttribute[str]("name")
+
+    # Resource requests
+    cpu = JobAttribute[int]("cpu")
+    mem = JobAttribute[str]("mem")
+    time = JobAttribute[str]("time")
+
+    # Scheduling
+    queue = JobAttribute[str]("queue")
+    priority = JobAttribute[int]("priority")
+
+    # MPI/Multi-node jobs (primarily Slurm, but kept for compatibility)
+    nodes = JobAttribute[int]("nodes")
+    tasks = JobAttribute[int]("tasks")
+
+    # Output handling
+    stdout = JobAttribute[str]("stdout")
+    stderr = JobAttribute[str]("stderr")
+
+    # Environment
+    inherit_env = JobAttribute[bool]("inherit_env", default=True)
+    workdir = JobAttribute[str]("workdir")
+    shell = JobAttribute[str]("shell", default="/bin/bash")
+    venv = JobAttribute[str]("venv")  # Virtual environment path
+
+    # Working directory behavior
+    use_cwd = JobAttribute[bool]("use_cwd", default=True)
+
+    # Note: 'dependency' is NOT a descriptor - it's handled specially by schedulers
+    # because it involves both string form (CLI) and programmatic form (Job.after())
+
+    # =========================================================================
+    # Attribute Registry - Order matters for directive generation
+    # =========================================================================
 
-    def submit(self, scheduler: BaseScheduler | None = None) -> JobResult:
-        """Submit the job.
+    RENDERABLE_ATTRIBUTES: list[str] = [
+        "shell",
+        "use_cwd",
+        "inherit_env",
+        "name",
+        "cpu",
+        "mem",
+        "time",
+        "queue",
+        "priority",
+        "nodes",
+        "tasks",
+        "stdout",
+        "stderr",
+    ]
+
+    # =========================================================================
+    # Initialization
+    # =========================================================================
+
+    def __init__(
+        self,
+        command: str | list[str],
+        *,
+        name: str | None = None,
+        cpu: int | None = None,
+        mem: str | None = None,
+        time: str | None = None,
+        queue: str | None = None,
+        priority: int | None = None,
+        nodes: int | None = None,
+        tasks: int | None = None,
+        stdout: str | None = None,
+        stderr: str | None = None,
+        inherit_env: bool = True,
+        workdir: str | None = None,
+        shell: str = "/bin/bash",
+        use_cwd: bool = True,
+        venv: str | None = None,
+        env_vars: dict[str, str] | None = None,
+        modules: list[str] | None = None,
+        modules_path: list[str] | None = None,
+        resources: ResourceSet | None = None,
+        raw_args: list[str] | None = None,
+        sge_args: list[str] | None = None,
+        slurm_args: list[str] | None = None,
+        pbs_args: list[str] | None = None,
+        dependency: str | None = None,
+    ):
+        # Command handling
+        if isinstance(command, list):
+            self.command = " ".join(command)
+        else:
+            self.command = command
+
+        # Set descriptor-based attributes
+        self.name = name or self._generate_name()
+        self.cpu = cpu
+        self.mem = mem
+        self.time = time
+        self.queue = queue
+        self.priority = priority
+        self.nodes = nodes
+        self.tasks = tasks
+        self.stdout = stdout
+        self.stderr = stderr
+        self.inherit_env = inherit_env
+        self.workdir = workdir
+        self.shell = shell
+        self.use_cwd = use_cwd
+
+        # Virtual environment - auto-capture from VIRTUAL_ENV if not specified
+        if venv is None:
+            venv = os.environ.get("VIRTUAL_ENV")
+        self.venv = venv
+
+        # Non-descriptor attributes
+        self.env_vars: dict[str, str] = env_vars or {}
+        self.modules: list[str] = modules or []
+        self.modules_path: list[str] = modules_path or []
+        self.resources: ResourceSet = resources or ResourceSet()
+        self.raw_args: list[str] = raw_args or []
+        self.sge_args: list[str] = sge_args or []
+        self.slurm_args: list[str] = slurm_args or []
+        self.pbs_args: list[str] = pbs_args or []
+        self.dependency: str | None = dependency
+
+        # Programmatic dependencies (from .after() method)
+        self.dependencies: list[JobResult] = []
+        self.dependency_type: str = "afterok"
+
+    # =========================================================================
+    # Submission API
+    # =========================================================================
+
+    def submit(self, scheduler: "BaseScheduler | None" = None) -> "JobResult":
+        """Submit the job to a scheduler.
+
+        This is the primary programmatic API for job submission.
 
         Args:
-            scheduler: Scheduler to use. Auto-detects if None.
+            scheduler: Scheduler to use. If None, auto-detects based on
+                       environment (checks HPC_SCHEDULER env var, then
+                       probes for SGE_ROOT, sbatch, etc.)
 
         Returns:
-            JobResult with job ID and status methods
+            JobResult with job ID and methods to check status, get output, etc.
+
+        Example:
+            job = Job("python train.py", cpu=4, mem="16G")
+            result = job.submit()
+            print(f"Submitted: {result.job_id}")
+
+            # Wait for completion
+            result.wait()
+            print(f"Exit code: {result.exit_code}")
         """
         from hpc_runner.schedulers import get_scheduler
 
@@ -100,37 +206,37 @@ class Job:
             scheduler = get_scheduler()
         return scheduler.submit(self)
 
-    def after(self, *jobs: JobResult, type: str = "afterok") -> Job:
-        """Add dependency on other jobs.
-
-        Args:
-            jobs: Jobs this job depends on
-            type: Dependency type (afterok, afterany, after, afternotok)
-        """
-        self.dependencies.extend(jobs)
-        self.dependency_type = type
-        return self
-
     @classmethod
     def from_config(
         cls,
         tool_or_type: str,
         command: str | None = None,
         **overrides: Any,
-    ) -> Job:
-        """Create job from configuration.
+    ) -> "Job":
+        """Create a job from configuration.
+
+        Looks up job settings from the config file by tool name or job type,
+        then applies any overrides.
 
         Args:
-            tool_or_type: Tool name or job type from config
-            command: Override command (uses config template if None)
+            tool_or_type: Tool name (e.g., "python", "make") or job type
+                          (e.g., "interactive", "gpu") from config
+            command: Command to run. If None, uses command from config.
             **overrides: Override any job parameters
+
+        Returns:
+            Job configured according to config file + overrides
+
+        Example:
+            # Config file has [types.gpu] with queue="gpu", resources=[{gpu=1}]
+            job = Job.from_config("gpu", command="python train.py")
         """
-        from hpc_runner.core.config import load_config
+        from hpc_runner.core.config import get_config
 
-        config = load_config()
+        config = get_config()
         job_config = config.get_job_config(tool_or_type)
 
-        if command:
+        if command is not None:
             job_config["command"] = command
         job_config.update(overrides)
 
@@ -143,7 +249,80 @@ class Job:
 
         return cls(**job_config)
 
+    # =========================================================================
+    # Attribute Iteration
+    # =========================================================================
+
+    def iter_attributes(self) -> Iterator[tuple[str, Any]]:
+        """Iterate over renderable attributes that have been set.
+
+        Yields:
+            Tuples of (attribute_name, value) for attributes that are not None
+            and not equal to their default "skip" values.
+
+        Note:
+            The iteration order follows RENDERABLE_ATTRIBUTES, which is
+            designed to produce sensible directive ordering.
+        """
+        for attr_name in self.RENDERABLE_ATTRIBUTES:
+            value = getattr(self, attr_name)
+
+            # Skip None values
+            if value is None:
+                continue
+
+            # Skip False for boolean attributes (they're opt-in)
+            # Exception: use_cwd and inherit_env default True, so False means explicit opt-out
+            descriptor = getattr(self.__class__, attr_name)
+            if isinstance(value, bool) and value is False and descriptor.default is not True:
+                continue
+
+            yield attr_name, value
+
+    # =========================================================================
+    # Properties
+    # =========================================================================
+
     @property
     def merge_output(self) -> bool:
-        """Whether stderr should be merged with stdout."""
+        """Whether to merge stderr into stdout."""
         return self.stderr is None
+
+    # =========================================================================
+    # Helper Methods
+    # =========================================================================
+
+    def _generate_name(self) -> str:
+        """Generate a job name from username and command."""
+        user = os.environ.get("USER", "user")
+        # Extract first meaningful word from command
+        cmd_parts = self.command.split()
+        for part in cmd_parts:
+            if "=" not in part:
+                cmd_name = part.split("/")[-1]  # Handle paths
+                return f"{user}_{cmd_name}"
+        return f"{user}_job"
+
+    def after(
+        self,
+        *jobs: "JobResult",
+        type: str = "afterok",
+    ) -> "Job":
+        """Add job dependencies.
+
+        Args:
+            *jobs: JobResult objects this job depends on
+            type: Dependency type (afterok, afterany, afternotok)
+
+        Returns:
+            Self for method chaining
+        """
+        self.dependencies.extend(jobs)
+        self.dependency_type = type
+        return self
+
+    def __repr__(self) -> str:
+        attrs = []
+        for attr, value in self.iter_attributes():
+            attrs.append(f"{attr}={value!r}")
+        return f"Job(command={self.command!r}, {', '.join(attrs)})"

hpc_runner/core/job_info.py

@@ -0,0 +1,104 @@
+"""Job information types for TUI display."""
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+
+from .result import JobStatus
+
+
+@dataclass
+class JobInfo:
+    """Unified job information for TUI display.
+
+    This dataclass provides a scheduler-agnostic view of job information
+    suitable for display in the monitor TUI. All fields except job_id,
+    name, user, and status are optional to handle varying levels of
+    information availability across schedulers.
+    """
+
+    job_id: str
+    name: str
+    user: str
+    status: JobStatus
+
+    # Queue/partition info
+    queue: str | None = None
+
+    # Timing information
+    submit_time: datetime | None = None
+    start_time: datetime | None = None
+    end_time: datetime | None = None
+    runtime: timedelta | None = None
+
+    # Resource requests/usage
+    cpu: int | None = None
+    memory: str | None = None  # e.g., "16G", "4096M"
+    gpu: int | None = None
+
+    # Completion info (None for active jobs)
+    exit_code: int | None = None
+
+    # Output file paths
+    stdout_path: Path | None = None
+    stderr_path: Path | None = None
+
+    # Extended info
+    node: str | None = None
+    dependencies: list[str] | None = None
+    array_task_id: int | None = None
+
+    @property
+    def is_active(self) -> bool:
+        """Check if job is still active (not yet completed)."""
+        return self.status in (
+            JobStatus.PENDING,
+            JobStatus.RUNNING,
+            JobStatus.UNKNOWN,
+        )
+
+    @property
+    def is_complete(self) -> bool:
+        """Check if job has finished (success or failure)."""
+        return self.status in (
+            JobStatus.COMPLETED,
+            JobStatus.FAILED,
+            JobStatus.CANCELLED,
+            JobStatus.TIMEOUT,
+        )
+
+    @property
+    def runtime_display(self) -> str:
+        """Format runtime for display (e.g., '2h 15m')."""
+        if self.runtime is None:
+            return "—"
+
+        total_seconds = int(self.runtime.total_seconds())
+        if total_seconds < 60:
+            return f"{total_seconds}s"
+
+        minutes = total_seconds // 60
+        if minutes < 60:
+            return f"{minutes}m"
+
+        hours = minutes // 60
+        remaining_minutes = minutes % 60
+        if hours < 24:
+            return f"{hours}h {remaining_minutes}m"
+
+        days = hours // 24
+        remaining_hours = hours % 24
+        return f"{days}d {remaining_hours}h"
+
+    @property
+    def resources_display(self) -> str:
+        """Format resources for display (e.g., '4/16G')."""
+        parts = []
+        if self.cpu is not None:
+            parts.append(str(self.cpu))
+        if self.memory is not None:
+            parts.append(self.memory)
+        if self.gpu is not None:
+            parts.append(f"{self.gpu}GPU")
+
+        return "/".join(parts) if parts else "—"