sapiopycommons 2024.3.19a157__py3-none-any.whl → 2025.1.17a402__py3-none-any.whl

sapiopycommons/eln/experiment_handler.py

@@ -1,7 +1,13 @@
+from __future__ import annotations
+
 import time
 from collections.abc import Mapping, Iterable
+from typing import TypeAlias
+from weakref import WeakValueDictionary
 
+from sapiopylib.rest.DataMgmtService import DataMgmtServer
 from sapiopylib.rest.ELNService import ElnManager
+from sapiopylib.rest.User import SapioUser
 from sapiopylib.rest.pojo.DataRecord import DataRecord
 from sapiopylib.rest.pojo.eln.ElnExperiment import ElnExperiment, TemplateExperimentQueryPojo, ElnTemplate, \
     InitializeNotebookExperimentPojo, ElnExperimentUpdateCriteria
@@ -16,18 +22,22 @@ from sapiopylib.rest.utils.Protocols import ElnEntryStep, ElnExperimentProtocol
 from sapiopylib.rest.utils.recordmodel.PyRecordModel import PyRecordModel
 from sapiopylib.rest.utils.recordmodel.RecordModelManager import RecordModelInstanceManager, RecordModelManager
 from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedType
+from sapiopylib.rest.utils.recordmodel.properties import Child
 
-from sapiopycommons.general.aliases import AliasUtil, SapioRecord
+from sapiopycommons.eln.experiment_report_util import ExperimentReportUtil
+from sapiopycommons.general.aliases import AliasUtil, SapioRecord, ExperimentIdentifier, UserIdentifier, \
+    DataTypeIdentifier, RecordModel
 from sapiopycommons.general.exceptions import SapioException
 
-Step = str | ElnEntryStep
+Step: TypeAlias = str | ElnEntryStep
 """An object representing an identifier to an ElnEntryStep. May be either the name of the step or the ElnEntryStep
 itself."""
 
 
 # FR-46064 - Initial port of PyWebhookUtils to sapiopycommons.
 class ExperimentHandler:
-    __context: SapioWebhookContext
+    user: SapioUser
+    context: SapioWebhookContext | None
     """The context that this handler is working from."""
 
     # Basic experiment info from the context.
@@ -48,9 +58,9 @@ class ExperimentHandler:
     # additional queries to obtain, but may also be repeatedly accessed. In such cases, cache the information after it
     # has been requested so that the user doesn't need to worry about caching it themselves.
     # CR-46341: Replace class variables with instance variables.
-    __exp_record: DataRecord
+    __exp_record: DataRecord | None
     """The data record for this experiment. Only cached when first accessed."""
-    __exp_template: ElnTemplate
+    __exp_template: ElnTemplate | None
     """The template for this experiment. Only cached when first accessed."""
     __exp_options: dict[str, str]
     """Experiment options for this experiment. Only cached when first accessed."""
@@ -59,60 +69,122 @@ class ExperimentHandler:
     """Whether this ExperimentHandler has queried the system for all steps in the experiment."""
     __steps: dict[str, ElnEntryStep]
     """Steps from this experiment. All steps are cached the first time any individual step is accessed."""
-    __step_options: dict[ElnEntryStep, dict[str, str]]
-    """Entry options for each step in this experiment. Only cached for each individual step when they are first accessed.
-    The cache is updated whenever the entry options for a step are changed by this handler."""
+    __step_options: dict[int, dict[str, str]]
+    """Entry options for each step in this experiment. All entry options are cached the first time any individual step's
+    options are queried. The cache is updated whenever the entry options for a step are changed by this handler."""
 
     # Constants
-    # TODO: sapiopylib is currently storing the status of entries as strings when first queried, requiring us to compare
-    #  against the value of the enums instead of the enums themselves. The ".value"s can be removed once sapiopylib is
-    #  fixed.
-    __COMPLETE_STATUSES = [ExperimentEntryStatus.Completed.value, ExperimentEntryStatus.CompletedApproved.value]
+    __ENTRY_COMPLETE_STATUSES = [ExperimentEntryStatus.Completed, ExperimentEntryStatus.CompletedApproved]
     """The set of statuses that an ELN entry could have and be considered completed/submitted."""
-    __LOCKED_STATUSES = [ExperimentEntryStatus.Completed.value, ExperimentEntryStatus.CompletedApproved.value,
-                         ExperimentEntryStatus.Disabled.value, ExperimentEntryStatus.LockedAwaitingApproval.value,
-                         ExperimentEntryStatus.LockedRejected.value]
+    __ENTRY_LOCKED_STATUSES = [ExperimentEntryStatus.Completed, ExperimentEntryStatus.CompletedApproved,
+                               ExperimentEntryStatus.Disabled, ExperimentEntryStatus.LockedAwaitingApproval,
+                               ExperimentEntryStatus.LockedRejected]
     """The set of statuses that an ELN entry could have and be considered locked."""
+    __EXPERIMENT_COMPLETE_STATUSES = [ElnExperimentStatus.Completed, ElnExperimentStatus.CompletedApproved]
+    """The set of statuses that an ELN experiment could have and be considered completed."""
+    __EXPERIMENT_LOCKED_STATUSES = [ElnExperimentStatus.Completed, ElnExperimentStatus.CompletedApproved,
+                                    ElnExperimentStatus.LockedRejected, ElnExperimentStatus.LockedAwaitingApproval,
+                                    ElnExperimentStatus.Canceled]
+    """The set of statuses that an ELN experiment could have and be considered locked."""
+
+    __instances: WeakValueDictionary[str, ExperimentHandler] = WeakValueDictionary()
+    __initialized: bool
 
-    def __init__(self, context: SapioWebhookContext, experiment: ElnExperiment | None = None):
+    def __new__(cls, context: UserIdentifier, experiment: ExperimentIdentifier | SapioRecord | None = None):
+        """
+        :param context: The current webhook context or a user object to send requests from.
+        :param experiment: If an experiment is provided that is separate from the experiment that is in the context,
+            that experiment will be used by this ExperimentHandler instead. An experiment can be provided in various
+            forms, including an ElnExperiment, ElnExperimentProtocol, an experiment record, or a notebook experiment ID.
+        """
+        param_results = cls.__parse_params(context, experiment)
+        user = param_results[0]
+        experiment = param_results[2]
+        key = f"{user.__hash__()}:{experiment.notebook_experiment_id}"
+        obj = cls.__instances.get(key)
+        if not obj:
+            obj = object.__new__(cls)
+            obj.__initialized = False
+            cls.__instances[key] = obj
+        return obj
+
+    def __init__(self, context: UserIdentifier, experiment: ExperimentIdentifier | SapioRecord | None = None):
         """
         Initialization will throw an exception if there is no ELN Experiment in the provided context and no experiment
         is provided.
 
-        :param context: The current webhook context.
+        :param context: The current webhook context or a user object to send requests from.
         :param experiment: If an experiment is provided that is separate from the experiment that is in the context,
-            that experiment will be used by this ExperimentHandler instead.
+            that experiment will be used by this ExperimentHandler instead. An experiment can be provided in various
+            forms, including an ElnExperiment, ElnExperimentProtocol, an experiment record, or a notebook experiment ID.
         """
-        # FR-46495 - Allow the init function of ExperimentHandler to take in an ElnExperiment that is separate from the
-        # context.
-        if context.eln_experiment is None and experiment is None:
-            raise SapioException("Cannot initialize ExperimentHandler. No ELN Experiment in the context.")
-        if context.eln_experiment == experiment:
-            experiment = None
-        self.__context = context
+        param_results = self.__parse_params(context, experiment)
+        self.user = param_results[0]
+        self.context = param_results[1]
+        experiment = param_results[2]
 
         # Get the basic information about this experiment that already exists in the context and is often used.
-        self.__eln_exp = experiment if experiment else context.eln_experiment
-        self.__protocol = ElnExperimentProtocol(experiment, context.user) if experiment else context.active_protocol
+        self.__eln_exp = experiment
+        self.__protocol = ElnExperimentProtocol(experiment, self.user)
         self.__exp_id = self.__protocol.get_id()
 
         # Grab various managers that may be used.
-        self.__eln_man = context.eln_manager
-        self.__inst_man = RecordModelManager(context.user).instance_manager
+        self.__eln_man = DataMgmtServer.get_eln_manager(self.user)
+        self.__inst_man = RecordModelManager(self.user).instance_manager
 
         # Create empty caches to fill when necessary.
         self.__steps = {}
         self.__step_options = {}
         # CR-46330: Cache any experiment entry information that might already exist in the context.
         self.__queried_all_steps = False
-        # We can only trust the entries in the context if no experiment was given as an input parameter.
-        if experiment is None:
-            if context.experiment_entry is not None:
-                self.__steps.update({context.active_step.get_name(): context.active_step})
-            if context.experiment_entry_list is not None:
-                for entry in context.experiment_entry_list:
+        # We can only trust the entries in the context if the experiment that this handler is for is the same as the
+        # one from the context.
+        if self.context is not None and self.context.eln_experiment == experiment:
+            if self.context.experiment_entry is not None:
+                self.__steps.update({self.context.active_step.get_name(): self.context.active_step})
+            if self.context.experiment_entry_list is not None:
+                for entry in self.context.experiment_entry_list:
                     self.__steps.update({entry.entry_name: ElnEntryStep(self.__protocol, entry)})
 
+    @staticmethod
+    def __parse_params(context: UserIdentifier, experiment: ExperimentIdentifier | SapioRecord | None = None) \
+            -> tuple[SapioUser, SapioWebhookContext | None, ElnExperiment]:
+        if isinstance(context, SapioWebhookContext):
+            user = context.user
+            context = context
+        else:
+            user = context
+            context = None
+        if context is not None and context.eln_experiment is not None and experiment is None:
+            experiment = context.eln_experiment
+        # FR-46495 - Allow the init function of ExperimentHandler to take in an ElnExperiment that is separate from the
+        # context.
+        # CR-37038 - Allow other experiment object types to be provided. Convert them all down to ElnExperiment.
+        if (context is None or context.eln_experiment is None) and experiment is not None:
+            eln_manager = DataMgmtServer.get_eln_manager(user)
+            # If this object is already an ElnExperiment, do nothing.
+            if isinstance(experiment, ElnExperiment):
+                pass
+            # If this object is an ElnExperimentProtocol, then we can get the ElnExperiment from the object.
+            elif isinstance(experiment, ElnExperimentProtocol):
+                experiment: ElnExperiment = experiment.eln_experiment
+            # If this object is an integer, assume it is a notebook ID that we can query the system with.
+            elif isinstance(experiment, int):
+                notebook_id: int = experiment
+                experiment: ElnExperiment = eln_manager.get_eln_experiment_by_id(notebook_id)
+                if not experiment:
+                    raise SapioException(f"No experiment with notebook ID {notebook_id} located in the system.")
+            # If this object is a record, assume it is an experiment record that we can query the system with.
+            else:
+                record_id: int = AliasUtil.to_record_ids([experiment])[0]
+                experiment: ElnExperiment = eln_manager.get_eln_experiment_by_record_id(record_id)
+                if not experiment:
+                    raise SapioException(f"No experiment with record ID {record_id} located in the system.")
+        if experiment is None:
+            raise SapioException("Cannot initialize ExperimentHandler. No ELN Experiment found in the provided parameters.")
+
+        return user, context, experiment
+
     # FR-46495: Split the creation of the experiment in launch_experiment into a create_experiment function.
     @staticmethod
     def create_experiment(context: SapioWebhookContext,
@@ -206,6 +278,7 @@ class ExperimentHandler:
         """
         template_id: int | None = self.__eln_exp.template_id
         if template_id is None:
+            self.__exp_template = None
             if exception_on_none:
                 raise SapioException(f"Experiment with ID {self.__exp_id} has no template ID.")
             return None
@@ -260,11 +333,7 @@ class ExperimentHandler:
         :return: The data record for this experiment. None if it has no record.
         """
         if not hasattr(self, "_ExperimentHandler__exp_record"):
-            drm = self.__context.data_record_manager
-            dt = self.__eln_exp.experiment_data_type_name
-            results = drm.query_data_records_by_id(dt, [self.__eln_exp.experiment_record_id]).result_list
-            # PR-46504: Set the exp_record to None if there are no results.
-            self.__exp_record = results[0] if results else None
+            self.__exp_record = self.__protocol.get_record()
         if self.__exp_record is None and exception_on_none:
             raise SapioException(f"Experiment record not found for experiment with ID {self.__exp_id}.")
         return self.__exp_record
@@ -350,6 +419,53 @@ class ExperimentHandler:
         options.update(mapping)
         self.update_experiment(experiment_option_map=options)
 
+    def experiment_is_complete(self) -> bool:
+        """
+        Determine if the experiment has been completed.
+
+        :return: True if the experiment's status is Completed or CompletedApproved. False otherwise.
+        """
+        return self.__eln_exp.notebook_experiment_status in self.__EXPERIMENT_COMPLETE_STATUSES
+
+    def experiment_is_canceled(self) -> bool:
+        """
+        Determine if the experiment has been canceled.
+
+        :return: True if the experiment's status is Canceled. False otherwise.
+        """
+        return self.__eln_exp.notebook_experiment_status == ElnExperimentStatus.Canceled
+
+    def experiment_is_locked(self) -> bool:
+        """
+        Determine if the experiment has been locked in any way.
+
+        :return: True if the experiment's status is Completed, CompletedApproved, Canceled, LockedAwaitingApproval,
+            or LockedRejected. False otherwise.
+        """
+        return self.__eln_exp.notebook_experiment_status in self.__EXPERIMENT_LOCKED_STATUSES
+
+    def complete_experiment(self) -> None:
+        """
+        Set the experiment's status to Completed. Makes a webservice call to update the experiment. Checks if the
+        experiment is already completed, and does nothing if so.
+        """
+        if not self.experiment_is_complete():
+            self.__protocol.complete_protocol()
+            self.__eln_exp.notebook_experiment_status = ElnExperimentStatus.Completed
+
+    def cancel_experiment(self) -> None:
+        """
+        Set the experiment's status to Canceled. Makes a webservice call to update the experiment. Checks if the
+        experiment is already canceled, and does nothing if so.
+
+        NOTE: This will not run the usual logic around canceling an experiment that you'd see if canceling the
+        experiment using the "Cancel Experiment" toolbar button, such as moving in process samples back to the queue,
+        as those changes are tied to the button instead of being on the experiment status change.
+        """
+        if not self.experiment_is_canceled():
+            self.__protocol.cancel_protocol()
+            self.__eln_exp.notebook_experiment_status = ElnExperimentStatus.Canceled
+
     def step_exists(self, step_name: str) -> bool:
         """
         Determine if a step by the given name exists in the experiment.
@@ -417,6 +533,58 @@ class ExperimentHandler:
             ret_list.append(step)
         return ret_list
 
+    def get_all_steps(self, data_type: DataTypeIdentifier | None = None) -> list[ElnEntryStep]:
+        """
+        Get a list of every entry in the experiment. Optionally filter the returned entries by a data type.
+
+        Makes a webservice call to retrieve every entry in the experiment if they were not already previously cached.
+
+        :param data_type: A data type used to filter the returned entries. If None is given, returns all entries. If
+            a data type name or wrapper is given, only returns entries that match that data type name or wrapper.
+        :return: Every entry in the experiment in order of appearance that match the provided data type, if any.
+        """
+        if self.__queried_all_steps is False:
+            self.__queried_all_steps = True
+            self.__steps.update({step.get_name(): step for step in self.__protocol.get_sorted_step_list()})
+        all_steps: list[ElnEntryStep] = self.__protocol.get_sorted_step_list()
+        if data_type is None:
+            return all_steps
+        data_type: str = AliasUtil.to_data_type_name(data_type)
+        return [x for x in all_steps if data_type in x.get_data_type_names()]
+
+    def get_step_by_option(self, key: str, value: str | None = None) -> ElnEntryStep:
+        """
+        Retrieve the step in this experiment that contains an entry option with the provided key and value.
+        Throws an exception if no entries or multiple entries in the experiment match.
+
+        :param key: The key of the entry option to match on.
+        :param value: The value of the entry option to match on. If not provided, then only matches on key.
+        :return: The entry in this experiment that matches the provided entry option key and value.
+        """
+        steps: list[ElnEntryStep] = self.get_steps_by_option(key, value)
+        count: int = len(steps)
+        if count != 1:
+            option = key + ("::" + value if value is not None else "")
+            raise SapioException(f"{('No' if count == 0 else 'Multiple')} entries in this experiment match the "
+                                 f"provided option: {option}")
+        return steps[0]
+
+    def get_steps_by_option(self, key: str, value: str | None = None) -> list[ElnEntryStep]:
+        """
+        Retrieve every step in this experiment that contains an entry option with the provided key and value.
+
+        :param key: The key of the entry option to match on.
+        :param value: The value of the entry option to match on. If not provided, then only matches on key.
+        :return: The entries in this experiment that match the provided entry option key and value.
+        """
+        ret_list: list[ElnEntryStep] = []
+        for step in self.get_all_steps():
+            options: dict[str, str] = self.get_step_options(step)
+            if key in options:
+                if value is None or options[key] == value:
+                    ret_list.append(step)
+        return ret_list
+
     def get_step_records(self, step: Step) -> list[DataRecord]:
         """
         Query for the data records for the given step. The returned records are not cached by the ExperimentHandler.
@@ -466,6 +634,15 @@ class ExperimentHandler:
             The records may be provided as either DataRecords, PyRecordModels, or WrappedRecordModels.
         """
         step = self.__to_eln_step(step)
+        if not records:
+            return
+        dt: str = AliasUtil.to_singular_data_type_name(records)
+        if ElnBaseDataType.is_base_data_type(dt):
+            raise SapioException(f"{dt} is an ELN data type. This function call has no effect on ELN data types. "
+                                 f"Use add_eln_rows or add_sample_details instead.")
+        if dt != step.get_data_type_names()[0]:
+            raise SapioException(f"Cannot add {dt} records to entry {step.get_name()} of type "
+                                 f"{step.get_data_type_names()[0]}.")
         step.add_records(AliasUtil.to_data_records(records))
 
     def remove_step_records(self, step: Step, records: Iterable[SapioRecord]) -> None:
@@ -484,6 +661,15 @@ class ExperimentHandler:
             The records may be provided as either DataRecords, PyRecordModels, or WrappedRecordModels.
         """
         step = self.__to_eln_step(step)
+        if not records:
+            return
+        dt: str = AliasUtil.to_singular_data_type_name(records)
+        if ElnBaseDataType.is_base_data_type(dt):
+            raise SapioException(f"{dt} is an ELN data type. This function call has no effect on ELN data types. "
+                                 f"Use remove_eln_rows or remove_sample_details instead.")
+        if dt != step.get_data_type_names()[0]:
+            raise SapioException(f"Cannot remove {dt} records from entry {step.get_name()} of type "
+                                 f"{step.get_data_type_names()[0]}.")
         step.remove_records(AliasUtil.to_data_records(records))
 
     def set_step_records(self, step: Step, records: Iterable[SapioRecord]) -> None:
@@ -507,11 +693,17 @@ class ExperimentHandler:
             The records may be provided as either DataRecords, PyRecordModels, or WrappedRecordModels.
         """
         step = self.__to_eln_step(step)
+        if records:
+            dt: str = AliasUtil.to_singular_data_type_name(records)
+            if ElnBaseDataType.is_base_data_type(dt):
+                raise SapioException(f"{dt} is an ELN data type. This function call has no effect on ELN data types. "
+                                     f"Use add_eln_rows or add_sample_details instead.")
+            if dt != step.get_data_type_names()[0]:
+                raise SapioException(f"Cannot set {dt} records for entry {step.get_name()} of type "
+                                     f"{step.get_data_type_names()[0]}.")
         step.set_records(AliasUtil.to_data_records(records))
 
     # FR-46496 - Provide alias of set_step_records for use with form entries.
-    # TODO: Provide a similar aliased function for attachment entries once sapiopylib allows setting multiple
-    #  attachments to an attachment step.
     def set_form_record(self, step: Step, record: SapioRecord) -> None:
         """
         Sets the record for a form entry.
@@ -529,7 +721,8 @@ class ExperimentHandler:
         self.set_step_records(step, [record])
 
     # FR-46496 - Provide functions for adding and removing rows from an ELN data type entry.
-    def add_eln_rows(self, step: Step, count: int) -> list[PyRecordModel]:
+    def add_eln_rows(self, step: Step, count: int, wrapper_type: type[WrappedType] | None = None) \
+            -> list[PyRecordModel | WrappedType]:
         """
         Add rows to an ELNExperimentDetail or ELNSampleDetail table entry. The rows will not appear in the system
         until a record manager store and commit has occurred.
@@ -541,15 +734,37 @@ class ExperimentHandler:
             The step may be provided as either a string for the name of the step or an ElnEntryStep.
             If given a name, throws an exception if no step of the given name exists in the experiment.
         :param count: The number of new rows to add to the entry.
+        :param wrapper_type: Optionally wrap the ELN data type in a record model wrapper. If not provided, returns
+            an unwrapped PyRecordModel.
         :return: A list of the newly created rows.
         """
         step = self.__to_eln_step(step)
         if step.eln_entry.entry_type != ElnEntryType.Table:
             raise SapioException("The provided step is not a table entry.")
         dt: str = step.get_data_type_names()[0]
-        if not self.__is_eln_type(dt):
+        if not ElnBaseDataType.is_eln_type(dt):
             raise SapioException("The provided step is not an ELN data type entry.")
-        return self.__inst_man.add_new_records(dt, count)
+        records: list[PyRecordModel] = self.__inst_man.add_new_records(dt, count)
+        if wrapper_type:
+            return self.__inst_man.wrap_list(records, wrapper_type)
+        return records
+
+    def add_eln_row(self, step: Step, wrapper_type: type[WrappedType] | None = None) -> PyRecordModel | WrappedType:
+        """
+        Add a row to an ELNExperimentDetail or ELNSampleDetail table entry. The row will not appear in the system
+        until a record manager store and commit has occurred.
+
+        If no step functions have been called before and a step is being searched for by name, queries for the
+        list of steps in the experiment and caches them.
+
+        :param step:
+            The step may be provided as either a string for the name of the step or an ElnEntryStep.
+            If given a name, throws an exception if no step of the given name exists in the experiment.
+        :param wrapper_type: Optionally wrap the ELN data type in a record model wrapper. If not provided, returns
+            an unwrapped PyRecordModel.
+        :return: The newly created row.
+        """
+        return self.add_eln_rows(step, 1, wrapper_type)[0]
 
     def remove_eln_rows(self, step: Step, records: list[SapioRecord]) -> None:
         """
@@ -571,10 +786,14 @@ class ExperimentHandler:
         """
         step = self.__to_eln_step(step)
         dt: str = step.get_data_type_names()[0]
-        if not self.__is_eln_type(dt):
+        if not ElnBaseDataType.is_eln_type(dt):
             raise SapioException("The provided step is not an ELN data type entry.")
-        if any([x.data_type_name != dt for x in records]):
-            raise SapioException("Not all of the provided records match the data type of the step.")
+        if not records:
+            return
+        record_dt: str = AliasUtil.to_singular_data_type_name(records, False)
+        if record_dt != dt:
+            raise SapioException(f"Cannot remove {dt} records from entry {step.get_name()} of type "
+                                 f"{step.get_data_type_names()[0]}.")
         # If any rows were provided as data records, turn them into record models before deleting them, as otherwise
         # this function would need to make a webservice call to do the deletion.
         data_records: list[DataRecord] = []
@@ -588,16 +807,59 @@ class ExperimentHandler:
             for record in record_models:
                 record.delete()
 
-    # TODO: Remove and use the function of the same name in ElnBaseDataType in the future. Currently this function is
-    #  bugged in sapiopylib and is comparing against base_type.name instead of base_type.value.
-    @staticmethod
-    def __is_eln_type(data_type: str):
-        if data_type is None or not data_type:
-            return False
-        for base_type in ElnBaseDataType:
-            if data_type.lower().startswith(base_type.value.lower()):
-                return True
-        return False
+    def remove_eln_row(self, step: Step, record: SapioRecord) -> None:
+        """
+        Remove a row from an ELNExperimentDetail or ELNSampleDetail table entry. ELN data type table entries display all
+        records in the system that match the entry's data type. This means that removing rows from an ELN data type
+        table entry is equivalent to deleting the records for the rows.
+
+        The row will not be deleted in the system until a record manager store and commit has occurred.
+
+        If no step functions have been called before and a step is being searched for by name, queries for the
+        list of steps in the experiment and caches them.
+
+        :param step:
+            The step may be provided as either a string for the name of the step or an ElnEntryStep.
+            If given a name, throws an exception if no step of the given name exists in the experiment.
+        :param record:
+            The record to remove from the given step.
+            The record may be provided as either a DataRecord, PyRecordModel, or WrappedRecordModel.
+        """
+        self.remove_eln_rows(step, [record])
+
+    def add_sample_details(self, step: Step, samples: list[RecordModel], wrapper_type: type[WrappedType]) \
+            -> list[PyRecordModel | WrappedType]:
+        """
+        Add sample details to a sample details entry while relating them to the input sample records.
+
+        :param step:
+            The step may be provided as either a string for the name of the step or an ElnEntryStep.
+            If given a name, throws an exception if no step of the given name exists in the experiment.
+        :param samples: The sample records to add the sample details to.
+        :param wrapper_type: Optionally wrap the sample details in a record model wrapper. If not provided, returns
+            an unwrapped PyRecordModel.
+        :return: The newly created sample details. The indices of the samples in the input list match the index of the
+            sample details in this list that they are related to.
+        """
+        step = self.__to_eln_step(step)
+        if step.eln_entry.entry_type != ElnEntryType.Table:
+            raise SapioException("The provided step is not a table entry.")
+        dt: str = step.get_data_type_names()[0]
+        if not ElnBaseDataType.is_eln_type(dt) or ElnBaseDataType.get_base_type(dt) != ElnBaseDataType.SAMPLE_DETAIL:
+            raise SapioException("The provided step is not an ELNSampleDetail entry.")
+        records: list[PyRecordModel] = []
+        for sample in samples:
+            if sample.data_type_name != "Sample":
+                raise SapioException(f"Received a {sample.data_type_name} record when Sample records were expected.")
+            detail: PyRecordModel = sample.add(Child.create_by_name(dt))
+            detail.set_field_values({
+                "SampleId": sample.get_field_value("SampleId"),
+                "OtherSampleId": sample.get_field_value("OtherSampleId")
+            })
+            records.append(detail)
+        if wrapper_type:
+            return self.__inst_man.wrap_list(records, wrapper_type)
+        return records
 
     def update_step(self, step: Step,
                     entry_name: str | None = None,
@@ -713,10 +975,7 @@ class ExperimentHandler:
         if dependency_set is not None:
             entry.dependency_set = dependency_set
         if entry_status is not None:
-            # TODO: sapiopylib is currently storing the status of entries as strings when first queried. For the sake of not
-            #  breaking comparisons to enums that expect this behavior, also setting the status to the enum's string.
-            #  The ".value" can be removed once sapiopylib is fixed.
-            entry.entry_status = entry_status.value
+            entry.entry_status = entry_status
         if order is not None:
             entry.order = order
         if description is not None:
@@ -752,7 +1011,7 @@ class ExperimentHandler:
         if clear_template_item_fulfilled_timestamp is True:
             entry.template_item_fulfilled_timestamp = None
         if entry_options_map is not None:
-            self.__step_options.update({step: entry_options_map})
+            self.__step_options.update({step.get_id(): entry_options_map})
 
     def get_step_option(self, step: Step, option: str) -> str:
         """
@@ -782,8 +1041,8 @@ class ExperimentHandler:
         list of steps in the experiment and caches them.
 
         Getting the step options requires a webservice query, which is made the first time any step option
-        method is called for a specific step. The step options are cached so that subsequent calls of this
-        method for that step don't make a webservice call.
+        method is called for any step in this experiment. The step options are cached so that subsequent calls of this
+        method don't make a webservice call.
 
         :param step:
             The step to get the options of.
@@ -791,7 +1050,10 @@ class ExperimentHandler:
             If given a name, throws an exception if no step of the given name exists in the experiment.
         :return: The map of options for the input step.
         """
-        return self.__get_step_options(step)
+        step = self.__to_eln_step(step)
+        if step not in self.__step_options:
+            self.__step_options.update(ExperimentReportUtil.get_experiment_entry_options(self.user, self.get_all_steps()))
+        return self.__step_options[step.get_id()]
 
     def add_step_options(self, step: Step, mapping: Mapping[str, str]):
         """
@@ -867,12 +1129,9 @@ class ExperimentHandler:
             If given a name, throws an exception if no step of the given name exists in the experiment.
         """
         step = self.__to_eln_step(step)
-        if step.eln_entry.entry_status not in self.__COMPLETE_STATUSES:
+        if step.eln_entry.entry_status not in self.__ENTRY_COMPLETE_STATUSES:
             step.complete_step()
-            # TODO: sapiopylib is currently storing the status of entries as strings when first queried. For the sake of not
-            #  breaking comparisons to enums that expect this behavior, also setting the status to the enum's string.
-            #  The ".value" can be removed once sapiopylib is fixed.
-            step.eln_entry.entry_status = ExperimentEntryStatus.Completed.value
+            step.eln_entry.entry_status = ExperimentEntryStatus.Completed
 
     def unlock_step(self, step: Step) -> None:
         """
@@ -888,12 +1147,30 @@ class ExperimentHandler:
             If given a name, throws an exception if no step of the given name exists in the experiment.
         """
         step = self.__to_eln_step(step)
-        if step.eln_entry.entry_status in self.__LOCKED_STATUSES:
+        if step.eln_entry.entry_status in self.__ENTRY_LOCKED_STATUSES:
             step.unlock_step()
-            # TODO: sapiopylib is currently storing the status of entries as strings when first queried. For the sake of not
-            #  breaking comparisons to enums that expect this behavior, also setting the status to the enum's string.
-            #  The ".value" can be removed once sapiopylib is fixed.
-            step.eln_entry.entry_status = ExperimentEntryStatus.UnlockedChangesRequired.value
+            step.eln_entry.entry_status = ExperimentEntryStatus.UnlockedChangesRequired
+
+    def disable_step(self, step: Step) -> None:
+        """
+        Set the status of the input step to Disabled. This is the state that entries are in when they are waiting for
+        entries that they are dependent upon to be submitted before they can be enabled. If you have unsubmitted an
+        entry and want its dependent entries to be locked again, then you would use this to set their status to
+        disabled.
+
+        Makes a webservice call to update the step. Checks if the step is already unlocked, and does nothing if so.
+
+        If no step functions have been called before and a step is being searched for by name, queries for the
+        list of steps in the experiment and caches them.
+
+        :param step:
+            The step to disable.
+            The step may be provided as either a string for the name of the step or an ElnEntryStep.
+            If given a name, throws an exception if no step of the given name exists in the experiment.
+        """
+        step = self.__to_eln_step(step)
+        if step.eln_entry.entry_status in self.__ENTRY_LOCKED_STATUSES:
+            self.update_step(step, entry_status=ExperimentEntryStatus.Disabled)
 
     def step_is_submitted(self, step: Step) -> bool:
         """
@@ -908,7 +1185,7 @@ class ExperimentHandler:
             If given a name, throws an exception if no step of the given name exists in the experiment.
         :return: True if the step's status is Completed or CompletedApproved. False otherwise.
         """
-        return self.__to_eln_step(step).eln_entry.entry_status in self.__COMPLETE_STATUSES
+        return self.__to_eln_step(step).eln_entry.entry_status in self.__ENTRY_COMPLETE_STATUSES
 
     def step_is_locked(self, step: Step) -> bool:
         """
@@ -924,7 +1201,7 @@ class ExperimentHandler:
         :return: True if the step's status is Completed, CompletedApproved, Disabled, LockedAwaitingApproval,
             or LockedRejected. False otherwise.
         """
-        return self.__to_eln_step(step).eln_entry.entry_status in self.__LOCKED_STATUSES
+        return self.__to_eln_step(step).eln_entry.entry_status in self.__ENTRY_LOCKED_STATUSES
 
     def __to_eln_step(self, step: Step) -> ElnEntryStep:
         """
@@ -946,16 +1223,3 @@ class ExperimentHandler:
             return self.__exp_options
         self.__exp_options = self.__eln_man.get_notebook_experiment_options(self.__exp_id)
         return self.__exp_options
-
-    def __get_step_options(self, step: Step) -> dict[str, str]:
-        """
-        Cache the options for the input step if they haven't been cached yet.
-
-        :return: The entry options for the input step.
-        """
-        step = self.__to_eln_step(step)
-        if step in self.__step_options:
-            return self.__step_options.get(step)
-        options: dict[str, str] = step.get_options()
-        self.__step_options.update({step: options})
-        return options