qq_lib.properties.states

  1# Released under MIT License.
  2# Copyright (c) 2025-2026 Ladislav Bartos and Robert Vacha Lab
  3
  4"""
  5State models for qq jobs across different layers of the system.
  6
  7This module defines three related enums - `NaiveState`, `BatchState`, and
  8`RealState` - used to represent a job's status as recorded in qq's metadata,
  9reported by the batch system, and interpreted by qq's higher-level logic.
 10
 11qq often receives partial or inconsistent information (e.g., a job marked as
 12finished locally while still running in the batch system). `RealState`
 13normalizes these signals into a single coherent state used by qq operators.
 14"""
 15
 16from enum import Enum
 17
 18from qq_lib.core.config import CFG
 19from qq_lib.core.logger import get_logger
 20
 21logger = get_logger(__name__)
 22
 23
 24class NaiveState(Enum):
 25    """
 26    Naive state of the job written into qqinfo files.
 27    """
 28
 29    QUEUED = 1
 30    RUNNING = 2
 31    FAILED = 3
 32    FINISHED = 4
 33    KILLED = 5
 34    UNKNOWN = 6
 35
 36    def __str__(self) -> str:
 37        """
 38        Return the lowercase string representation of the enum variant.
 39
 40        Returns:
 41            str: The name of the state in lowercase.
 42        """
 43        return self.name.lower()
 44
 45    @classmethod
 46    def from_str(cls, s: str) -> "NaiveState":
 47        """
 48        Convert a string to the corresponding NaiveState enum variant.
 49
 50        Args:
 51            s (str): String representation of the state (case-insensitive).
 52
 53        Returns:
 54            NaiveState: Corresponding enum variant. Returns UNKNOWN if no match is found.
 55        """
 56        try:
 57            return cls[s.upper()]
 58        except KeyError:
 59            return cls.UNKNOWN
 60
 61
 62class BatchState(Enum):
 63    """
 64    State of the job according to the underlying batch system.
 65    """
 66
 67    RUNNING = 1
 68    QUEUED = 2
 69    FINISHED = 3
 70    FAILED = 4
 71    HELD = 5
 72    EXITING = 6
 73    WAITING = 7
 74    MOVING = 8
 75    SUSPENDED = 9
 76    UNKNOWN = 10
 77
 78    def __str__(self) -> str:
 79        """
 80        Return the lowercase string representation of the enum variant.
 81
 82        Returns:
 83            str: The name of the batch state in lowercase.
 84        """
 85        return self.name.lower()
 86
 87    @classmethod
 88    def _code_to_state(cls) -> dict[str, str]:
 89        """
 90        Internal mapping from one-letter codes to batch state names.
 91
 92        Returns:
 93            dict[str, str]: Mapping of codes to corresponding batch state names.
 94        """
 95        return {
 96            "E": "exiting",
 97            "H": "held",
 98            "Q": "queued",
 99            "R": "running",
100            "T": "moving",
101            "W": "waiting",
102            "S": "suspended",
103            "F": "finished",
104            "X": "failed",
105        }
106
107    @classmethod
108    def from_code(cls, code: str) -> "BatchState":
109        """
110        Convert a one-letter batch system code to a BatchState enum variant.
111
112        Args:
113            code (str): One-letter code representing the batch system state.
114
115        Returns:
116            BatchState: Corresponding enum variant, or UNKNOWN if the code is invalid.
117        """
118        code = code.upper()
119        if code not in cls._code_to_state():
120            return cls.UNKNOWN
121
122        name = cls._code_to_state()[code].upper()
123        return cls[name]
124
125    def to_code(self) -> str:
126        """
127        Return the one-letter code corresponding to this BatchState.
128
129        Returns:
130            str: One-letter code representing the batch state. Returns '?' if unknown.
131        """
132        for k, v in self._code_to_state().items():
133            if v.upper() == self.name:
134                return k
135
136        return "?"
137
138    @property
139    def color(self) -> str:
140        """
141        Return the display color associated with this BatchState.
142
143        Returns:
144            str: A string representing the color for presentation purposes.
145        """
146        if self is BatchState.MOVING:
147            return RealState.QUEUED.color
148        return RealState[self.name].color
149
150
151class RealState(Enum):
152    """
153    Precise state of the job obtained by combining information from NaiveState and BatchState.
154    """
155
156    QUEUED = 1
157    HELD = 2
158    SUSPENDED = 3
159    WAITING = 4
160    RUNNING = 5
161    BOOTING = 6
162    KILLED = 7
163    FAILED = 8
164    FINISHED = 9
165    EXITING = 10
166    IN_AN_INCONSISTENT_STATE = 11
167    UNKNOWN = 12
168
169    def __str__(self) -> str:
170        """
171        Return the human-readable string representation of the state.
172
173        Returns:
174            str: Lowercase string with underscores replaced by spaces.
175        """
176        return self.name.lower().replace("_", " ")
177
178    @classmethod
179    def from_states(
180        cls, naive_state: NaiveState, batch_state: BatchState
181    ) -> "RealState":
182        """
183        Determine the RealState of a job based on its NaiveState and BatchState.
184
185        Args:
186            naive_state (NaiveState): The naive state of the job from qqinfo.
187            batch_state (BatchState): The state of the job according to the batch system.
188
189        Returns:
190            RealState: The corresponding RealState.
191        """
192        logger.debug(
193            f"Converting to RealState from '{naive_state}' and '{batch_state}'."
194        )
195        match (naive_state, batch_state):
196            case (NaiveState.UNKNOWN, _):
197                return cls.UNKNOWN
198
199            case (NaiveState.QUEUED, BatchState.QUEUED | BatchState.MOVING):
200                return cls.QUEUED
201            case (NaiveState.QUEUED, BatchState.HELD):
202                return cls.HELD
203            case (NaiveState.QUEUED, BatchState.SUSPENDED):
204                return cls.SUSPENDED
205            case (NaiveState.QUEUED, BatchState.WAITING):
206                return cls.WAITING
207            case (NaiveState.QUEUED, BatchState.RUNNING):
208                return cls.BOOTING
209            case (NaiveState.QUEUED, _):
210                return cls.IN_AN_INCONSISTENT_STATE
211
212            case (NaiveState.RUNNING, BatchState.RUNNING):
213                return cls.RUNNING
214            case (NaiveState.RUNNING, BatchState.SUSPENDED):
215                return cls.SUSPENDED
216            case (NaiveState.RUNNING, _):
217                return cls.IN_AN_INCONSISTENT_STATE
218
219            case (NaiveState.KILLED, BatchState.RUNNING):
220                return cls.EXITING
221            case (NaiveState.KILLED, _):
222                return cls.KILLED
223
224            case (NaiveState.FINISHED, BatchState.RUNNING):
225                return cls.EXITING
226            case (
227                NaiveState.FINISHED,
228                BatchState.QUEUED
229                | BatchState.WAITING
230                | BatchState.HELD
231                | BatchState.FAILED,
232            ):
233                return cls.IN_AN_INCONSISTENT_STATE
234            case (NaiveState.FINISHED, _):
235                return cls.FINISHED
236
237            case (NaiveState.FAILED, BatchState.RUNNING):
238                return cls.EXITING
239            case (
240                NaiveState.FAILED,
241                BatchState.QUEUED
242                | BatchState.WAITING
243                | BatchState.HELD
244                | BatchState.FINISHED,
245            ):
246                return cls.IN_AN_INCONSISTENT_STATE
247            case (NaiveState.FAILED, _):
248                return cls.FAILED
249
250        return cls.UNKNOWN
251
252    @property
253    def color(self) -> str:
254        """
255        Return the display color associated with this RealState.
256
257        Returns:
258            str: A string representing the color for presentation purposes.
259        """
260        return getattr(CFG.state_colors, self.name.lower())