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

hpcflow/sdk/core/actions.py

@@ -1,3 +1,9 @@
+"""
+Actions are base components of elements.
+Element action runs (EARs) are the basic components of any enactment;
+they may be grouped together within a jobscript for efficiency.  
+"""
+
 from __future__ import annotations
 import copy
 from dataclasses import dataclass
@@ -37,13 +43,23 @@ ACTION_SCOPE_REGEX = r"(\w*)(?:\[(.*)\])?"
 
 
 class ActionScopeType(enum.Enum):
+    """
+    Types of action scope.
+    """
+
+    #: Scope that applies to anything.
     ANY = 0
+    #: Scope that only applies to main scripts.
     MAIN = 1
+    #: Scope that applies to processing steps.
     PROCESSING = 2
+    #: Scope that applies to input file generators.
     INPUT_FILE_GENERATOR = 3
+    #: Scope that applies to output file parsers.
     OUTPUT_FILE_PARSER = 4
 
 
+#: Keyword arguments permitted for particular scopes.
 ACTION_SCOPE_ALLOWED_KWARGS = {
     ActionScopeType.ANY.name: set(),
     ActionScopeType.MAIN.name: set(),
@@ -64,30 +80,36 @@ class EARStatus(enum.Enum):
         member.__doc__ = doc
         return member
 
+    #: Not yet associated with a submission.
     pending = (
         0,
         ".",
         "grey46",
         "Not yet associated with a submission.",
     )
+    #: Associated with a prepared submission that is not yet submitted.
     prepared = (
         1,
         ".",
         "grey46",
         "Associated with a prepared submission that is not yet submitted.",
     )
+    #: Submitted for execution.
     submitted = (
         2,
         ".",
         "grey46",
         "Submitted for execution.",
     )
+    #: Executing now.
     running = (
         3,
         "●",
         "dodger_blue1",
         "Executing now.",
     )
+    #: Not attempted due to a failure of an upstream action on which this depends,
+    #: or a loop termination condition being satisfied.
     skipped = (
         4,
         "s",
@@ -97,18 +119,21 @@ class EARStatus(enum.Enum):
             "or a loop termination condition being satisfied."
         ),
     )
+    #: Aborted by the user; downstream actions will be attempted.
     aborted = (
         5,
         "A",
         "deep_pink4",
         "Aborted by the user; downstream actions will be attempted.",
     )
+    #: Probably exited successfully.
     success = (
         6,
         "■",
         "green3",
         "Probably exited successfully.",
     )
+    #: Probably failed.
     error = (
         7,
         "E",
@@ -128,10 +153,57 @@ class EARStatus(enum.Enum):
 
     @property
     def rich_repr(self):
+        """
+        The rich representation of the value.
+        """
         return f"[{self.colour}]{self.symbol}[/{self.colour}]"
 
 
 class ElementActionRun:
+    """
+    The Element Action Run (EAR) is an atomic unit of an enacted workflow, representing
+    one unit of work (e.g., particular submitted job to run a program) within that
+    overall workflow. With looping over, say, parameter spaces, there may be many EARs
+    per element.
+
+    Parameters
+    ----------
+    id_: int
+        The ID of the EAR.
+    is_pending: bool
+        Whether this EAR is pending.
+    element_action:
+        The particular element action that this is a run of.
+    index: int:
+        The index of the run within the collection of runs.
+    data_idx: dict
+        Used for looking up input data to the EAR.
+    commands_idx: list[int]
+        Indices of commands to apply.
+    start_time: datetime
+        Time of start of run, if the run has ever been started.
+    end_time: datetime
+        Time of end of run, if the run has ever ended.
+    snapshot_start: dict
+        Parameters for taking a snapshot of the data directory before the run.
+        If unspecified, no snapshot will be taken.
+    snapshot_end: dict
+        Parameters for taking a snapshot of the data directory after the run.
+        If unspecified, no snapshot will be taken.
+    submission_idx: int
+        What submission was this (if it has been submitted)?
+    success: bool
+        Whether this EAR succeeded (if it has run).
+    skip: bool
+        Whether this EAR was skipped.
+    exit_code: int
+        The exit code, if known.
+    metadata: dict
+        Metadata about the EAR.
+    run_hostname: str
+        Where to run the EAR (if not locally).
+    """
+
     _app_attr = "app"
 
     def __init__(
@@ -189,14 +261,23 @@ class ElementActionRun:
 
     @property
     def id_(self) -> int:
+        """
+        The ID of the EAR.
+        """
         return self._id
 
     @property
     def is_pending(self) -> bool:
+        """
+        Whether this EAR is pending.
+        """
         return self._is_pending
 
     @property
     def element_action(self):
+        """
+        The particular element action that this is a run of.
+        """
         return self._element_action
 
     @property
@@ -206,58 +287,100 @@ class ElementActionRun:
 
     @property
     def action(self):
+        """
+        The action this is a run of.
+        """
         return self.element_action.action
 
     @property
     def element_iteration(self):
+        """
+        The iteration information of this run.
+        """
         return self.element_action.element_iteration
 
     @property
     def element(self):
+        """
+        The element this is a run of.
+        """
         return self.element_iteration.element
 
     @property
     def workflow(self):
+        """
+        The workflow this is a run of.
+        """
         return self.element_iteration.workflow
 
     @property
     def data_idx(self):
+        """
+        Used for looking up input data to the EAR.
+        """
         return self._data_idx
 
     @property
     def commands_idx(self):
+        """
+        Indices of commands to apply.
+        """
         return self._commands_idx
 
     @property
     def metadata(self):
+        """
+        Metadata about the EAR.
+        """
         return self._metadata
 
     @property
     def run_hostname(self):
+        """
+        Where to run the EAR, if known/specified.
+        """
         return self._run_hostname
 
     @property
     def start_time(self):
+        """
+        When the EAR started.
+        """
         return self._start_time
 
     @property
     def end_time(self):
+        """
+        When the EAR finished.
+        """
         return self._end_time
 
     @property
     def submission_idx(self):
+        """
+        What actual submission index was this?
+        """
         return self._submission_idx
 
     @property
     def success(self):
+        """
+        Did the EAR succeed?
+        """
         return self._success
 
     @property
     def skip(self):
+        """
+        Was the EAR skipped?
+        """
         return self._skip
 
     @property
     def snapshot_start(self):
+        """
+        The snapshot of the data directory at the start of the run.
+        """
         if self._ss_start_obj is None and self._snapshot_start:
             self._ss_start_obj = JSONLikeDirSnapShot(
                 root_path=".",
@@ -267,14 +390,18 @@ class ElementActionRun:
 
     @property
     def snapshot_end(self):
+        """
+        The snapshot of the data directory at the end of the run.
+        """
         if self._ss_end_obj is None and self._snapshot_end:
             self._ss_end_obj = JSONLikeDirSnapShot(root_path=".", **self._snapshot_end)
         return self._ss_end_obj
 
     @property
     def dir_diff(self) -> DirectorySnapshotDiff:
-        """Get the changes to the EAR working directory due to the execution of this
-        EAR."""
+        """
+        The changes to the EAR working directory due to the execution of this EAR.
+        """
         if self._ss_diff_obj is None and self.snapshot_end:
             self._ss_diff_obj = DirectorySnapshotDiff(
                 self.snapshot_start, self.snapshot_end
@@ -283,15 +410,23 @@ class ElementActionRun:
 
     @property
     def exit_code(self):
+        """
+        The exit code of the underlying program run by the EAR, if known.
+        """
         return self._exit_code
 
     @property
     def task(self):
+        """
+        The task that this EAR is part of the implementation of.
+        """
         return self.element_action.task
 
     @property
     def status(self):
-        """Return the state of this EAR."""
+        """
+        The state of this EAR.
+        """
 
         if self.skip:
             return EARStatus.skipped
@@ -336,6 +471,14 @@ class ElementActionRun:
         return self.action.get_parameter_names(prefix)
 
     def get_data_idx(self, path: str = None):
+        """
+        Get the data index of a value in the most recent iteration.
+
+        Parameters
+        ----------
+        path:
+            Path to the parameter.
+        """
         return self.element_iteration.get_data_idx(
             path,
             action_idx=self.element_action.action_idx,
@@ -350,6 +493,20 @@ class ElementActionRun:
         as_strings: bool = False,
         use_task_index: bool = False,
     ):
+        """
+        Get the source or sources of a parameter in the most recent iteration.
+
+        Parameters
+        ----------
+        path:
+            Path to the parameter.
+        typ:
+            The parameter type.
+        as_strings:
+            Whether to return the result as human-readable strings.
+        use_task_index:
+            Whether to use the task index.
+        """
         return self.element_iteration.get_parameter_sources(
             path,
             action_idx=self.element_action.action_idx,
@@ -366,6 +523,22 @@ class ElementActionRun:
         raise_on_missing: bool = False,
         raise_on_unset: bool = False,
     ):
+        """
+        Get a value (parameter, input, output, etc.) from the most recent iteration.
+
+        Parameters
+        ----------
+        path:
+            Path to the value.
+        default:
+            Default value to provide if value absent.
+        raise_on_missing:
+            Whether to raise an exception on an absent value.
+            If not, the default is returned.
+        raise_on_unset:
+            Whether to raise an exception on an explicitly unset value.
+            If not, the default is returned.
+        """
         return self.element_iteration.get(
             path=path,
             action_idx=self.element_action.action_idx,
@@ -436,12 +609,18 @@ class ElementActionRun:
 
     @property
     def inputs(self):
+        """
+        The inputs to this EAR.
+        """
         if not self._inputs:
             self._inputs = self.app.ElementInputs(element_action_run=self)
         return self._inputs
 
     @property
     def outputs(self):
+        """
+        The outputs from this EAR.
+        """
         if not self._outputs:
             self._outputs = self.app.ElementOutputs(element_action_run=self)
         return self._outputs
@@ -449,24 +628,36 @@ class ElementActionRun:
     @property
     @TimeIt.decorator
     def resources(self):
+        """
+        The resources to use with (or used by) this EAR.
+        """
         if not self._resources:
             self._resources = self.app.ElementResources(**self.get_resources())
         return self._resources
 
     @property
     def input_files(self):
+        """
+        The input files to the controlled program.
+        """
         if not self._input_files:
             self._input_files = self.app.ElementInputFiles(element_action_run=self)
         return self._input_files
 
     @property
     def output_files(self):
+        """
+        The output files from the controlled program.
+        """
         if not self._output_files:
             self._output_files = self.app.ElementOutputFiles(element_action_run=self)
         return self._output_files
 
     @property
     def env_spec(self) -> Dict[str, Any]:
+        """
+        Environment details.
+        """
         return self.resources.environments[self.action.get_environment_name()]
 
     @TimeIt.decorator
@@ -476,9 +667,15 @@ class ElementActionRun:
         return self.element_iteration.get_resources(self.action)
 
     def get_environment_spec(self) -> str:
+        """
+        What environment to run in?
+        """
         return self.action.get_environment_spec()
 
     def get_environment(self) -> app.Environment:
+        """
+        What environment to run in?
+        """
         return self.action.get_environment()
 
     def get_all_previous_iteration_runs(self, include_self: bool = True):
@@ -502,13 +699,13 @@ class ElementActionRun:
 
         Parameters
         ----------
-        inputs
+        inputs:
             If specified, a list of input parameter types to include, or a dict whose keys
             are input parameter types to include. For schema inputs that have
             `multiple=True`, the input type should be labelled. If a dict is passed, and
             the key "all_iterations` is present and `True`, the return for that input
             will be structured to include values for all previous iterations.
-        label_dict
+        label_dict:
             If True, arrange the values of schema inputs with multiple=True as a dict
             whose keys are the labels. If False, labels will be included in the top level
             keys.
@@ -565,6 +762,9 @@ class ElementActionRun:
         return self.get_input_values(inputs=inputs, label_dict=label_dict)
 
     def get_IFG_input_values(self) -> Dict[str, Any]:
+        """
+        Get a dict of input values that are to be passed via an input file generator.
+        """
         if not self.action._from_expand:
             raise RuntimeError(
                 f"Cannot get input file generator inputs from this EAR because the "
@@ -583,6 +783,10 @@ class ElementActionRun:
         return inputs
 
     def get_OFP_output_files(self) -> Dict[str, Union[str, List[str]]]:
+        """
+        Get a dict of output files that are going to be parsed to generate one or more
+        outputs.
+        """
         # TODO: can this return multiple files for a given FileSpec?
         if not self.action._from_expand:
             raise RuntimeError(
@@ -595,6 +799,9 @@ class ElementActionRun:
         return out_files
 
     def get_OFP_inputs(self) -> Dict[str, Union[str, List[str]]]:
+        """
+        Get a dict of input values that are to be passed to output file parsers.
+        """
         if not self.action._from_expand:
             raise RuntimeError(
                 f"Cannot get output file parser inputs from this from EAR because the "
@@ -610,6 +817,9 @@ class ElementActionRun:
         return inputs
 
     def get_OFP_outputs(self) -> Dict[str, Union[str, List[str]]]:
+        """
+        Get the outputs obtained by parsing an output file.
+        """
         if not self.action._from_expand:
             raise RuntimeError(
                 f"Cannot get output file parser outputs from this from EAR because the "
@@ -621,6 +831,9 @@ class ElementActionRun:
         return outputs
 
     def write_source(self, js_idx: int, js_act_idx: int):
+        """
+        Write values to files in standard formats.
+        """
         import h5py
 
         for fmt, ins in self.action.script_data_in_grouped.items():
@@ -690,10 +903,13 @@ class ElementActionRun:
         self, jobscript: app.Jobscript, JS_action_idx: int
     ) -> Tuple[str, List[str], List[int]]:
         """
+        Write the EAR's enactment to disk in preparation for submission.
+
         Returns
         -------
-        commands
-        shell_vars
+        commands:
+            List of argument words for the command that enacts the EAR.
+        shell_vars:
             Dict whose keys are command indices, and whose values are lists of tuples,
             where each tuple contains: (parameter name, shell variable name,
             "stdout"/"stderr").
@@ -735,6 +951,20 @@ class ElementActionRun:
 
 
 class ElementAction:
+    """
+    An abstract representation of an element's action at a particular iteration and
+    the runs that enact that element iteration.
+
+    Parameters
+    ----------
+    element_iteration:
+        The iteration
+    action_idx:
+        The action index.
+    runs:
+        The list of run indices.
+    """
+
     _app_attr = "app"
 
     def __init__(self, element_iteration, action_idx, runs):
@@ -761,18 +991,30 @@ class ElementAction:
 
     @property
     def element_iteration(self):
+        """
+        The iteration for this action.
+        """
         return self._element_iteration
 
     @property
     def element(self):
+        """
+        The element for this action.
+        """
         return self.element_iteration.element
 
     @property
     def num_runs(self):
+        """
+        The number of runs associated with this action.
+        """
         return len(self._runs)
 
     @property
     def runs(self):
+        """
+        The EARs that this action is enacted by.
+        """
         if self._run_objs is None:
             self._run_objs = [
                 self.app.ElementActionRun(
@@ -790,41 +1032,65 @@ class ElementAction:
 
     @property
     def task(self):
+        """
+        The task that this action is an instance of.
+        """
         return self.element_iteration.task
 
     @property
     def action_idx(self):
+        """
+        The index of the action.
+        """
         return self._action_idx
 
     @property
     def action(self):
+        """
+        The abstract task that this is a concrete model of.
+        """
         return self.task.template.get_schema_action(self.action_idx)
 
     @property
     def inputs(self):
+        """
+        The inputs to this action.
+        """
         if not self._inputs:
             self._inputs = self.app.ElementInputs(element_action=self)
         return self._inputs
 
     @property
     def outputs(self):
+        """
+        The outputs from this action.
+        """
         if not self._outputs:
             self._outputs = self.app.ElementOutputs(element_action=self)
         return self._outputs
 
     @property
     def input_files(self):
+        """
+        The input files to this action.
+        """
         if not self._input_files:
             self._input_files = self.app.ElementInputFiles(element_action=self)
         return self._input_files
 
     @property
     def output_files(self):
+        """
+        The output files from this action.
+        """
         if not self._output_files:
             self._output_files = self.app.ElementOutputFiles(element_action=self)
         return self._output_files
 
     def get_data_idx(self, path: str = None, run_idx: int = -1):
+        """
+        Get the data index for some path/run.
+        """
         return self.element_iteration.get_data_idx(
             path,
             action_idx=self.action_idx,
@@ -839,6 +1105,9 @@ class ElementAction:
         as_strings: bool = False,
         use_task_index: bool = False,
     ):
+        """
+        Get information about where parameters originated.
+        """
         return self.element_iteration.get_parameter_sources(
             path,
             action_idx=self.action_idx,
@@ -856,6 +1125,9 @@ class ElementAction:
         raise_on_missing: bool = False,
         raise_on_unset: bool = False,
     ):
+        """
+        Get the value of a parameter.
+        """
         return self.element_iteration.get(
             path=path,
             action_idx=self.action_idx,
@@ -868,8 +1140,8 @@ class ElementAction:
     def get_parameter_names(self, prefix: str) -> List[str]:
         """Get parameter types associated with a given prefix.
 
-        For inputs, labels are ignored. See `Action.get_parameter_names` for more
-        information.
+        For inputs, labels are ignored.
+        See :py:meth:`.Action.get_parameter_names` for more information.
 
         Parameters
         ----------
@@ -898,7 +1170,9 @@ class ActionScope(JSONLike):
         if isinstance(typ, str):
             typ = getattr(self.app.ActionScopeType, typ.upper())
 
+        #: Action scope type.
         self.typ = typ
+        #: Any provided extra keyword arguments.
         self.kwargs = {k: v for k, v in kwargs.items() if v is not None}
 
         bad_keys = set(kwargs.keys()) - ACTION_SCOPE_ALLOWED_KWARGS[self.typ.name]
@@ -932,6 +1206,9 @@ class ActionScope(JSONLike):
         return {"type": typ_str, **kwargs}
 
     def to_string(self):
+        """
+        Render this action scope as a string.
+        """
         kwargs_str = ""
         if self.kwargs:
             kwargs_str = "[" + ", ".join(f"{k}={v}" for k, v in self.kwargs.items()) + "]"
@@ -948,27 +1225,46 @@ class ActionScope(JSONLike):
 
     @classmethod
     def any(cls):
+        """
+        Any scope.
+        """
         return cls(typ=ActionScopeType.ANY)
 
     @classmethod
     def main(cls):
+        """
+        The main scope.
+        """
         return cls(typ=ActionScopeType.MAIN)
 
     @classmethod
     def processing(cls):
+        """
+        The processing scope.
+        """
         return cls(typ=ActionScopeType.PROCESSING)
 
     @classmethod
     def input_file_generator(cls, file=None):
+        """
+        The scope of an input file generator.
+        """
         return cls(typ=ActionScopeType.INPUT_FILE_GENERATOR, file=file)
 
     @classmethod
     def output_file_parser(cls, output=None):
+        """
+        The scope of an output file parser.
+        """
         return cls(typ=ActionScopeType.OUTPUT_FILE_PARSER, output=output)
 
 
 @dataclass
 class ActionEnvironment(JSONLike):
+    """
+    The environment that an action is enacted within.
+    """
+
     _app_attr = "app"
 
     _child_objects = (
@@ -978,7 +1274,9 @@ class ActionEnvironment(JSONLike):
         ),
     )
 
+    #: The environment document.
     environment: Union[str, Dict[str, Any]]
+    #: The scope.
     scope: Optional[app.ActionScope] = None
 
     def __post_init__(self):
@@ -998,8 +1296,27 @@ class ActionEnvironment(JSONLike):
 
 
 class ActionRule(JSONLike):
-    """Class to represent a rule/condition that must be True if an action is to be
-    included."""
+    """
+    Class to represent a rule/condition that must be True if an action is to be
+    included.
+
+    Parameters
+    ----------
+    rule: ~hpcflow.app.Rule
+        The rule to apply.
+    check_exists: str
+        A special rule that is enabled if this named attribute is present.
+    check_missing: str
+        A special rule that is enabled if this named attribute is absent.
+    path: str
+        Where to find the attribute to check.
+    condition: dict | ConditionLike
+        A more complex condition to apply.
+    cast: str
+        The name of a class to cast the attribute to before checking.
+    doc: str
+        Documentation for this rule, if any.
+    """
 
     _child_objects = (ChildObjectSpec(name="rule", class_name="Rule"),)
 
@@ -1031,8 +1348,11 @@ class ActionRule(JSONLike):
                 f"constructor arguments."
             )
 
+        #: The rule to apply.
         self.rule = rule
+        #: The action that contains this rule.
         self.action = None  # assigned by parent action
+        #: The command that is guarded by this rule.
         self.command = None  # assigned by parent command
 
     def __eq__(self, other):
@@ -1044,19 +1364,85 @@ class ActionRule(JSONLike):
 
     @TimeIt.decorator
     def test(self, element_iteration: app.ElementIteration) -> bool:
+        """
+        Test if this rule holds for a particular iteration.
+
+        Parameter
+        ---------
+        element_iteration:
+            The iteration to apply this rule to.
+        """
         return self.rule.test(element_like=element_iteration, action=self.action)
 
     @classmethod
     def check_exists(cls, check_exists):
+        """
+        Make an action rule that checks if a named attribute is present.
+
+        Parameter
+        ---------
+        check_exists: str
+            The path to the attribute to check for.
+        """
         return cls(rule=app.Rule(check_exists=check_exists))
 
     @classmethod
     def check_missing(cls, check_missing):
+        """
+        Make an action rule that checks if a named attribute is absent.
+
+        Parameter
+        ---------
+        check_missing: str
+            The path to the attribute to check for.
+        """
         return cls(rule=app.Rule(check_missing=check_missing))
 
 
 class Action(JSONLike):
-    """"""
+    """
+    An atomic component of a workflow that will be enacted within an iteration
+    structure.
+
+    Parameters
+    ----------
+    environments: list[ActionEnvironment]
+        The environments in which this action can run.
+    commands: list[~hpcflow.app.Command]
+        The commands to be run by this action.
+    script: str
+        The name of the Python script to run.
+    script_data_in: str
+        Information about data input to the script.
+    script_data_out: str
+        Information about data output from the script.
+    script_data_files_use_opt: bool
+        If True, script data input and output file paths will be passed to the script
+        execution command line with an option like ``--input-json`` or ``--output-hdf5``
+        etc. If False, the file paths will be passed on their own. For Python scripts,
+        options are always passed, and this parameter is overwritten to be True,
+        regardless of its initial value.
+    script_exe: str
+        The executable to use to run the script.
+    script_pass_env_spec: bool
+        Whether to pass the environment details to the script.
+    abortable: bool
+        Whether this action can be aborted.
+    input_file_generators: list[~hpcflow.app.InputFileGenerator]
+        Any applicable input file generators.
+    output_file_parsers: list[~hpcflow.app.OutputFileParser]
+        Any applicable output file parsers.
+    input_files: list[~hpcflow.app.FileSpec]
+        The input files to the action's commands.
+    output_files: list[~hpcflow.app.FileSpec]
+        The output files from the action's commands.
+    rules: list[ActionRule]
+        How to determine whether to run the action.
+    save_files: list[str]
+        The names of files to be explicitly saved after each step.
+    clean_up: list[str]
+        The names of files to be deleted after each step.
+    """
 
     _app_attr = "app"
     _child_objects = (
@@ -1136,36 +1522,45 @@ class Action(JSONLike):
         save_files: Optional[List[str]] = None,
         clean_up: Optional[List[str]] = None,
     ):
-        """
-        Parameters
-        ----------
-        script_data_files_use_opt
-            If True, script data input and output file paths will be passed to the script
-            execution command line with an option like `--input-json` or `--output-hdf5`
-            etc. If False, the file paths will be passed on their own. For Python scripts,
-            options are always passed, and this parameter is overwritten to be True,
-            regardless of its initial value.
-
-        """
+        #: The commands to be run by this action.
         self.commands = commands or []
+        #: The name of the Python script to run.
         self.script = script
+        #: Information about data input to the script.
         self.script_data_in = script_data_in
+        #: Information about data output from the script.
         self.script_data_out = script_data_out
+        #: If True, script data input and output file paths will be passed to the script
+        #: execution command line with an option like `--input-json` or `--output-hdf5`
+        #: etc. If False, the file paths will be passed on their own. For Python scripts,
+        #: options are always passed, and this parameter is overwritten to be True,
+        #: regardless of its initial value.
         self.script_data_files_use_opt = (
             script_data_files_use_opt if not self.script_is_python else True
         )
+        #: The executable to use to run the script.
         self.script_exe = script_exe.lower() if script_exe else None
+        #: Whether to pass the environment details to the script.
         self.script_pass_env_spec = script_pass_env_spec
+        #: The environments in which this action can run.
         self.environments = environments or [
             self.app.ActionEnvironment(environment="null_env")
         ]
+        #: Whether this action can be aborted.
         self.abortable = abortable
+        #: Any applicable input file generators.
         self.input_file_generators = input_file_generators or []
+        #: Any applicable output file parsers.
         self.output_file_parsers = output_file_parsers or []
+        #: The input files to the action's commands.
         self.input_files = self._resolve_input_files(input_files or [])
+        #: The output files from the action's commands.
         self.output_files = self._resolve_output_files(output_files or [])
+        #: How to determine whether to run the action.
         self.rules = rules or []
+        #: The names of files to be explicitly saved after each step.
         self.save_files = save_files or []
+        #: The names of files to be deleted after each step.
         self.clean_up = clean_up or []
 
         self._task_schema = None  # assigned by parent TaskSchema
@@ -1174,6 +1569,9 @@ class Action(JSONLike):
         self._set_parent_refs()
 
     def process_script_data_formats(self):
+        """
+        Convert script data information into standard form.
+        """
         self.script_data_in = self._process_script_data_in(self.script_data_in)
         self.script_data_out = self._process_script_data_out(self.script_data_out)
 
@@ -1317,6 +1715,9 @@ class Action(JSONLike):
 
     @property
     def task_schema(self):
+        """
+        The task schema that this action came from.
+        """
         return self._task_schema
 
     def _resolve_input_files(self, input_files):
@@ -1397,7 +1798,7 @@ class Action(JSONLike):
         out = {"input_file_writers": writer_files, "commands": commands}
         return out
 
-    def get_resolved_action_env(
+    def _get_resolved_action_env(
         self,
         relevant_scopes: Tuple[app.ActionScopeType],
         input_file_generator: app.InputFileGenerator = None,
@@ -1427,7 +1828,10 @@ class Action(JSONLike):
     def get_input_file_generator_action_env(
         self, input_file_generator: app.InputFileGenerator
     ):
-        return self.get_resolved_action_env(
+        """
+        Get the actual environment to use for an input file generator.
+        """
+        return self._get_resolved_action_env(
             relevant_scopes=(
                 ActionScopeType.ANY,
                 ActionScopeType.PROCESSING,
@@ -1437,7 +1841,10 @@ class Action(JSONLike):
         )
 
     def get_output_file_parser_action_env(self, output_file_parser: app.OutputFileParser):
-        return self.get_resolved_action_env(
+        """
+        Get the actual environment to use for an output file parser.
+        """
+        return self._get_resolved_action_env(
             relevant_scopes=(
                 ActionScopeType.ANY,
                 ActionScopeType.PROCESSING,
@@ -1447,15 +1854,24 @@ class Action(JSONLike):
         )
 
     def get_commands_action_env(self):
-        return self.get_resolved_action_env(
+        """
+        Get the actual environment to use for the action commands.
+        """
+        return self._get_resolved_action_env(
             relevant_scopes=(ActionScopeType.ANY, ActionScopeType.MAIN),
             commands=self.commands,
         )
 
     def get_environment_name(self) -> str:
+        """
+        Get the name of the primary environment.
+        """
         return self.get_environment_spec()["name"]
 
     def get_environment_spec(self) -> Dict[str, Any]:
+        """
+        Get the specification for the primary envionment, assuming it has been expanded.
+        """
         if not self._from_expand:
             raise RuntimeError(
                 f"Cannot choose a single environment from this action because it is not "
@@ -1464,6 +1880,9 @@ class Action(JSONLike):
         return self.environments[0].environment
 
     def get_environment(self) -> app.Environment:
+        """
+        Get the primary environment.
+        """
         return self.app.envs.get(**self.get_environment_spec())
 
     @staticmethod
@@ -1487,6 +1906,9 @@ class Action(JSONLike):
     def get_snippet_script_str(
         cls, script, env_spec: Optional[Dict[str, Any]] = None
     ) -> str:
+        """
+        Get the substituted script snippet path as a string.
+        """
         if not cls.is_snippet_script(script):
             raise ValueError(
                 f"Must be an app-data script name (e.g. "
@@ -1508,6 +1930,9 @@ class Action(JSONLike):
     def get_snippet_script_path(
         cls, script_path, env_spec: Optional[Dict[str, Any]] = None
     ) -> Path:
+        """
+        Get the substituted script snippet path, or False if there is no snippet.
+        """
         if not cls.is_snippet_script(script_path):
             return False
 
@@ -1518,26 +1943,42 @@ class Action(JSONLike):
         return Path(path)
 
     @staticmethod
-    def get_param_dump_file_stem(js_idx: int, js_act_idx: int):
+    def __get_param_dump_file_stem(js_idx: int, js_act_idx: int):
         return RunDirAppFiles.get_run_param_dump_file_prefix(js_idx, js_act_idx)
 
     @staticmethod
-    def get_param_load_file_stem(js_idx: int, js_act_idx: int):
+    def __get_param_load_file_stem(js_idx: int, js_act_idx: int):
         return RunDirAppFiles.get_run_param_load_file_prefix(js_idx, js_act_idx)
 
     def get_param_dump_file_path_JSON(self, js_idx: int, js_act_idx: int):
-        return Path(self.get_param_dump_file_stem(js_idx, js_act_idx) + ".json")
+        """
+        Get the path of the JSON dump file.
+        """
+        return Path(self.__get_param_dump_file_stem(js_idx, js_act_idx) + ".json")
 
     def get_param_dump_file_path_HDF5(self, js_idx: int, js_act_idx: int):
-        return Path(self.get_param_dump_file_stem(js_idx, js_act_idx) + ".h5")
+        """
+        Get the path of the HDF56 dump file.
+        """
+        return Path(self.__get_param_dump_file_stem(js_idx, js_act_idx) + ".h5")
 
     def get_param_load_file_path_JSON(self, js_idx: int, js_act_idx: int):
-        return Path(self.get_param_load_file_stem(js_idx, js_act_idx) + ".json")
+        """
+        Get the path of the JSON load file.
+        """
+        return Path(self.__get_param_load_file_stem(js_idx, js_act_idx) + ".json")
 
     def get_param_load_file_path_HDF5(self, js_idx: int, js_act_idx: int):
-        return Path(self.get_param_load_file_stem(js_idx, js_act_idx) + ".h5")
+        """
+        Get the path of the HDF5 load file.
+        """
+        return Path(self.__get_param_load_file_stem(js_idx, js_act_idx) + ".h5")
 
     def expand(self):
+        """
+        Expand this action into a list of actions if necessary.
+        This converts input file generators and output file parsers into their own actions.
+        """
         if self._from_expand:
             # already expanded
             return [self]
@@ -1694,7 +2135,7 @@ class Action(JSONLike):
 
         Parameters
         ----------
-        sub_parameters
+        sub_parameters:
             If True, sub-parameters (i.e. dot-delimited parameter types) will be returned
             untouched. If False (default), only return the root parameter type and
             disregard the sub-parameter part.
@@ -1747,7 +2188,7 @@ class Action(JSONLike):
 
         Parameters
         ----------
-        sub_parameters
+        sub_parameters:
             If True, sub-parameters (i.e. dot-delimited parameter types) in command line
             inputs will be returned untouched. If False (default), only return the root
             parameter type and disregard the sub-parameter part.
@@ -1786,9 +2227,15 @@ class Action(JSONLike):
         return tuple(set(params))
 
     def get_input_file_labels(self):
+        """
+        Get the labels from the input files.
+        """
         return tuple(i.label for i in self.input_files)
 
     def get_output_file_labels(self):
+        """
+        Get the labels from the output files.
+        """
         return tuple(i.label for i in self.output_files)
 
     @TimeIt.decorator
@@ -1919,6 +2366,10 @@ class Action(JSONLike):
         return scopes
 
     def get_precise_scope(self) -> app.ActionScope:
+        """
+        Get the exact scope of this action.
+        The action must have been expanded prior to calling this.
+        """
         if not self._from_expand:
             raise RuntimeError(
                 "Precise scope cannot be unambiguously defined until the Action has been "
@@ -1942,6 +2393,9 @@ class Action(JSONLike):
     def is_input_type_required(
         self, typ: str, provided_files: List[app.FileSpec]
     ) -> bool:
+        """
+        Determine if the given input type is required by this action.
+        """
         # TODO: for now assume a script takes all inputs
         if (
             self.script
@@ -1966,6 +2420,9 @@ class Action(JSONLike):
             if typ in (OFP.inputs or []):
                 return True
 
+        # Appears to be not required
+        return False
+
     @TimeIt.decorator
     def test_rules(self, element_iter) -> Tuple[bool, List[int]]:
         """Test all rules against the specified element iteration."""