executorlib 1.9.2__py3-none-any.whl → 1.9.4__py3-none-any.whl

executorlib/_version.py

@@ -1,5 +1,6 @@
-# file generated by setuptools-scm
+# file generated by vcs-versioning
 # don't change, don't track in version control
+from __future__ import annotations
 
 __all__ = [
     "__version__",
@@ -10,25 +11,14 @@ __all__ = [
     "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_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
 
-__version__ = version = '1.9.2'
-__version_tuple__ = version_tuple = (1, 9, 2)
+__version__ = version = '1.9.4'
+__version_tuple__ = version_tuple = (1, 9, 4)
 
 __commit_id__ = commit_id = None

executorlib/executor/base.py

@@ -25,10 +25,22 @@ class BaseExecutor(FutureExecutor, ABC):
 
     @property
     def max_workers(self) -> Optional[int]:
+        """
+        Return the number of parallel workers configured for this executor.
+
+        Returns:
+            Optional[int]: The maximum number of parallel workers, or None if unconstrained.
+        """
         return self._task_scheduler.max_workers
 
     @max_workers.setter
     def max_workers(self, max_workers: int):
+        """
+        Set the number of parallel workers on the underlying task scheduler.
+
+        Args:
+            max_workers (int): New maximum number of parallel workers.
+        """
         self._task_scheduler.max_workers = max_workers
 
     @property

executorlib/executor/flux.py

@@ -51,8 +51,8 @@ class FluxJobExecutor(BaseExecutor):
                                                   do not allow other tasks to use the same compute node.
                               * error_log_file (str): path to the error log file, primarily used to merge the log of
                                                       multiple tasks in one file.
-                              * run_time_limit (int): the maximum time the execution of the submitted Python function is
-                                                      allowed to take in seconds.
+                              * run_time_max (int): the maximum time the execution of the submitted Python function is
+                                                    allowed to take in seconds.
                               * priority (int): the queuing system priority assigned to a given Python function to
                                                 influence the scheduling.
                               * slurm_cmd_args (list): Additional command line arguments for the srun call (SLURM only)
@@ -154,7 +154,7 @@ class FluxJobExecutor(BaseExecutor):
                                                       - do not allow other tasks to use the same compute node.
                                   * error_log_file (str): path to the error log file, primarily used to merge the log of
                                                           multiple tasks in one file.
-                                  * run_time_limit (int): the maximum time the execution of the submitted Python
+                                  * run_time_max (int): the maximum time the execution of the submitted Python
                                                         function is allowed to take in seconds.
                                   * priority (int): the queuing system priority assigned to a given Python function to
                                                     influence the scheduling.
@@ -283,8 +283,8 @@ class FluxClusterExecutor(BaseExecutor):
                                                   do not allow other tasks to use the same compute node.
                               * error_log_file (str): path to the error log file, primarily used to merge the log of
                                                       multiple tasks in one file.
-                              * run_time_limit (int): the maximum time the execution of the submitted Python function is
-                                                      allowed to take in seconds.
+                              * run_time_max (int): the maximum time the execution of the submitted Python function is
+                                                    allowed to take in seconds.
                               * priority (int): the queuing system priority assigned to a given Python function to
                                                 influence the scheduling.
                               * slurm_cmd_args (list): Additional command line arguments for the srun call (SLURM only)
@@ -380,7 +380,7 @@ class FluxClusterExecutor(BaseExecutor):
                                                       - do not allow other tasks to use the same compute node.
                                   * error_log_file (str): path to the error log file, primarily used to merge the log of
                                                           multiple tasks in one file.
-                                  * run_time_limit (int): the maximum time the execution of the submitted Python
+                                  * run_time_max (int): the maximum time the execution of the submitted Python
                                                         function is allowed to take in seconds.
                                   * priority (int): the queuing system priority assigned to a given Python function to
                                                     influence the scheduling.
@@ -417,7 +417,7 @@ class FluxClusterExecutor(BaseExecutor):
             "cwd": None,
             "openmpi_oversubscribe": openmpi_oversubscribe,
             "slurm_cmd_args": [],
-            "run_time_limit": None,
+            "run_time_max": None,
         }
         if resource_dict is None:
             resource_dict = {}
@@ -540,8 +540,8 @@ def create_flux_executor(
                                                   do not allow other tasks to use the same compute node.
                               * error_log_file (str): path to the error log file, primarily used to merge the log of
                                                       multiple tasks in one file.
-                              * run_time_limit (int): the maximum time the execution of the submitted Python function is
-                                                      allowed to take in seconds.
+                              * run_time_max (int): the maximum time the execution of the submitted Python function is
+                                                    allowed to take in seconds.
                               * priority (int): the queuing system priority assigned to a given Python function to
                                                 influence the scheduling.
                               * slurm_cmd_args (list): Additional command line arguments for the srun call (SLURM only)

executorlib/executor/single.py

@@ -50,8 +50,8 @@ class SingleNodeExecutor(BaseExecutor):
                                                   do not allow other tasks to use the same compute node.
                               * error_log_file (str): path to the error log file, primarily used to merge the log of
                                                       multiple tasks in one file.
-                              * run_time_limit (int): the maximum time the execution of the submitted Python function is
-                                                      allowed to take in seconds.
+                              * run_time_max (int): the maximum time the execution of the submitted Python function is
+                                                    allowed to take in seconds.
                               * priority (int): the queuing system priority assigned to a given Python function to
                                                 influence the scheduling.
                               * slurm_cmd_args (list): Additional command line arguments for the srun call (SLURM only)
@@ -145,7 +145,7 @@ class SingleNodeExecutor(BaseExecutor):
                                                       - do not allow other tasks to use the same compute node.
                                   * error_log_file (str): path to the error log file, primarily used to merge the log of
                                                           multiple tasks in one file.
-                                  * run_time_limit (int): the maximum time the execution of the submitted Python
+                                  * run_time_max (int): the maximum time the execution of the submitted Python
                                                         function is allowed to take in seconds.
                                   * priority (int): the queuing system priority assigned to a given Python function to
                                                     influence the scheduling.
@@ -259,8 +259,8 @@ class TestClusterExecutor(BaseExecutor):
                                                   do not allow other tasks to use the same compute node.
                               * error_log_file (str): path to the error log file, primarily used to merge the log of
                                                       multiple tasks in one file.
-                              * run_time_limit (int): the maximum time the execution of the submitted Python function is
-                                                      allowed to take in seconds.
+                              * run_time_max (int): the maximum time the execution of the submitted Python function is
+                                                    allowed to take in seconds.
                               * priority (int): the queuing system priority assigned to a given Python function to
                                                 influence the scheduling.
                               * slurm_cmd_args (list): Additional command line arguments for the srun call (SLURM only)
@@ -350,7 +350,7 @@ class TestClusterExecutor(BaseExecutor):
                                                       - do not allow other tasks to use the same compute node.
                                   * error_log_file (str): path to the error log file, primarily used to merge the log of
                                                           multiple tasks in one file.
-                                  * run_time_limit (int): the maximum time the execution of the submitted Python
+                                  * run_time_max (int): the maximum time the execution of the submitted Python
                                                         function is allowed to take in seconds.
                                   * priority (int): the queuing system priority assigned to a given Python function to
                                                     influence the scheduling.
@@ -479,8 +479,8 @@ def create_single_node_executor(
                                                   do not allow other tasks to use the same compute node.
                               * error_log_file (str): path to the error log file, primarily used to merge the log of
                                                       multiple tasks in one file.
-                              * run_time_limit (int): the maximum time the execution of the submitted Python function is
-                                                      allowed to take in seconds.
+                              * run_time_max (int): the maximum time the execution of the submitted Python function is
+                                                    allowed to take in seconds.
                               * priority (int): the queuing system priority assigned to a given Python function to
                                                 influence the scheduling.
                               * slurm_cmd_args (list): Additional command line arguments for the srun call (SLURM only)

executorlib/executor/slurm.py

@@ -52,8 +52,8 @@ class SlurmClusterExecutor(BaseExecutor):
                                                   do not allow other tasks to use the same compute node.
                               * error_log_file (str): path to the error log file, primarily used to merge the log of
                                                       multiple tasks in one file.
-                              * run_time_limit (int): the maximum time the execution of the submitted Python function is
-                                                      allowed to take in seconds.
+                              * run_time_max (int): the maximum time the execution of the submitted Python function is
+                                                    allowed to take in seconds.
                               * priority (int): the queuing system priority assigned to a given Python function to
                                                 influence the scheduling.
                               * slurm_cmd_args (list): Additional command line arguments for the srun call (SLURM only)
@@ -149,7 +149,7 @@ class SlurmClusterExecutor(BaseExecutor):
                                                       - do not allow other tasks to use the same compute node.
                                   * error_log_file (str): path to the error log file, primarily used to merge the log of
                                                           multiple tasks in one file.
-                                  * run_time_limit (int): the maximum time the execution of the submitted Python
+                                  * run_time_max (int): the maximum time the execution of the submitted Python
                                                         function is allowed to take in seconds.
                                   * priority (int): the queuing system priority assigned to a given Python function to
                                                     influence the scheduling.
@@ -293,8 +293,8 @@ class SlurmJobExecutor(BaseExecutor):
                                                   do not allow other tasks to use the same compute node.
                               * error_log_file (str): path to the error log file, primarily used to merge the log of
                                                       multiple tasks in one file.
-                              * run_time_limit (int): the maximum time the execution of the submitted Python function is
-                                                      allowed to take in seconds.
+                              * run_time_max (int): the maximum time the execution of the submitted Python function is
+                                                    allowed to take in seconds.
                               * priority (int): the queuing system priority assigned to a given Python function to
                                                 influence the scheduling.
                               * slurm_cmd_args (list): Additional command line arguments for the srun call (SLURM only)
@@ -390,7 +390,7 @@ class SlurmJobExecutor(BaseExecutor):
                                                       - do not allow other tasks to use the same compute node.
                                   * error_log_file (str): path to the error log file, primarily used to merge the log of
                                                           multiple tasks in one file.
-                                  * run_time_limit (int): the maximum time the execution of the submitted Python
+                                  * run_time_max (int): the maximum time the execution of the submitted Python
                                                         function is allowed to take in seconds.
                                   * priority (int): the queuing system priority assigned to a given Python function to
                                                     influence the scheduling.
@@ -518,8 +518,8 @@ def create_slurm_executor(
                                                   do not allow other tasks to use the same compute node.
                               * error_log_file (str): path to the error log file, primarily used to merge the log of
                                                       multiple tasks in one file.
-                              * run_time_limit (int): the maximum time the execution of the submitted Python function is
-                                                      allowed to take in seconds.
+                              * run_time_max (int): the maximum time the execution of the submitted Python function is
+                                                    allowed to take in seconds.
                               * priority (int): the queuing system priority assigned to a given Python function to
                                                 influence the scheduling.
                               * slurm_cmd_args (list): Additional command line arguments for the srun call (SLURM only)

executorlib/standalone/batched.py

@@ -1,27 +1,39 @@
 from concurrent.futures import Future
 
 
-def batched_futures(lst: list[Future], skip_lst: list[list], n: int) -> list[list]:
+def batched_futures(
+    lst: list[Future], nested_skip_lst: list[Future[list]], n: int
+) -> tuple[bool, list[Future]]:
     """
     Batch n completed future objects. If the number of completed futures is smaller than n and the end of the batch is
-    not reached yet, then an empty list is returned. If n future objects are done, which are not included in the skip_lst
+    not reached yet, then an empty list is returned. If n future objects are done, which are not included in the skip_set
     then they are returned as batch.
 
     Args:
         lst (list): list of all future objects
-        skip_lst (list): list of previous batches of future objects
+        nested_skip_lst (list): list of future objects, which contain the list of future objects ids which should be skipped for the batch
         n (int): batch size
 
     Returns:
         list: results of the batched futures
     """
-    skipped_elements_lst = [item for items in skip_lst for item in items]
+    skip_set = {fid for f in nested_skip_lst for fid in f.result()}
 
     done_lst = []
-    n_expected = min(n, len(lst) - len(skipped_elements_lst))
+    failed_lst = []
+    n_expected = min(n, len(lst) - len(skip_set))
     for v in lst:
-        if v.done() and v.result() not in skipped_elements_lst:
-            done_lst.append(v.result())
-        if len(done_lst) == n_expected:
-            return done_lst
-    return []
+        if id(v) not in skip_set and v.done():
+            if v.exception() is not None:
+                failed_lst.append(v)
+            elif id(v) not in skip_set and v.done():
+                done_lst.append(v)
+                if len(done_lst) == n_expected:
+                    return True, done_lst
+    if (len(lst) - len(skip_set)) == len(failed_lst):
+        return (
+            False,
+            failed_lst[:n_expected],
+        )  # raise the exception only after all futures have failed
+    else:
+        return True, []

executorlib/standalone/command.py

@@ -126,7 +126,7 @@ def generate_slurm_command(
     openmpi_oversubscribe: bool = False,
     slurm_cmd_args: Optional[list[str]] = None,
     pmi_mode: Optional[str] = None,
-    run_time_limit: Optional[int] = None,
+    run_time_max: Optional[int] = None,
 ) -> list[str]:
     """
     Generate the command list for the SLURM interface.
@@ -141,7 +141,7 @@ def generate_slurm_command(
         openmpi_oversubscribe (bool, optional): Whether to oversubscribe the cores. Defaults to False.
         slurm_cmd_args (list[str], optional): Additional command line arguments. Defaults to [].
         pmi_mode (str): PMI interface to use (OpenMPI v5 requires pmix) default is None
-        run_time_limit (int): The maximum runtime in seconds for each task. Default: None
+        run_time_max (int): The maximum runtime in seconds for each task. Default: None
 
     Returns:
         list[str]: The generated command list.
@@ -153,7 +153,7 @@ def generate_slurm_command(
         command_prepend_lst += ["--mpi=" + pmi_mode]
     if num_nodes is not None:
         command_prepend_lst += ["-N", str(num_nodes)]
-    if threads_per_core > 1:
+    if threads_per_core >= 1:
         command_prepend_lst += ["--cpus-per-task=" + str(threads_per_core)]
     if gpus_per_core > 0:
         command_prepend_lst += ["--gpus-per-task=" + str(gpus_per_core)]
@@ -161,8 +161,8 @@ def generate_slurm_command(
         command_prepend_lst += ["--exact"]
     if openmpi_oversubscribe:
         command_prepend_lst += ["--oversubscribe"]
-    if run_time_limit is not None:
-        command_prepend_lst += ["--time=" + str(run_time_limit // 60 + 1)]
+    if run_time_max is not None:
+        command_prepend_lst += ["--time=" + str(run_time_max // 60 + 1)]
     if slurm_cmd_args is not None and len(slurm_cmd_args) > 0:
         command_prepend_lst += slurm_cmd_args
     return command_prepend_lst

executorlib/standalone/hdf.py

@@ -1,3 +1,4 @@
+import contextlib
 import os
 from concurrent.futures import Future
 from time import sleep
@@ -34,10 +35,11 @@ def dump(file_name: Optional[str], data_dict: dict) -> None:
         with h5py.File(file_name_abs, "a") as fname:
             for data_key, data_value in data_dict.items():
                 if data_key in group_dict:
-                    fname.create_dataset(
-                        name="/" + group_dict[data_key],
-                        data=np.void(cloudpickle.dumps(data_value)),
-                    )
+                    with contextlib.suppress(ValueError):
+                        fname.create_dataset(
+                            name="/" + group_dict[data_key],
+                            data=np.void(cloudpickle.dumps(data_value)),
+                        )
 
 
 def load(file_name: str) -> dict:
@@ -171,7 +173,11 @@ def get_cache_files(cache_directory: str) -> list[str]:
     file_lst = []
     cache_directory_abs = os.path.abspath(cache_directory)
     for dirpath, _, filenames in os.walk(cache_directory_abs):
-        file_lst += [os.path.join(dirpath, f) for f in filenames if f.endswith("_o.h5")]
+        file_lst += [
+            os.path.join(dirpath, f)
+            for f in filenames
+            if f.endswith("_o.h5") or f.endswith("_i.h5")
+        ]
     return file_lst
 
 

executorlib/standalone/inputcheck.py

@@ -141,6 +141,16 @@ def check_init_function(
 def check_max_workers_and_cores(
     max_workers: Optional[int], max_cores: Optional[int]
 ) -> None:
+    """
+    Check that neither max_workers nor max_cores is set when using a pysqa-based backend.
+
+    Args:
+        max_workers (int, optional): Maximum number of workers.
+        max_cores (int, optional): Maximum number of cores.
+
+    Raises:
+        ValueError: If max_workers or max_cores is not None.
+    """
     if max_workers is not None:
         raise ValueError(
             "The number of workers cannot be controlled with the pysqa based backend."
@@ -152,6 +162,15 @@ def check_max_workers_and_cores(
 
 
 def check_hostname_localhost(hostname_localhost: Optional[bool]) -> None:
+    """
+    Check that hostname_localhost is not set when using a pysqa-based backend.
+
+    Args:
+        hostname_localhost (bool, optional): Flag to use localhost for ZMQ connections.
+
+    Raises:
+        ValueError: If hostname_localhost is not None.
+    """
     if hostname_localhost is not None:
         raise ValueError(
             "The option to connect to hosts based on their hostname is not available with the pysqa based backend."
@@ -159,6 +178,16 @@ def check_hostname_localhost(hostname_localhost: Optional[bool]) -> None:
 
 
 def check_restart_limit(restart_limit: int, block_allocation: bool = True) -> None:
+    """
+    Check that restart_limit is only used together with block_allocation.
+
+    Args:
+        restart_limit (int): Maximum number of times a worker process may be restarted.
+        block_allocation (bool): Whether block allocation is enabled. Defaults to True.
+
+    Raises:
+        ValueError: If restart_limit is non-zero and block_allocation is False.
+    """
     if not block_allocation and restart_limit != 0:
         raise ValueError(
             "The option to specify a restart limit for worker processes is only available with block_allocation=True."
@@ -166,6 +195,15 @@ def check_restart_limit(restart_limit: int, block_allocation: bool = True) -> No
 
 
 def check_pmi_mode(pmi_mode: Optional[str]) -> None:
+    """
+    Check that pmi_mode is not set on a local workstation without SLURM or flux.
+
+    Args:
+        pmi_mode (str, optional): PMI interface name (e.g. "pmix", "pmi1", "pmi2").
+
+    Raises:
+        ValueError: If pmi_mode is not None.
+    """
     if pmi_mode is not None:
         raise ValueError(
             "The option to specify the pmi mode is not available on a local workstation, it requires SLURM or flux."
@@ -199,7 +237,22 @@ def validate_number_of_cores(
     set_local_cores: bool = False,
 ) -> int:
     """
-    Validate the number of cores and return the appropriate value.
+    Validate the number of cores and return the number of workers to use.
+
+    Precedence: max_cores / cores_per_worker > max_workers > CPU count (with warning).
+
+    Args:
+        max_cores (int, optional): Total number of cores available.
+        max_workers (int, optional): Explicit number of parallel workers.
+        cores_per_worker (int, optional): Number of cores allocated to each worker. Defaults to 1.
+        set_local_cores (bool): When True, fall back to the local CPU count if neither
+            max_cores nor max_workers is given instead of raising an error. Defaults to False.
+
+    Returns:
+        int: Number of parallel workers to use.
+
+    Raises:
+        ValueError: If neither max_cores nor max_workers is set and set_local_cores is False.
     """
     if max_cores is not None and max_workers is None and cores_per_worker is not None:
         return int(max_cores / cores_per_worker)

executorlib/standalone/interactive/arguments.py

@@ -27,10 +27,21 @@ def get_future_objects_from_input(args: tuple, kwargs: dict):
 
     find_future_in_list(lst=args)
     find_future_in_list(lst=kwargs.values())
-    boolean_flag = len([future for future in future_lst if future.done()]) == len(
-        future_lst
-    )
-    return future_lst, boolean_flag
+
+    return future_lst
+
+
+def check_list_of_futures_is_done(future_lst: list[Future]) -> bool:
+    """
+    Check if all future objects in the list of future objects are done
+
+    Args:
+        future_lst (list): list of future objects
+
+    Returns:
+        bool: True if all future objects in the list of future objects are done, False otherwise
+    """
+    return len([future for future in future_lst if future.done()]) == len(future_lst)
 
 
 def get_exception_lst(future_lst: list[Future]) -> list:

executorlib/standalone/interactive/communication.py

@@ -240,6 +240,9 @@ def interface_connect(host: str, port: str) -> tuple[zmq.Context, zmq.Socket]:
     Args:
         host (str): hostname of the host running the SocketInterface instance to connect to.
         port (str): port on the host the SocketInterface instance is running on.
+
+    Returns:
+        Tuple[zmq.Context, zmq.Socket]: The ZMQ context and the connected PAIR socket.
     """
     context = zmq.Context()
     socket = context.socket(zmq.PAIR)
@@ -265,6 +268,9 @@ def interface_receive(socket: Optional[zmq.Socket]) -> dict:
 
     Args:
         socket (zmq.Socket): socket for the connection
+
+    Returns:
+        dict: Deserialized dictionary received from the socket, or an empty dict if socket is None.
     """
     if socket is not None:
         return cloudpickle.loads(socket.recv())

executorlib/standalone/select.py

@@ -3,21 +3,51 @@ from typing import Any, Optional
 
 
 class FutureSelector(Future):
+    """
+    A Future wrapper that returns a single element from a result that is a tuple, list, or dict.
+
+    This is used by split_future() and get_item_from_future() to give callers an individual
+    Future-like object for each output of a function that returns a collection.
+
+    Args:
+        future (Future): The underlying future whose result is a collection.
+        selector (int | str): Index (for sequences) or key (for mappings) used to extract
+            the desired element from the result.
+    """
+
     def __init__(self, future: Future, selector: int | str):
+        """
+        Args:
+            future (Future): The underlying future whose result is a collection.
+            selector (int | str): Index or key used to extract an element from the result.
+        """
         self._future = future
         self._selector = selector
         super().__init__()
 
     def __getattr__(self, attr: str) -> Any:
+        """Delegate attribute access to the wrapped future."""
         return getattr(self._future, attr)
 
     def __setattr__(self, name: str, value: Any):
+        """Set attributes on the wrapped future, except for the two private instance variables."""
         if name in ["_future", "_selector"]:
             super().__setattr__(name, value)
         else:
             setattr(self._future, name, value)
 
     def result(self, timeout: Optional[float] = None) -> Any:
+        """
+        Return the selected element from the underlying future's result.
+
+        Args:
+            timeout (float, optional): Maximum seconds to wait for the result. Defaults to None
+                (wait indefinitely).
+
+        Returns:
+            Any: The element at position/key ``selector`` in the underlying result, or None if
+                the underlying result is None.
+        """
         result = self._future.result(timeout=timeout)
         if result is not None:
             return result[self._selector]

executorlib/standalone/serialize.py

@@ -102,6 +102,18 @@ def _get_hash(binary: bytes) -> str:
 
 
 def _get_function_name(fn: Callable) -> str:
+    """
+    Return a human-readable name for a callable.
+
+    For regular functions and methods the ``__name__`` attribute is used. For callable objects
+    (classes implementing ``__call__``) the class name is extracted from ``__class__``.
+
+    Args:
+        fn (Callable): The callable whose name should be determined.
+
+    Returns:
+        str: A short name string suitable for use as part of a cache key prefix.
+    """
     if hasattr(fn, "__name__"):
         return fn.__name__
     else:

executorlib/standalone/validate.py

@@ -14,6 +14,25 @@ except ImportError:
 
 
 class ResourceDictValidation(BaseModel):
+    """
+    Pydantic (or dataclass fallback) model for validating resource dictionaries passed to task submissions.
+
+    Attributes:
+        cores (int, optional): Number of MPI cores to be used for each function call.
+        threads_per_core (int, optional): Number of OpenMP threads to be used for each function call.
+        gpus_per_core (int, optional): Number of GPUs per worker.
+        cwd (str, optional): Current working directory where the parallel python task is executed.
+        cache_key (str, optional): External cache key to identify tasks on the file system.
+        cache_directory (str, optional): The directory to store cache files.
+        num_nodes (int, optional): Number of compute nodes used for the evaluation.
+        exclusive (bool, optional): Reserve exclusive access to selected compute nodes.
+        error_log_file (str, optional): Path to the error log file.
+        run_time_max (int, optional): Maximum allowed execution time in seconds.
+        priority (int, optional): Queuing system priority for the task.
+        slurm_cmd_args (list[str], optional): Additional command line arguments for the srun call.
+        submission_template (str, optional): Template for queuing system job submission scripts.
+    """
+
     cores: Optional[int] = None
     threads_per_core: Optional[int] = None
     gpus_per_core: Optional[int] = None
@@ -23,7 +42,7 @@ class ResourceDictValidation(BaseModel):
     num_nodes: Optional[int] = None
     exclusive: Optional[bool] = None
     error_log_file: Optional[str] = None
-    run_time_limit: Optional[int] = None
+    run_time_max: Optional[int] = None
     priority: Optional[int] = None
     slurm_cmd_args: Optional[list[str]] = None
     submission_template: Optional[str] = None
@@ -39,6 +58,18 @@ if not HAS_PYDANTIC:
 
 
 def _get_accepted_keys(class_type) -> list[str]:
+    """
+    Return a list of accepted field names from a Pydantic model or dataclass.
+
+    Args:
+        class_type: A Pydantic BaseModel subclass or a dataclass.
+
+    Returns:
+        list[str]: Field names declared on the class.
+
+    Raises:
+        TypeError: If the class type is neither a Pydantic model nor a dataclass.
+    """
     if hasattr(class_type, "model_fields"):
         return list(class_type.model_fields.keys())
     elif hasattr(class_type, "__dataclass_fields__"):
@@ -47,10 +78,32 @@ def _get_accepted_keys(class_type) -> list[str]:
 
 
 def validate_resource_dict(resource_dict: dict) -> None:
+    """
+    Validate a resource dictionary against the declared fields of ResourceDictValidation.
+
+    Args:
+        resource_dict (dict): Dictionary of resource requirements to validate. Unknown keys raise
+            a validation error when pydantic is available.
+
+    Raises:
+        ValidationError: If any key/value pair violates the ResourceDictValidation schema.
+    """
     _ = ResourceDictValidation(**resource_dict)
 
 
 def validate_resource_dict_with_optional_keys(resource_dict: dict) -> None:
+    """
+    Validate a resource dictionary, allowing unknown keys with a warning instead of an error.
+
+    Known keys are validated against ResourceDictValidation. Unknown keys are collected and
+    emitted as a UserWarning so callers can detect unsupported options without hard failure.
+
+    Args:
+        resource_dict (dict): Dictionary of resource requirements to validate.
+
+    Raises:
+        ValidationError: If any known key/value pair violates the ResourceDictValidation schema.
+    """
     accepted_keys = _get_accepted_keys(class_type=ResourceDictValidation)
     optional_lst = [key for key in resource_dict if key not in accepted_keys]
     validate_dict = {