hpcflow-new2 0.2.0a179__py3-none-any.whl → 0.2.0a181__py3-none-any.whl

hpcflow/sdk/core/environment.py

@@ -1,3 +1,7 @@
+"""
+Model of an execution environment.
+"""
+
 from __future__ import annotations
 
 from dataclasses import dataclass
@@ -14,8 +18,24 @@ from hpcflow.sdk.core.utils import check_valid_py_identifier, get_duplicate_item
 
 @dataclass
 class NumCores(JSONLike):
+    """
+    A range of cores supported by an executable instance.
+
+    Parameters
+    ----------
+    start:
+        The minimum number of cores supported.
+    stop:
+        The maximum number of cores supported.
+    step: int
+        The step in the number of cores supported. Defaults to 1.
+    """
+
+    #: The minimum number of cores supported.
     start: int
+    #: The maximum number of cores supported.
     stop: int
+    #: The step in the number of cores supported. Normally 1.
     step: int = None
 
     def __post_init__(self):
@@ -41,8 +61,24 @@ class NumCores(JSONLike):
 
 @dataclass
 class ExecutableInstance(JSONLike):
+    """
+    A particular instance of an executable that can support some mode of operation.
+
+    Parameters
+    ----------
+    parallel_mode:
+        What parallel mode is supported by this executable instance.
+    num_cores: NumCores | int | dict[str, int]
+        The number of cores supported by this executable instance.
+    command:
+        The actual command to use for this executable instance.
+    """
+
+    #: What parallel mode is supported by this executable instance.
     parallel_mode: str
+    #: The number of cores supported by this executable instance.
     num_cores: Any
+    #: The actual command to use for this executable instance.
     command: str
 
     def __post_init__(self):
@@ -63,10 +99,24 @@ class ExecutableInstance(JSONLike):
 
     @classmethod
     def from_spec(cls, spec):
+        """
+        Construct an instance from a specification dictionary.
+        """
         return cls(**spec)
 
 
 class Executable(JSONLike):
+    """
+    A program managed by the environment.
+
+    Parameters
+    ----------
+    label:
+        The abstract name of the program.
+    instances: list[ExecutableInstance]
+        The concrete instances of the application that may be present.
+    """
+
     _child_objects = (
         ChildObjectSpec(
             name="instances",
@@ -76,7 +126,9 @@ class Executable(JSONLike):
     )
 
     def __init__(self, label: str, instances: List[app.ExecutableInstance]):
+        #: The abstract name of the program.
         self.label = check_valid_py_identifier(label)
+        #: The concrete instances of the application that may be present.
         self.instances = instances
 
         self._executables_list = None  # assigned by parent
@@ -101,9 +153,28 @@ class Executable(JSONLike):
 
     @property
     def environment(self):
+        """
+        The environment that the executable is going to run in.
+        """
         return self._executables_list.environment
 
     def filter_instances(self, parallel_mode=None, num_cores=None):
+        """
+        Select the instances of the executable that are compatible with the given
+        requirements.
+
+        Parameters
+        ----------
+        parallel_mode: str
+            If given, the parallel mode to require.
+        num_cores:  int
+            If given, the number of cores desired.
+
+        Returns
+        -------
+        list[ExecutableInstance]:
+            The known executable instances that match the requirements.
+        """
         out = []
         for i in self.instances:
             if parallel_mode is None or i.parallel_mode == parallel_mode:
@@ -113,6 +184,22 @@ class Executable(JSONLike):
 
 
 class Environment(JSONLike):
+    """
+    An execution environment that contains a number of executables.
+
+    Parameters
+    ----------
+    name: str
+        The name of the environment.
+    setup: list[str]
+        Commands to run to enter the environment.
+    specifiers: dict[str, str]
+        Dictionary of attributes that may be used to supply addional key/value pairs to
+        look up an environment by.
+    executables: list[Executable]
+        List of abstract executables in the environment.
+    """
+
     _hash_value = None
     _validation_schema = "environments_spec_schema.yaml"
     _child_objects = (
@@ -126,9 +213,14 @@ class Environment(JSONLike):
     def __init__(
         self, name, setup=None, specifiers=None, executables=None, _hash_value=None
     ):
+        #: The name of the environment.
         self.name = name
+        #: Commands to run to enter the environment.
         self.setup = setup
+        #: Dictionary of attributes that may be used to supply addional key/value pairs
+        #: to look up an environment by.
         self.specifiers = specifiers or {}
+        #: List of abstract executables in the environment.
         self.executables = (
             executables
             if isinstance(executables, ExecutablesList)

hpcflow/sdk/core/errors.py

@@ -1,32 +1,59 @@
+"""
+Errors from the workflow system.
+"""
+
 import os
 from typing import Iterable, List
 
 
 class InputValueDuplicateSequenceAddress(ValueError):
-    pass
+    """
+    An InputValue has the same sequence address twice.
+    """
 
 
 class TaskTemplateMultipleSchemaObjectives(ValueError):
-    pass
+    """
+    A TaskTemplate has multiple objectives.
+    """
 
 
 class TaskTemplateUnexpectedInput(ValueError):
-    pass
+    """
+    A TaskTemplate was given unexpected input.
+    """
 
 
 class TaskTemplateUnexpectedSequenceInput(ValueError):
-    pass
+    """
+    A TaskTemplate was given an unexpected sequence.
+    """
 
 
 class TaskTemplateMultipleInputValues(ValueError):
-    pass
+    """
+    A TaskTemplate had multiple input values bound over each other.
+    """
 
 
 class InvalidIdentifier(ValueError):
-    pass
+    """
+    A bad identifier name was given.
+    """
 
 
 class MissingInputs(Exception):
+    """
+    Inputs were missing.
+
+    Parameters
+    ----------
+    message: str
+        The message of the exception.
+    missing_inputs: list[str]
+        The missing inputs.
+    """
+
     # TODO: add links to doc pages for common user-exceptions?
 
     def __init__(self, message, missing_inputs) -> None:
@@ -35,6 +62,17 @@ class MissingInputs(Exception):
 
 
 class UnrequiredInputSources(ValueError):
+    """
+    Input sources were provided that were not required.
+
+    Parameters
+    ----------
+    message: str
+        The message of the exception.
+    unrequired_sources: list
+        The input sources that were not required.
+    """
+
     def __init__(self, message, unrequired_sources) -> None:
         self.unrequired_sources = unrequired_sources
         for src in unrequired_sources:
@@ -50,129 +88,199 @@ class UnrequiredInputSources(ValueError):
 
 
 class ExtraInputs(Exception):
+    """
+    Extra inputs were provided.
+
+    Parameters
+    ----------
+    message: str
+        The message of the exception.
+    extra_inputs: list
+        The extra inputs.
+    """
+
     def __init__(self, message, extra_inputs) -> None:
         self.extra_inputs = extra_inputs
         super().__init__(message)
 
 
 class UnavailableInputSource(ValueError):
-    pass
+    """
+    An input source was not available.
+    """
 
 
 class InapplicableInputSourceElementIters(ValueError):
-    pass
+    """
+    An input source element iteration was inapplicable."""
 
 
 class NoCoincidentInputSources(ValueError):
-    pass
+    """
+    Could not line up input sources to make an actual valid execution.
+    """
 
 
 class TaskTemplateInvalidNesting(ValueError):
-    pass
+    """
+    Invalid nesting in a task template.
+    """
 
 
 class TaskSchemaSpecValidationError(Exception):
-    pass
+    """
+    A task schema failed to validate.
+    """
 
 
 class WorkflowSpecValidationError(Exception):
-    pass
+    """
+    A workflow failed to validate.
+    """
 
 
 class InputSourceValidationError(Exception):
-    pass
+    """
+    An input source failed to validate.
+    """
 
 
 class EnvironmentSpecValidationError(Exception):
-    pass
+    """
+    An environment specification failed to validate.
+    """
 
 
 class ParameterSpecValidationError(Exception):
-    pass
+    """
+    A parameter specification failed to validate.
+    """
 
 
 class FileSpecValidationError(Exception):
-    pass
+    """
+    A file specification failed to validate.
+    """
 
 
 class DuplicateExecutableError(ValueError):
-    pass
+    """
+    The same executable was present twice in an executable environment.
+    """
 
 
 class MissingCompatibleActionEnvironment(Exception):
-    pass
+    """
+    Could not find a compatible action environment.
+    """
 
 
 class MissingActionEnvironment(Exception):
-    pass
+    """
+    Could not find an action environment.
+    """
 
 
 class ActionEnvironmentMissingNameError(Exception):
-    pass
+    """
+    An action environment was missing its name.
+    """
 
 
 class FromSpecMissingObjectError(Exception):
-    pass
+    """
+    Missing object when deserialising from specification.
+    """
 
 
 class TaskSchemaMissingParameterError(Exception):
-    pass
+    """
+    Parameter was missing from task schema.
+    """
 
 
 class ToJSONLikeChildReferenceError(Exception):
-    pass
+    """
+    Failed to generate or reference a child object when converting to JSON.
+    """
 
 
 class InvalidInputSourceTaskReference(Exception):
-    pass
+    """
+    Invalid input source in task reference.
+    """
 
 
 class WorkflowNotFoundError(Exception):
-    pass
+    """
+    Could not find the workflow.
+    """
 
 
 class MalformedWorkflowError(Exception):
-    pass
+    """
+    Workflow was a malformed document.
+    """
 
 
 class ValuesAlreadyPersistentError(Exception):
-    pass
+    """
+    Trying to make a value persistent that already is so.
+    """
 
 
 class MalformedParameterPathError(ValueError):
-    pass
+    """
+    The path to a parameter was ill-formed.
+    """
 
 
 class MalformedNestingOrderPath(ValueError):
-    pass
+    """
+    A nesting order path was ill-formed.
+    """
 
 
 class UnknownResourceSpecItemError(ValueError):
-    pass
+    """
+    A resource specification item was not found.
+    """
 
 
 class WorkflowParameterMissingError(AttributeError):
-    pass
+    """
+    A parameter to a workflow was missing.
+    """
 
 
 class WorkflowBatchUpdateFailedError(Exception):
-    pass
+    """
+    An update to a workflow failed.
+    """
 
 
 class WorkflowLimitsError(ValueError):
-    pass
+    """
+    Workflow hit limits.
+    """
 
 
 class UnsetParameterDataError(Exception):
-    pass
+    """
+    Tried to read from an unset parameter.
+    """
 
 
 class LoopAlreadyExistsError(Exception):
-    pass
+    """
+    A particular loop (or its name) already exists.
+    """
 
 
 class LoopTaskSubsetError(ValueError):
-    pass
+    """
+    Problem constructing a subset of a task for a loop.
+    """
 
 
 class SchedulerVersionsFailure(RuntimeError):
@@ -184,6 +292,10 @@ class SchedulerVersionsFailure(RuntimeError):
 
 
 class JobscriptSubmissionFailure(RuntimeError):
+    """
+    A job script could not be submitted to the scheduler.
+    """
+
     def __init__(
         self,
         message,
@@ -207,13 +319,19 @@ class JobscriptSubmissionFailure(RuntimeError):
 
 
 class SubmissionFailure(RuntimeError):
+    """
+    A job submission failed.
+    """
+
     def __init__(self, message) -> None:
         self.message = message
         super().__init__(message)
 
 
 class WorkflowSubmissionFailure(RuntimeError):
-    pass
+    """
+    A workflow submission failed.
+    """
 
 
 class ResourceValidationError(ValueError):
@@ -272,31 +390,45 @@ class UnsupportedSchedulerError(ResourceValidationError):
 
 
 class UnknownSGEPEError(ResourceValidationError):
-    pass
+    """
+    Miscellaneous error from SGE parallel environment.
+    """
 
 
 class IncompatibleSGEPEError(ResourceValidationError):
-    pass
+    """
+    The SGE parallel environment selected is incompatible.
+    """
 
 
 class NoCompatibleSGEPEError(ResourceValidationError):
-    pass
+    """
+    No SGE parallel environment is compatible with request.
+    """
 
 
 class IncompatibleParallelModeError(ResourceValidationError):
-    pass
+    """
+    The parallel mode is incompatible.
+    """
 
 
 class UnknownSLURMPartitionError(ResourceValidationError):
-    pass
+    """
+    The requested SLURM partition isn't known.
+    """
 
 
 class IncompatibleSLURMPartitionError(ResourceValidationError):
-    pass
+    """
+    The requested SLURM partition is incompatible.
+    """
 
 
 class IncompatibleSLURMArgumentsError(ResourceValidationError):
-    pass
+    """
+    The SLURM arguments are incompatible with each other.
+    """
 
 
 class _MissingStoreItemError(ValueError):
@@ -354,80 +486,132 @@ class MissingParameterData(_MissingStoreItemError):
 
 
 class NotSubmitMachineError(RuntimeError):
-    pass
+    """
+    The requested machine can't be submitted to.
+    """
 
 
 class RunNotAbortableError(ValueError):
-    pass
+    """
+    Cannot abort the run.
+    """
 
 
 class NoCLIFormatMethodError(AttributeError):
-    pass
+    """
+    Some CLI class lacks a format method
+    """
 
 
 class ContainerKeyError(KeyError):
+    """
+    A key could not be mapped in a container.
+
+    Parameters
+    ----------
+    path: list[str]
+        The path whose resolution failed.
+    """
+
     def __init__(self, path: List[str]) -> None:
         self.path = path
         super().__init__()
 
 
 class MayNeedObjectError(Exception):
+    """
+    An object is needed but not present.
+
+    Parameters
+    ----------
+    path: list[str]
+        The path whose resolution failed.
+    """
+
     def __init__(self, path):
         self.path = path
         super().__init__()
 
 
 class NoAvailableElementSetsError(Exception):
-    pass
+    """
+    No element set is available.
+    """
 
 
 class OutputFileParserNoOutputError(ValueError):
-    pass
+    """
+    There was no output for the output file parser to parse.
+    """
 
 
 class SubmissionEnvironmentError(ValueError):
-    """Raised when submitting a workflow on a machine without a compatible environment."""
+    """
+    Raised when submitting a workflow on a machine without a compatible environment.
+    """
 
 
 class MissingEnvironmentExecutableError(SubmissionEnvironmentError):
-    pass
+    """
+    The environment does not have the requested executable at all.
+    """
 
 
 class MissingEnvironmentExecutableInstanceError(SubmissionEnvironmentError):
-    pass
+    """
+    The environment does not have a suitable instance of the requested executable.
+    """
 
 
 class MissingEnvironmentError(SubmissionEnvironmentError):
-    pass
+    """
+    There is no environment with that name.
+    """
 
 
 class UnsupportedScriptDataFormat(ValueError):
-    pass
+    """
+    That format of script data is not supported.
+    """
 
 
 class UnknownScriptDataParameter(ValueError):
-    pass
+    """
+    Unknown parameter in script data.
+    """
 
 
 class UnknownScriptDataKey(ValueError):
-    pass
+    """
+    Unknown key in script data.
+    """
 
 
 class MissingVariableSubstitutionError(KeyError):
-    pass
+    """
+    No definition available of a variable being substituted.
+    """
 
 
 class EnvironmentPresetUnknownEnvironmentError(ValueError):
-    pass
+    """
+    An environment preset could not be resolved to an execution environment.
+    """
 
 
 class UnknownEnvironmentPresetError(ValueError):
-    pass
+    """
+    An execution environment was unknown.
+    """
 
 
 class MultipleEnvironmentsError(ValueError):
-    pass
+    """
+    Multiple applicable execution environments exist.
+    """
 
 
 class MissingElementGroup(ValueError):
-    pass
+    """
+    An element group should exist but doesn't.
+    """