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

hpcflow/sdk/core/parameters.py

@@ -1,3 +1,7 @@
+"""
+Parameters represent information passed around within a workflow.
+"""
+
 from __future__ import annotations
 import copy
 from dataclasses import dataclass, field
@@ -49,40 +53,74 @@ def _process_demo_data_strings(app, value):
 
 
 class ParameterValue:
+    """
+    The value handler for a parameter.
+
+    Intended to be subclassed.
+    """
+
     _typ = None
     _sub_parameters = {}
 
     def to_dict(self):
+        """
+        Serialise this parameter value as a dictionary.
+        """
         if hasattr(self, "__dict__"):
             return dict(self.__dict__)
         elif hasattr(self, "__slots__"):
             return {k: getattr(self, k) for k in self.__slots__}
 
     def prepare_JSON_dump(self) -> Dict:
+        """
+        Prepare this parameter value for serialisation as JSON.
+        """
         raise NotImplementedError
 
     def dump_to_HDF5_group(self, group):
+        """
+        Write this parameter value to an HDF5 group.
+        """
         raise NotImplementedError
 
     @classmethod
     def save_from_HDF5_group(cls, group, param_id: int, workflow):
+        """
+        Extract a parameter value from an HDF5 group.
+        """
         raise NotImplementedError
 
     @classmethod
     def save_from_JSON(cls, data, param_id: int, workflow):
+        """
+        Extract a parameter value from JSON data.
+        """
         raise NotImplementedError
 
 
 class ParameterPropagationMode(enum.Enum):
+    """
+    How a parameter is propagated.
+    """
+
+    #: Parameter is propagated implicitly.
     IMPLICIT = 0
+    #: Parameter is propagated explicitly.
     EXPLICIT = 1
+    #: Parameter is never propagated.
     NEVER = 2
 
 
 @dataclass
 class ParameterPath(JSONLike):
+    """
+    Path to a parameter.
+    """
+
     # TODO: unused?
+    #: The path to the parameter.
     path: Sequence[Union[str, int, float]]
+    #: The task in which to look up the parameter.
     task: Optional[
         Union[app.TaskTemplate, app.TaskSchema]
     ] = None  # default is "current" task
@@ -90,6 +128,28 @@ class ParameterPath(JSONLike):
 
 @dataclass
 class Parameter(JSONLike):
+    """
+    A general parameter to a workflow task.
+
+    Parameters
+    ----------
+    typ:
+        Type code.
+        Used to look up the :py:class:`ParameterValue` for this parameter,
+        if any.
+    is_file:
+        Whether this parameter represents a file.
+    sub_parameters: list[SubParameter]
+        Any parameters packed within this one.
+    _value_class: type[ParameterValue]
+        Class that provides the implementation of this parameter's values.
+        Not normally directly user-managed.
+    _hash_value:
+        Hash of this class. Not normally user-managed.
+    _validation:
+        Validation schema.
+    """
+
     _validation_schema = "parameters_spec_schema.yaml"
     _child_objects = (
         ChildObjectSpec(
@@ -102,8 +162,12 @@ class Parameter(JSONLike):
         ),
     )
 
+    #: Type code. Used to look up the :py:class:`ParameterValue` for this parameter,
+    #: if any.
     typ: str
+    #: Whether this parameter represents a file.
     is_file: bool = False
+    #: Any parameters packed within this one.
     sub_parameters: List[app.SubParameter] = field(default_factory=lambda: [])
     _value_class: Any = None
     _hash_value: Optional[str] = field(default=None, repr=False)
@@ -158,17 +222,35 @@ class Parameter(JSONLike):
 
     @property
     def url_slug(self) -> str:
+        """
+        Representation of this parameter as part of a URL.
+        """
         return self.typ.lower().replace("_", "-")
 
 
 @dataclass
 class SubParameter:
+    """
+    A parameter that is a component of another parameter.
+    """
+
+    #: How to find this within the containing paraneter.
     address: Address
+    #: The containing main parameter.
     parameter: app.Parameter
 
 
 @dataclass
 class SchemaParameter(JSONLike):
+    """
+    A parameter bound in a schema.
+
+    Parameters
+    ----------
+    parameter: Parameter
+        The parameter.
+    """
+
     _app_attr = "app"
 
     _child_objects = (
@@ -189,14 +271,26 @@ class SchemaParameter(JSONLike):
 
     @property
     def name(self):
+        """
+        The name of the parameter.
+        """
         return self.parameter.name
 
     @property
     def typ(self):
+        """
+        The type code of the parameter.
+        """
         return self.parameter.typ
 
 
 class NullDefault(enum.Enum):
+    """
+    Sentinel value used to distinguish an explicit null.
+    """
+
+    #: Special sentinel.
+    #: Used in situations where otherwise a JSON object or array would be.
     NULL = 0
 
 
@@ -206,13 +300,13 @@ class SchemaInput(SchemaParameter):
 
     Parameters
     ----------
-    parameter
+    parameter:
         The parameter (i.e. type) of this schema input.
-    multiple
+    multiple:
         If True, expect one or more of these parameters defined in the workflow,
         distinguished by a string label in square brackets. For example `p1[0]` for a
         parameter `p1`.
-    labels
+    labels:
         Dict whose keys represent the string labels that distinguish multiple parameters
         if `multiple` is `True`. Use the key "*" to mean all labels not matching
         other label keys. If `multiple` is `False`, this will default to a
@@ -220,10 +314,10 @@ class SchemaInput(SchemaParameter):
         `True`, this will default to a single-item dict with the catch-all key:
         `{{"*": {{}}}}`. On initialisation, remaining keyword-arguments are treated as default
         values for the dict values of `labels`.
-    default_value
+    default_value:
         The default value for this input parameter. This is itself a default value that
         will be applied to all `labels` values if a "default_value" key does not exist.
-    propagation_mode
+    propagation_mode:
         Determines how this input should propagate through the workflow. This is a default
         value that will be applied to all `labels` values if a "propagation_mode" key does
         not exist. By default, the input is allowed to be used in downstream tasks simply
@@ -232,7 +326,7 @@ class SchemaInput(SchemaParameter):
         the downstream task `input_sources` for it to be used, and "never", meaning that
         the parameter must not be used in downstream tasks and will be inaccessible to
         those tasks.
-    group
+    group:
         Determines the name of the element group from which this input should be sourced.
         This is a default value that will be applied to all `labels` if a "group" key
         does not exist.
@@ -270,8 +364,12 @@ class SchemaInput(SchemaParameter):
             except ValueError:
                 parameter = self.app.Parameter(parameter)
 
+        #: The parameter (i.e. type) of this schema input.
         self.parameter = parameter
+        #: Whether to expect more than of these parameters defined in the workflow.
         self.multiple = multiple
+        #: Dict whose keys represent the string labels that distinguish multiple
+        #: parameters if `multiple` is `True`.
         self.labels = labels
 
         if self.labels is None:
@@ -395,6 +493,9 @@ class SchemaInput(SchemaParameter):
 
     @property
     def default_value(self):
+        """
+        The default value of the input.
+        """
         if not self.multiple:
             if "default_value" in self.single_labelled_data:
                 return self.single_labelled_data["default_value"]
@@ -403,28 +504,46 @@ class SchemaInput(SchemaParameter):
 
     @property
     def task_schema(self):
+        """
+        The schema containing this input.
+        """
         return self._task_schema
 
     @property
     def all_labelled_types(self):
+        """
+        The types of the input labels.
+        """
         return list(f"{self.typ}{f'[{i}]' if i else ''}" for i in self.labels)
 
     @property
     def single_label(self):
+        """
+        The label of this input, assuming it is not mulitple.
+        """
         if not self.multiple:
             return next(iter(self.labels))
 
     @property
     def single_labelled_type(self):
+        """
+        The type code of this input, assuming it is not mulitple.
+        """
         if not self.multiple:
             return next(iter(self.labelled_info()))["labelled_type"]
 
     @property
     def single_labelled_data(self):
+        """
+        The value of this input, assuming it is not mulitple.
+        """
         if not self.multiple:
             return self.labels[self.single_label]
 
     def labelled_info(self):
+        """
+        Get descriptors for all the labels associated with this input.
+        """
         for k, v in self.labels.items():
             label = f"[{k}]" if k else ""
             dct = {
@@ -458,6 +577,9 @@ class SchemaInput(SchemaParameter):
 
     @property
     def input_or_output(self):
+        """
+        Whether this is an input or output. Always ``input``.
+        """
         return "input"
 
 
@@ -465,11 +587,16 @@ class SchemaInput(SchemaParameter):
 class SchemaOutput(SchemaParameter):
     """A Parameter as outputted from particular task."""
 
+    #: The basic parameter this supplies.
     parameter: Parameter
+    #: How this output propagates.
     propagation_mode: ParameterPropagationMode = ParameterPropagationMode.IMPLICIT
 
     @property
     def input_or_output(self):
+        """
+        Whether this is an input or output. Always ``output``.
+        """
         return "output"
 
     def __repr__(self) -> str:
@@ -483,6 +610,11 @@ class SchemaOutput(SchemaParameter):
 
 @dataclass
 class BuiltinSchemaParameter:
+    """
+    A parameter of a built-in schema.
+    """
+
+    # TODO: Is this used anywhere?
     # builtin inputs (resources,parameter_perturbations,method,implementation
     # builtin outputs (time, memory use, node/hostname etc)
     # - builtin parameters do not propagate to other tasks (since all tasks define the same
@@ -493,6 +625,23 @@ class BuiltinSchemaParameter:
 
 
 class ValueSequence(JSONLike):
+    """
+    A sequence of values.
+
+    Parameters
+    ----------
+    path:
+        The path to this sequence.
+    values:
+        The values in this sequence.
+    nesting_order: int
+        A nesting order for this sequence. Can be used to compose sequences together.
+    label: str
+        A label for this sequence.
+    value_class_method: str
+        Name of a method used to generate sequence values. Not normally used directly.
+    """
+
     def __init__(
         self,
         path: str,
@@ -504,9 +653,13 @@ class ValueSequence(JSONLike):
         label = str(label) if label is not None else ""
         path, label = self._validate_parameter_path(path, label)
 
+        #: The path to this sequence.
         self.path = path
+        #: The label of this sequence.
         self.label = label
+        #: The nesting order for this sequence.
         self.nesting_order = nesting_order
+        #: Name of a method used to generate sequence values.
         self.value_class_method = value_class_method
 
         if values is not None:
@@ -603,30 +756,48 @@ class ValueSequence(JSONLike):
 
     @property
     def parameter(self):
+        """
+        The parameter this sequence supplies.
+        """
         return self._parameter
 
     @property
     def path_split(self):
+        """
+        The components of ths path.
+        """
         if self._path_split is None:
             self._path_split = self.path.split(".")
         return self._path_split
 
     @property
     def path_type(self):
+        """
+        The type of path this is.
+        """
         return self.path_split[0]
 
     @property
     def input_type(self):
+        """
+        The type of input sequence this is, if it is one.
+        """
         if self.path_type == "inputs":
             return self.path_split[1].replace(self._label_fmt, "")
 
     @property
     def input_path(self):
+        """
+        The path of the input sequence this is, if it is one.
+        """
         if self.path_type == "inputs":
             return ".".join(self.path_split[2:])
 
     @property
     def resource_scope(self):
+        """
+        The scope of the resources this is, if it is one.
+        """
         if self.path_type == "resources":
             return self.path_split[1]
 
@@ -641,6 +812,9 @@ class ValueSequence(JSONLike):
 
     @property
     def labelled_type(self):
+        """
+        The labelled type of input sequence this is, if it is one.
+        """
         if self.input_type:
             return f"{self.input_type}{self._label_fmt}"
 
@@ -750,12 +924,17 @@ class ValueSequence(JSONLike):
 
     @property
     def normalised_path(self):
+        """
+        The path to this sequence.
+        """
         return self.path
 
     @property
     def normalised_inputs_path(self):
-        """Return the normalised path without the "inputs" prefix, if the sequence is an
-        inputs sequence, else return None."""
+        """
+        The normalised path without the "inputs" prefix, if the sequence is an
+        inputs sequence, else return None.
+        """
 
         if self.input_type:
             if self.input_path:
@@ -802,6 +981,9 @@ class ValueSequence(JSONLike):
 
     @property
     def workflow(self):
+        """
+        The workflow containing this sequence.
+        """
         if self._workflow:
             return self._workflow
         elif self._element_set:
@@ -809,6 +991,9 @@ class ValueSequence(JSONLike):
 
     @property
     def values(self):
+        """
+        The values in this sequence.
+        """
         if self._values_group_idx is not None:
             vals = []
             for idx, pg_idx_i in enumerate(self._values_group_idx):
@@ -885,6 +1070,9 @@ class ValueSequence(JSONLike):
         label=None,
         **kwargs,
     ):
+        """
+        Build a sequence from a NumPy linear space.
+        """
         # TODO: save persistently as an array?
         args = {"start": start, "stop": stop, "num": num, **kwargs}
         values = cls._values_from_linear_space(**args)
@@ -905,6 +1093,9 @@ class ValueSequence(JSONLike):
         label=None,
         **kwargs,
     ):
+        """
+        Build a sequence from a NumPy geometric space.
+        """
         args = {"start": start, "stop": stop, "num": num, "endpoint": endpoint, **kwargs}
         values = cls._values_from_geometric_space(**args)
         obj = cls(values=values, path=path, nesting_order=nesting_order, label=label)
@@ -925,6 +1116,9 @@ class ValueSequence(JSONLike):
         label=None,
         **kwargs,
     ):
+        """
+        Build a sequence from a NumPy logarithmic space.
+        """
         args = {
             "start": start,
             "stop": stop,
@@ -950,6 +1144,9 @@ class ValueSequence(JSONLike):
         label=None,
         **kwargs,
     ):
+        """
+        Build a sequence from a range.
+        """
         # TODO: save persistently as an array?
         args = {"start": start, "stop": stop, "step": step, **kwargs}
         if isinstance(step, int):
@@ -982,6 +1179,9 @@ class ValueSequence(JSONLike):
         label=None,
         **kwargs,
     ):
+        """
+        Build a sequence from a simple file.
+        """
         args = {"file_path": file_path, **kwargs}
         values = cls._values_from_file(**args)
         obj = cls(
@@ -1009,6 +1209,8 @@ class ValueSequence(JSONLike):
         **kwargs,
     ):
         """
+        Build a sequence to cover a rectangle.
+
         Parameters
         ----------
         coord:
@@ -1044,6 +1246,9 @@ class ValueSequence(JSONLike):
         label=None,
         **kwargs,
     ):
+        """
+        Build a sequence from a uniform random number generator.
+        """
         args = {"low": low, "high": high, "num": num, "seed": seed, **kwargs}
         values = cls._values_from_random_uniform(**args)
         obj = cls(values=values, path=path, nesting_order=nesting_order, label=label)
@@ -1111,6 +1316,9 @@ class AbstractInputValue(JSONLike):
 
     @property
     def workflow(self):
+        """
+        The workflow containing this input value.
+        """
         if self._workflow:
             return self._workflow
         elif self._element_set:
@@ -1120,6 +1328,9 @@ class AbstractInputValue(JSONLike):
 
     @property
     def value(self):
+        """
+        The value itself.
+        """
         if self._value_group_idx is not None:
             val = self.workflow.get_parameter_data(self._value_group_idx)
             if self._value_is_obj and self.parameter._value_class:
@@ -1132,31 +1343,44 @@ class AbstractInputValue(JSONLike):
 
 @dataclass
 class ValuePerturbation(AbstractInputValue):
+    """
+    A perturbation applied to a value.
+    """
+
+    #: The name of this perturbation.
     name: str
+    #: The path to the value(s) to perturb.
     path: Optional[Sequence[Union[str, int, float]]] = None
+    #: The multiplicative factor to apply.
     multiplicative_factor: Optional[Numeric] = 1
+    #: The additive factor to apply.
     additive_factor: Optional[Numeric] = 0
 
     @classmethod
     def from_spec(cls, spec):
+        """
+        Construct an instance from a specification dictionary.
+        """
         return cls(**spec)
 
 
 class InputValue(AbstractInputValue):
     """
+    An input value to a task.
+
     Parameters
     ----------
-    parameter
-        Parameter whose value is to be specified
-    label
+    parameter: Parameter | SchemaInput | str
+        Parameter whose value is to be specified.
+    label: str
         Optional identifier to be used where the associated `SchemaInput` accepts multiple
         parameters of the specified type. This will be cast to a string.
-    value
+    value: Any
         The input parameter value.
-    value_class_method
+    value_class_method: How to obtain the real value.
         A class method that can be invoked with the `value` attribute as keyword
         arguments.
-    path
+    path: str
         Dot-delimited path within the parameter's nested data structure for which `value`
         should be set.
 
@@ -1188,9 +1412,16 @@ class InputValue(AbstractInputValue):
         elif isinstance(parameter, SchemaInput):
             parameter = parameter.parameter
 
+        #: Parameter whose value is to be specified.
         self.parameter = parameter
+        #: Identifier to be used where the associated `SchemaInput` accepts multiple
+        #: parameters of the specified type.
         self.label = str(label) if label is not None else ""
+        #: Dot-delimited path within the parameter's nested data structure for which
+        #: `value` should be set.
         self.path = (path.strip(".") if path else None) or None
+        #: A class method that can be invoked with the `value` attribute as keyword
+        #: arguments.
         self.value_class_method = value_class_method
         self._value = _process_demo_data_strings(self.app, value)
 
@@ -1293,15 +1524,24 @@ class InputValue(AbstractInputValue):
 
     @property
     def labelled_type(self):
+        """
+        The labelled type of this input value.
+        """
         label = f"[{self.label}]" if self.label else ""
         return f"{self.parameter.typ}{label}"
 
     @property
     def normalised_inputs_path(self):
+        """
+        The normalised input path without the ``inputs.`` prefix.
+        """
         return f"{self.labelled_type}{f'.{self.path}' if self.path else ''}"
 
     @property
     def normalised_path(self):
+        """
+        The full normalised input path.
+        """
         return f"inputs.{self.normalised_inputs_path}"
 
     def make_persistent(self, workflow: Any, source: Dict) -> Tuple[str, List[int], bool]:
@@ -1347,8 +1587,55 @@ class ResourceSpec(JSONLike):
     `os_name` is used for retrieving a default shell name and for retrieving the correct
     `Shell` class; when using WSL, it should still be `nt` (i.e. Windows).
 
+    Parameters
+    ----------
+    scope:
+        Which scope does this apply to.
+    scratch: str
+        Which scratch space to use.
+    parallel_mode: ParallelMode
+        Which parallel mode to use.
+    num_cores: int
+        How many cores to request.
+    num_cores_per_node: int
+        How many cores per compute node to request.
+    num_threads: int
+        How many threads to request.
+    num_nodes: int
+        How many compute nodes to request.
+    scheduler: str
+        Which scheduler to use.
+    shell: str
+        Which system shell to use.
+    use_job_array: bool
+        Whether to use array jobs.
+    max_array_items: int
+        If using array jobs, up to how many items should be in the job array.
+    time_limit: str
+        How long to run for.
+    scheduler_args: dict[str, Any]
+        Additional arguments to pass to the scheduler.
+    shell_args: dict[str, Any]
+        Additional arguments to pass to the shell.
+    os_name: str
+        Which OS to use.
+    environments: dict
+        Which execution environments to use.
+    SGE_parallel_env: str
+        Which SGE parallel environment to request.
+    SLURM_partition: str
+        Which SLURM partition to request.
+    SLURM_num_tasks: str
+        How many SLURM tasks to request.
+    SLURM_num_tasks_per_node: str
+        How many SLURM tasks per compute node to request.
+    SLURM_num_nodes: str
+        How many compute nodes to request.
+    SLURM_num_cpus_per_task: str
+        How many CPU cores to ask for per SLURM task.
     """
 
+    #: The names of parameters that may be used when making an instance of this class.
     ALLOWED_PARAMETERS = {
         "scratch",
         "parallel_mode",
@@ -1407,6 +1694,7 @@ class ResourceSpec(JSONLike):
         SLURM_num_nodes: Optional[str] = None,
         SLURM_num_cpus_per_task: Optional[str] = None,
     ):
+        #: Which scope does this apply to.
         self.scope = scope or self.app.ActionScope.any()
         if not isinstance(self.scope, self.app.ActionScope):
             self.scope = self.app.ActionScope.from_json_like(self.scope)
@@ -1498,10 +1786,16 @@ class ResourceSpec(JSONLike):
 
     @property
     def normalised_resources_path(self):
+        """
+        Standard name of this resource spec.
+        """
         return self.scope.to_string()
 
     @property
     def normalised_path(self):
+        """
+        Full name of this resource spec.
+        """
         return f"resources.{self.normalised_resources_path}"
 
     def to_dict(self):
@@ -1596,31 +1890,55 @@ class ResourceSpec(JSONLike):
 
     @property
     def scratch(self):
-        # TODO: currently unused, except in tests
+        """
+        Which scratch space to use.
+
+        Todo
+        ----
+        Currently unused, except in tests.
+        """
         return self._get_value("scratch")
 
     @property
     def parallel_mode(self):
+        """
+        Which parallel mode to use.
+        """
         return self._get_value("parallel_mode")
 
     @property
     def num_cores(self):
+        """
+        How many cores to request.
+        """
         return self._get_value("num_cores")
 
     @property
     def num_cores_per_node(self):
+        """
+        How many cores per compute node to request.
+        """
         return self._get_value("num_cores_per_node")
 
     @property
     def num_nodes(self):
+        """
+        How many compute nodes to request.
+        """
         return self._get_value("num_nodes")
 
     @property
     def num_threads(self):
+        """
+        How many threads to request.
+        """
         return self._get_value("num_threads")
 
     @property
     def scheduler(self):
+        """
+        Which scheduler to use.
+        """
         return self._get_value("scheduler")
 
     @scheduler.setter
@@ -1631,6 +1949,9 @@ class ResourceSpec(JSONLike):
 
     @property
     def shell(self):
+        """
+        Which system shell to use.
+        """
         return self._get_value("shell")
 
     @shell.setter
@@ -1641,54 +1962,93 @@ class ResourceSpec(JSONLike):
 
     @property
     def use_job_array(self):
+        """
+        Whether to use array jobs.
+        """
         return self._get_value("use_job_array")
 
     @property
     def max_array_items(self):
+        """
+        If using array jobs, up to how many items should be in the job array.
+        """
         return self._get_value("max_array_items")
 
     @property
     def time_limit(self):
+        """
+        How long to run for.
+        """
         return self._get_value("time_limit")
 
     @property
     def scheduler_args(self):
+        """
+        Additional arguments to pass to the scheduler.
+        """
         return self._get_value("scheduler_args")
 
     @property
     def shell_args(self):
+        """
+        Additional arguments to pass to the shell.
+        """
         return self._get_value("shell_args")
 
     @property
     def os_name(self):
+        """
+        Which OS to use.
+        """
         return self._get_value("os_name")
 
     @property
     def environments(self):
+        """
+        Which execution environments to use.
+        """
         return self._get_value("environments")
 
     @property
     def SGE_parallel_env(self):
+        """
+        Which SGE parallel environment to request.
+        """
         return self._get_value("SGE_parallel_env")
 
     @property
     def SLURM_partition(self):
+        """
+        Which SLURM partition to request.
+        """
         return self._get_value("SLURM_partition")
 
     @property
     def SLURM_num_tasks(self):
+        """
+        How many SLURM tasks to request.
+        """
         return self._get_value("SLURM_num_tasks")
 
     @property
     def SLURM_num_tasks_per_node(self):
+        """
+        How many SLURM tasks per compute node to request.
+        """
         return self._get_value("SLURM_num_tasks_per_node")
 
     @property
     def SLURM_num_nodes(self):
+        """
+        How many compute nodes to request.
+        """
         return self._get_value("SLURM_num_nodes")
 
     @property
     def SLURM_num_cpus_per_task(self):
+        """
+        How many CPU cores to ask for per SLURM task.
+        """
         return self._get_value("SLURM_num_cpus_per_task")
 
     @os_name.setter
@@ -1698,6 +2058,9 @@ class ResourceSpec(JSONLike):
 
     @property
     def workflow(self):
+        """
+        The workflow owning this resource spec.
+        """
         if self._workflow:
             return self._workflow
 
@@ -1718,27 +2081,69 @@ class ResourceSpec(JSONLike):
 
     @property
     def element_set(self):
+        """
+        The element set that will use this resource spec.
+        """
         return self._resource_list.element_set
 
     @property
     def workflow_template(self):
+        """
+        The workflow template that will use this resource spec.
+        """
         return self._resource_list.workflow_template
 
 
 class InputSourceType(enum.Enum):
+    """
+    The types if input sources.
+    """
+
+    #: Input source is an import.
     IMPORT = 0
+    #: Input source is local.
     LOCAL = 1
+    #: Input source is a default.
     DEFAULT = 2
+    #: Input source is a task.
     TASK = 3
 
 
 class TaskSourceType(enum.Enum):
+    """
+    The types of task-based input sources.
+    """
+
+    #: Input source is a task input.
     INPUT = 0
+    #: Input source is a task output.
     OUTPUT = 1
+    #: Input source is unspecified.
     ANY = 2
 
 
 class InputSource(JSONLike):
+    """
+    An input source to a workflow task.
+
+    Parameters
+    ----------
+    source_type: InputSourceType
+        Type of the input source.
+    import_ref:
+        Where the input comes from when the type is `IMPORT`.
+    task_ref:
+        Which task is this an input for? Used when the type is `TASK`.
+    task_source_type: TaskSourceType
+        Type of task source.
+    element_iters:
+        Which element iterations does this apply to?
+    path:
+        Path to where this input goes.
+    where: ~hpcflow.app.Rule | list[~hpcflow.app.Rule] | ~hpcflow.app.ElementFilter
+        Filtering rules.
+    """
+
     _child_objects = (
         ChildObjectSpec(
             name="source_type",
@@ -1769,12 +2174,19 @@ class InputSource(JSONLike):
                     rules[idx] = app.Rule(**i)
             where = app.ElementFilter(rules=rules)
 
+        #: Type of the input source.
         self.source_type = self._validate_source_type(source_type)
+        #: Where the input comes from when the type is `IMPORT`.
         self.import_ref = import_ref
+        #: Which task is this an input for? Used when the type is `TASK`.
         self.task_ref = task_ref
+        #: Type of task source.
         self.task_source_type = self._validate_task_source_type(task_source_type)
+        #: Which element iterations does this apply to?
         self.element_iters = element_iters
+        #: Filtering rules.
         self.where = where
+        #: Path to where this input goes.
         self.path = path
 
         if self.source_type is InputSourceType.TASK:
@@ -1852,6 +2264,9 @@ class InputSource(JSONLike):
         return None
 
     def to_string(self):
+        """
+        Render this input source as a string.
+        """
         out = [self.source_type.name.lower()]
         if self.source_type is InputSourceType.TASK:
             out += [str(self.task_ref), self.task_source_type.name.lower()]
@@ -1893,20 +2308,26 @@ class InputSource(JSONLike):
 
     @classmethod
     def from_string(cls, str_defn):
-        return cls(**cls._parse_from_string(str_defn))
-
-    @classmethod
-    def _parse_from_string(cls, str_defn):
         """Parse a dot-delimited string definition of an InputSource.
 
-        Examples:
-            - task.[task_ref].input
-            - task.[task_ref].output
-            - local
-            - default
-            - import.[import_ref]
+        Parameter
+        ---------
+        str_defn:
+            The string to parse.
+
+        Examples
+        --------
+            task.[task_ref].input
+            task.[task_ref].output
+            local
+            default
+            import.[import_ref]
 
         """
+        return cls(**cls._parse_from_string(str_defn))
+
+    @classmethod
+    def _parse_from_string(cls, str_defn):
         parts = str_defn.split(".")
         source_type = cls._validate_source_type(parts[0])
         task_ref = None
@@ -1957,6 +2378,18 @@ class InputSource(JSONLike):
 
     @classmethod
     def import_(cls, import_ref, element_iters=None, where=None):
+        """
+        Make an instnace of an input source that is an import.
+
+        Parameters
+        ----------
+        import_ref:
+            Import reference.
+        element_iters:
+            Originating element iterations.
+        where:
+            Filtering rule.
+        """
         return cls(
             source_type=cls.app.InputSourceType.IMPORT,
             import_ref=import_ref,
@@ -1966,14 +2399,34 @@ class InputSource(JSONLike):
 
     @classmethod
     def local(cls):
+        """
+        Make an instnace of an input source that is local.
+        """
         return cls(source_type=cls.app.InputSourceType.LOCAL)
 
     @classmethod
     def default(cls):
+        """
+        Make an instnace of an input source that is default.
+        """
         return cls(source_type=cls.app.InputSourceType.DEFAULT)
 
     @classmethod
     def task(cls, task_ref, task_source_type=None, element_iters=None, where=None):
+        """
+        Make an instnace of an input source that is a task.
+
+        Parameters
+        ----------
+        task_ref:
+            Source task reference.
+        task_source_type:
+            Type of task source.
+        element_iters:
+            Originating element iterations.
+        where:
+            Filtering rule.
+        """
         if not task_source_type:
             task_source_type = cls.app.TaskSourceType.OUTPUT
         return cls(