qq_lib.properties.interpreter

 1# Released under MIT License.
 2# Copyright (c) 2025-2026 Ladislav Bartos and Robert Vacha Lab
 3
 4import shutil
 5import socket
 6from dataclasses import dataclass, field
 7from typing import Any
 8
 9from qq_lib.core.config import CFG
10from qq_lib.core.error import QQError
11
12
13@dataclass(frozen=True)
14class Interpreter:
15    """
16    Configuration for the interpreter used to execute a job script.
17
18    Attributes:
19        executable: Name or path of the interpreter executable.
20            Defaults to the executable from `CFG.runner.default_interpreter`.
21        arguments: Additional command-line arguments passed to the interpreter.
22            Defaults to arguments parsed from `CFG.runner.default_interpreter`,
23            or an empty list if `executable` is provided explicitly.
24    """
25
26    executable: str | None = None
27    arguments: list[str] = field(default_factory=list)
28
29    def __post_init__(self):
30        """Parse executable and arguments from `CFG.runner.default_interpreter` if no executable was provided."""
31        if self.executable is None:
32            binary, *arguments = CFG.runner.default_interpreter.split()
33            object.__setattr__(self, "executable", binary)
34            object.__setattr__(self, "arguments", arguments)
35
36    @classmethod
37    def from_str(cls, s: str) -> "Interpreter":
38        """
39        Create an Interpreter from a string containing the executable and optional arguments.
40
41        The string is split on whitespace. The first token is used as the executable
42        and any remaining tokens become arguments.
43
44        Args:
45            s (str): Space-separated string of the interpreter executable followed by
46                optional arguments. For example: "python3 -u" or "/usr/bin/bash".
47
48        Returns:
49            Interpreter:An Interpreter instance with the parsed executable and arguments.
50        """
51        executable, *arguments = s.split()
52        return cls(executable=executable, arguments=arguments)
53
54    @classmethod
55    def from_dict(cls, d: dict[str, Any]) -> "Interpreter":
56        """
57        Create an Interpreter from a dictionary.
58
59        Args:
60            d (dict[str, Any]): Dictionary with keys matching the dataclass fields
61                (`executable` and `arguments`).
62
63        Returns:
64            Interpreter: An Interpreter instance constructed from the dictionary values.
65        """
66        return cls(**d)
67
68    def to_dict(self) -> dict[str, Any]:
69        """
70        Serialize the Interpreter to a dictionary.
71
72        Returns:
73            A dictionary with `executable` and `arguments` keys.
74        """
75        return {"executable": self.executable, "arguments": self.arguments}
76
77    def to_command_list(self) -> list[str]:
78        """
79        Resolve the executable to its full path and build the command list.
80
81        Uses `shutil.which` to locate the interpreter on the current node.
82        The returned list is suitable for use with `subprocess` calls.
83
84        Returns:
85            list[str]: A list containing the resolved absolute path of the executable
86            followed by any configured arguments.
87
88        Raises:
89            QQError: If the interpreter executable cannot be found on the current node.
90        """
91        # enforced in __post_init__
92        assert self.executable is not None
93
94        if not (full := shutil.which(self.executable)):
95            raise QQError(
96                f"Interpreter '{self.executable}' is not available on node '{socket.getfqdn()}'."
97            )
98
99        return [full] + self.arguments