sapiopycommons 2025.3.25a459__py3-none-any.whl → 2025.3.31a466__py3-none-any.whl

sapiopycommons/eln/experiment_handler.py

@@ -26,6 +26,7 @@ from sapiopylib.rest.pojo.eln.SapioELNEnums import ExperimentEntryStatus, ElnExp
     ElnBaseDataType
 from sapiopylib.rest.pojo.eln.eln_headings import ElnExperimentTab, ElnExperimentTabAddCriteria
 from sapiopylib.rest.pojo.eln.field_set import ElnFieldSetInfo
+from sapiopylib.rest.pojo.eln.protocol_template import ProtocolTemplateInfo
 from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
 from sapiopylib.rest.pojo.webhook.WebhookDirective import ElnExperimentDirective
 from sapiopylib.rest.pojo.webhook.WebhookResult import SapioWebhookResult
@@ -40,6 +41,7 @@ from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedType
 from sapiopylib.rest.utils.recordmodel.properties import Child
 
 from sapiopycommons.datatype.data_fields import SystemFields
+from sapiopycommons.datatype.experiment_cache import ExperimentCacheManager
 from sapiopycommons.eln.experiment_report_util import ExperimentReportUtil
 from sapiopycommons.eln.experiment_tags import PLATE_DESIGNER_PLUGIN
 from sapiopycommons.general.aliases import AliasUtil, SapioRecord, ExperimentIdentifier, UserIdentifier, \
@@ -51,8 +53,8 @@ from sapiopycommons.recordmodel.record_handler import RecordHandler
 Step: TypeAlias = str | ElnEntryStep
 """An object representing an identifier to an ElnEntryStep. May be either the name of the step or the ElnEntryStep
 itself."""
-Tab: TypeAlias = str | ElnExperimentTab
-"""An object representing an identifier to an ElnExperimentTab. May be either the name of the tab or the
+TabIdentifier: TypeAlias = int | str | ElnExperimentTab
+"""An object representing an identifier to an ElnExperimentTab. May be either the ID or name of the tab, or the
 ElnExperimentTab itself."""
 ElnDataTypeFields: TypeAlias = AbstractVeloxFieldDefinition | ElnFieldSetInfo | str | int
 """An object representing an identifier to an ElnDataType field. These can be field definitions for ad hoc fields,
@@ -77,6 +79,8 @@ class ExperimentHandler:
     # Managers.
     _eln_man: ElnManager
     """The ELN manager. Used for updating the experiment and its steps."""
+    _exp_cache: ExperimentCacheManager
+    """The experiment cache manager. Used for caching experiment-related information."""
     _inst_man: RecordModelInstanceManager
     """The record model instance manager. Used for wrapping the data records of a step as record models."""
     _rec_handler: RecordHandler
@@ -113,9 +117,6 @@ class ExperimentHandler:
     _tabs_by_name: dict[str, ElnExperimentTab]
     """The tabs for this experiment by their name. Only cached when first accessed."""
 
-    _predefined_fields: dict[str, dict[str, AbstractVeloxFieldDefinition]]
-    """A dictionary of predefined fields for each ELN data type. Only cached when first accessed."""
-
     # Constants
     _ENTRY_COMPLETE_STATUSES = [ExperimentEntryStatus.Completed, ExperimentEntryStatus.CompletedApproved]
     """The set of statuses that an ELN entry could have and be considered completed/submitted."""
@@ -173,6 +174,7 @@ class ExperimentHandler:
 
         # Grab various managers that may be used.
         self._eln_man = DataMgmtServer.get_eln_manager(self.user)
+        self._exp_cache = ExperimentCacheManager(self.user)
         self._inst_man = RecordModelManager(self.user).instance_manager
         self._rec_handler = RecordHandler(self.user)
 
@@ -284,30 +286,35 @@ class ExperimentHandler:
         self._tabs.clear()
         self._tabs_by_name.clear()
 
-    def add_entry_to_caches(self, entry: ExperimentEntry | ElnEntryStep) -> None:
+    def add_entry_to_caches(self, entry: ExperimentEntry | ElnEntryStep) -> ElnEntryStep:
         """
         Add the given entry to the cache of steps for this experiment. This is necessary in order for certain methods to
         work. You should only need to do this if you have created a new entry in your code using a method outside
         of this ExperimentHandler.
 
         :param entry: The entry to add to the cache.
+        :return: The entry that was added to the cache as an ElnEntryStep.
         """
         if isinstance(entry, ExperimentEntry):
             entry = ElnEntryStep(self._protocol, entry)
         self._steps.update({entry.get_name(): entry})
         self._steps_by_id.update({entry.get_id(): entry})
         # Skipping the options cache. The get_step_options method will update the cache when necessary.
+        return entry
 
-    def add_entries_to_caches(self, entries: list[ExperimentEntry | ElnEntryStep]) -> None:
+    def add_entries_to_caches(self, entries: list[ExperimentEntry | ElnEntryStep]) -> list[ElnEntryStep]:
         """
         Add the given entries to the cache of steps for this experiment. This is necessary in order for certain methods
         to work. You should only need to do this if you have created a new entry in your code using a method outside
         of this ExperimentHandler.
 
         :param entries: The entries to add to the cache.
+        :return: The entries that were added to the cache as ElnEntrySteps.
         """
+        new_entries: list[ElnEntryStep] = []
         for entry in entries:
-            self.add_entry_to_caches(entry)
+            new_entries.append(self.add_entry_to_caches(entry))
+        return new_entries
 
     def add_tab_to_cache(self, tab: ElnExperimentTab) -> None:
         """
@@ -348,22 +355,10 @@ class ExperimentHandler:
         :param active_templates_only: Whether only active templates should be queried for.
         :return: The newly created experiment.
         """
-        template_query = TemplateExperimentQueryPojo(latest_version_only=(template_version is None),
-                                                     active_templates_only=active_templates_only)
-        templates: list[ElnTemplate] = context.eln_manager.get_template_experiment_list(template_query)
-        launch_template: ElnTemplate | None = None
-        for template in templates:
-            if template.template_name != template_name:
-                continue
-            if template_version is not None and template.template_version != template_version:
-                continue
-            launch_template = template
-            break
-        if launch_template is None:
-            raise SapioException(f"No template with the name \"{template_name}\"" +
-                                 ("" if template_version is None else f" and the version {template_version}") +
-                                 f" found.")
-
+        launch_template: ElnTemplate = ExperimentCacheManager(context).get_experiment_template(template_name,
+                                                                                               active_templates_only,
+                                                                                               template_version,
+                                                                                               first_match=True)
         if experiment_name is None:
             experiment_name: str = launch_template.display_name
         if parent_record is not None:
@@ -590,6 +585,9 @@ class ExperimentHandler:
         """
         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.
+
+        NOTE: This will cause the usual process tracking logic to run as if you'd clicked the "Complete Experiment"
+        toolbar button. This includes moving the in process samples forward to the next step in the process.
         """
         if not self.experiment_is_complete():
             self._protocol.complete_protocol()
@@ -600,9 +598,11 @@ class ExperimentHandler:
         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.
+        NOTE: This will cause the usual process tracking logic to run as if you'd clicked the "Cancel Experiment"
+        toolbar button. This includes moving the in process samples back into the process queue for the current step.
+
+        On version 24.12 and earlier, this was not the case, as the process tracking logic was tied to the button
+        instead of being on the experiment status change.
         """
         if not self.experiment_is_canceled():
             self._protocol.cancel_protocol()
@@ -782,8 +782,9 @@ class ExperimentHandler:
             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.")
+            raise SapioException(f"{dt} is an ELN data type. This function call has no effect on ELN data types. ELN "
+                                 f"records that are committed to the system will automatically appear in the ELN entry "
+                                 f"with the matching data type name.")
         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]}.")
@@ -809,8 +810,9 @@ class ExperimentHandler:
             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.")
+            # CR-47532: Add remove_step_records support for Experiment Detail and Sample Detail entries.
+            self.remove_eln_rows(step, records)
+            return
         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]}.")
@@ -839,9 +841,14 @@ class ExperimentHandler:
         step = self.__to_eln_step(step)
         if records:
             dt: str = AliasUtil.to_singular_data_type_name(records)
+            # CR-47532: Add set_step_records support for Experiment Detail and Sample Detail entries.
             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.")
+                remove_rows: list[PyRecordModel] = []
+                for record in self.get_step_models(step):
+                    if record not in records:
+                        remove_rows.append(record)
+                self.remove_eln_rows(step, remove_rows)
+                return
             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]}.")
@@ -868,6 +875,23 @@ class ExperimentHandler:
             step.eln_entry.record_id = AliasUtil.to_data_record(record).record_id
 
     # FR-46496 - Provide functions for adding and removing rows from an ELN data type entry.
+    def add_eln_row(self, step: Step, wrapper_type: type[WrappedType] | None = None) -> WrappedType | PyRecordModel:
+        """
+        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 add_eln_rows(self, step: Step, count: int, wrapper_type: type[WrappedType] | None = None) \
             -> list[WrappedType] | list[PyRecordModel]:
         """
@@ -896,10 +920,64 @@ class ExperimentHandler:
             return self._inst_man.wrap_list(records, wrapper_type)
         return records
 
-    def add_eln_row(self, step: Step, wrapper_type: type[WrappedType] | None = None) -> WrappedType | PyRecordModel:
+    def add_sample_detail(self, step: Step, sample: RecordModel,
+                           wrapper_type: type[WrappedType] | None = None) \
+            -> WrappedType | PyRecordModel:
         """
-        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.
+        Add a sample detail to a sample detail entry while relating it to the input sample record.
+
+        :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 sample: The sample record to add the sample detail to.
+        :param wrapper_type: Optionally wrap the sample detail in a record model wrapper. If not provided, returns
+            an unwrapped PyRecordModel.
+        :return: The newly created sample detail.
+        """
+        return self.add_sample_details(step, [sample], wrapper_type)[0]
+
+    def add_sample_details(self, step: Step, samples: list[RecordModel],
+                           wrapper_type: type[WrappedType] | None = None) \
+            -> list[WrappedType] | list[PyRecordModel]:
+        """
+        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 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.
@@ -907,11 +985,11 @@ class ExperimentHandler:
         :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.
+        :param record:
+            The record to remove from the given step.
+            The record may be provided as either a DataRecord, PyRecordModel, or WrappedRecordModel.
         """
-        return self.add_eln_rows(step, 1, wrapper_type)[0]
+        self.remove_eln_rows(step, [record])
 
     def remove_eln_rows(self, step: Step, records: list[SapioRecord]) -> None:
         """
@@ -954,61 +1032,6 @@ class ExperimentHandler:
             for record in record_models:
                 record.delete()
 
-    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] | None = None) \
-            -> list[WrappedType] | list[PyRecordModel]:
-        """
-        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
-
     # noinspection PyPep8Naming
     def update_step(self, step: Step,
                     entry_name: str | None = None,
@@ -1703,7 +1726,7 @@ class ExperimentHandler:
             self.get_all_tabs()
         return self._tabs_by_name[tab_name]
 
-    def get_steps_in_tab(self, tab: Tab, data_type: DataTypeIdentifier | None = None) -> list[ElnEntryStep]:
+    def get_steps_in_tab(self, tab: TabIdentifier, data_type: DataTypeIdentifier | None = None) -> list[ElnEntryStep]:
         """
         Get all the steps in the input tab sorted in order of appearance.
 
@@ -1713,7 +1736,8 @@ class ExperimentHandler:
         If the steps in the experiment have not been queried before, queries for the list of steps in the experiment
         and caches them.
 
-        :param tab: The tab or tab name to get the steps of.
+        :param tab: The tab to get the steps of. This can be either an ElnExperimentTab object, or the name or ID of
+            the tab.
         :param data_type: The data type to filter the steps by. If None, all steps are returned.
         :return: A list of all the steps in the input tab sorted in order of appearance.
         """
@@ -1725,7 +1749,7 @@ class ExperimentHandler:
         steps.sort(key=lambda s: (s.eln_entry.order, s.eln_entry.column_order))
         return steps
 
-    def get_next_entry_order_in_tab(self, tab: Tab) -> int:
+    def get_next_entry_order_in_tab(self, tab: TabIdentifier) -> int:
         """
         Get the next available order for a new entry in the input tab.
 
@@ -1735,12 +1759,71 @@ class ExperimentHandler:
         If the steps in the experiment have not been queried before, queries for the list of steps in the experiment
         and caches them.
 
-        :param tab: The tab or tab name to get the steps of.
+        :param tab: The tab to get the next entry order of. This can be either an ElnExperimentTab object, or the name
+            or ID of the tab.
         :return: The next available order for a new entry in the input tab.
         """
         steps = self.get_steps_in_tab(tab)
         return steps[-1].eln_entry.order + 1 if steps else 0
 
+    # FR-47530: Add functions for dealing with entry positioning.
+    def step_to_position(self, step: Step) -> ElnEntryPosition:
+        """
+        Get the position of the input step in the experiment.
+
+        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 get the position of.
+            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.
+        :return: The position of the input step in the experiment.
+        """
+        step: ElnEntryStep = self.__to_eln_step(step)
+        entry: ExperimentEntry = step.eln_entry
+        return ElnEntryPosition(entry.notebook_experiment_tab_id,
+                                entry.order,
+                                entry.column_span,
+                                entry.column_order)
+
+    def step_at_position(self, position: ElnEntryPosition) -> Step | None:
+        """
+        Get the step at the input position in the experiment.
+
+        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 position: The position to get the step at.
+        :return: The step at the input position in the experiment, or None if no step exists at that position.
+        """
+        if position.tab_id is None or position.order is None:
+            raise SapioException("The provided position must at least have a tab ID and order.")
+        for step in self.get_steps_in_tab(position.tab_id):
+            entry: ExperimentEntry = step.eln_entry
+            if entry.order != position.order:
+                continue
+            if position.column_span is not None and entry.column_span != position.column_span:
+                continue
+            if position.column_order is not None and entry.column_order != position.column_order:
+                continue
+            return step
+        return None
+
+    # FR-47530: Create a function for adding protocol templates to the experiment.
+    def add_protocol(self, protocol: ProtocolTemplateInfo | int, position: ElnEntryPosition) -> list[ElnEntryStep]:
+        """
+        Add a protocol to the experiment. Updates the handler cache with the newly created entries.
+
+        :param protocol: The protocol to add. This can be either a ProtocolTemplateInfo object or the ID of the
+            protocol template.
+        :param position: The position that the protocol's first entry will be placed at.
+        :return: The newly created protocol entries.
+        """
+        protocol = protocol if isinstance(protocol, int) else protocol.template_id
+        new_entries: list[ExperimentEntry] = self._eln_man.add_protocol_template(self._exp_id, protocol, position)
+        return self.add_entries_to_caches(new_entries)
+
     # FR-47468: Add functions for creating new entries in the experiment.
     def create_attachment_step(self, entry_name: str, data_type: DataTypeIdentifier,
                                *,
@@ -2114,24 +2197,12 @@ class ExperimentHandler:
         for field in fields:
             if isinstance(field, AbstractVeloxFieldDefinition):
                 field_defs.append(field)
-            elif isinstance(field, ElnFieldSetInfo):
-                field_defs.extend(self._eln_man.get_predefined_fields_from_field_set_id(field.field_set_id))
+            elif isinstance(field, (int, ElnFieldSetInfo)):
+                field_defs.extend(self._exp_cache.get_field_set_fields(field))
             elif isinstance(field, str):
-                field_defs.append(self._predefined_field(field, dt))
-            elif isinstance(field, int):
-                field_defs.extend(self._eln_man.get_predefined_fields_from_field_set_id(field))
+                field_defs.append(self._exp_cache.get_predefined_field(field, dt))
         return field_defs
 
-    def _predefined_field(self, field_name: str, data_type: ElnBaseDataType) -> AbstractVeloxFieldDefinition:
-        """
-        Get the predefined field of the given name for the given ELN data type.
-        """
-        # TODO: Should this be in some sort of DataTypeCacheManager?
-        if data_type not in self._predefined_fields:
-            fields: list[AbstractVeloxFieldDefinition] = self._eln_man.get_predefined_fields(data_type)
-            self._predefined_fields[data_type.data_type_name] = {x.data_field_name: x for x in fields}
-        return self._predefined_fields[data_type.data_type_name][field_name]
-
     def __to_eln_step(self, step: Step) -> ElnEntryStep:
         """
         Convert a variable that could be either a string or an ElnEntryStep to just an ElnEntryStep.
@@ -2142,7 +2213,7 @@ class ExperimentHandler:
         """
         return self.get_step(step) if isinstance(step, str) else step
 
-    def __to_eln_tab(self, tab: Tab) -> ElnExperimentTab:
+    def __to_eln_tab(self, tab: TabIdentifier) -> ElnExperimentTab:
         """
         Convert a variable that could be either a string or an ElnExperimentTab to just an ElnExperimentTab.
         This will query and cache the tabs for the experiment if the input tab is a name and the tabs have not been
@@ -2150,4 +2221,8 @@ class ExperimentHandler:
 
         :return: The input tab as an ElnExperimentTab.
         """
-        return self.get_tab(tab) if isinstance(tab, str) else tab
+        if isinstance(tab, str):
+            return self.get_tab(tab)
+        if isinstance(tab, int):
+            return [x for x in self._tabs if x.tab_id == tab][0]
+        return tab

sapiopycommons/files/file_util.py

@@ -327,10 +327,10 @@ class FileUtil:
         :param files: A dictionary of file name to file data as a string or bytes.
         :return: The bytes for a zip file containing the input files.
         """
-        zip_buffer: io.BytesIO = io.BytesIO()
-        with zipfile.ZipFile(zip_buffer, "w", zipfile.ZIP_DEFLATED) as zip_file:
-            for file_name, file_data in files.items():
-                zip_file.writestr(file_name, file_data)
+        with io.BytesIO() as zip_buffer:
+            with zipfile.ZipFile(zip_buffer, "w", zipfile.ZIP_DEFLATED) as zip_file:
+                for file_name, file_data in files.items():
+                    zip_file.writestr(file_name, file_data)
         return zip_buffer.getvalue()
 
     # Deprecated functions:

sapiopycommons/general/accession_service.py

@@ -199,7 +199,7 @@ class AccessionRequestId(AbstractAccessionServiceOperator):
 
     Properties:
         numberOfCharacters: Number of characters maximum in the request ID.
-        accessorName: This is a legacy variable from drum.getNextIdListByMapName(), which allows setting different "accessorName" from old system. We need this for compability patch for converting these to the new preference format.
+        accessorName: This is a legacy variable from drum.getNextIdListByMapName(), which allows setting different "accessorName" from old system. We need this for compatibility patch for converting these to the new preference format.
     """
     _num_of_characters: int
     _accessor_name: str
@@ -341,7 +341,7 @@ class AccessionService:
     def get_affixed_id_in_batch(self, data_type_name: str, data_field_name: str, num_ids: int, prefix: str | None,
                                 suffix: str | None, num_digits: int | None, start_num: int = 1) -> list[str]:
         """
-        Get the batch affixed IDs that are maximal in cache and contiguious for a particular datatype.datafield under a given format.
+        Get the batch affixed IDs that are maximal in cache and contiguous for a particular datatype.datafield under a given format.
         :param data_type_name: The datatype name to look for max ID
         :param data_field_name: The datafield name to look for max ID
         :param num_ids: The number of IDs to accession.

sapiopycommons/general/data_structure_util.py

@@ -0,0 +1,115 @@
+from enum import Enum
+from typing import Iterable, Any, Collection
+
+from sapiopycommons.general.exceptions import SapioException
+
+
+class ArrayTransformation(Enum):
+    """
+    An enumeration of the different transformations that can be applied to a 2D array.
+    """
+    ROTATE_CLOCKWISE = 0
+    ROTATE_COUNTER_CLOCKWISE = 1
+    ROTATE_180_DEGREES = 2
+    MIRROR_HORIZONTAL = 3
+    MIRROR_VERTICAL = 4
+
+
+# FR-47524: Create a DataStructureUtils class that implements various collection utility functions from our Java
+# libraries.
+class DataStructureUtil:
+    """
+    Utility class for working with data structures. Copies from ListUtil, SetUtil, and various other classes in
+    our Java library.
+    """
+    @staticmethod
+    def find_first_or_none(values: Iterable[Any]) -> Any | None:
+        """
+        Get the first value from an iterable, or None if the iterable is empty.
+
+        :param values: An iterable of values.
+        :return: The first value from the input, or None if the input is empty.
+        """
+        return next(iter(values), None)
+
+    @staticmethod
+    def remove_null_values(values: Iterable[Any]) -> list[Any]:
+        """
+        Remove null values from a list.
+
+        :param values: An iterable of values.
+        :return: A list containing all the non-null values from the input.
+        """
+        return [value for value in values if value is not None]
+
+    @staticmethod
+    def transform_2d_array(values: Collection[Collection[Any]], transformation: ArrayTransformation) \
+            -> Collection[Collection[Any]]:
+        """
+        Perform a transformation on a 2D list.
+
+        :param values: An iterable of iterables. The iterables should all be of the same size.
+        :param transformation: The transformation to apply to the input.
+        :return: A new 2D list containing the input transformed according to the specified transformation.
+        """
+        x: int = len(values)
+        for row in values:
+            y = len(row)
+            if y != x:
+                raise SapioException(f"Input must be a square 2D array. The provided array has a length of {x} but "
+                                     f"at least one row has a length of {y}.")
+
+        match transformation:
+            case ArrayTransformation.ROTATE_CLOCKWISE:
+                return [list(row) for row in zip(*values[::-1])]
+            case ArrayTransformation.ROTATE_COUNTER_CLOCKWISE:
+                return [list(row) for row in zip(*values)][::-1]
+            case ArrayTransformation.ROTATE_180_DEGREES:
+                return [row[::-1] for row in values[::-1]]
+            case ArrayTransformation.MIRROR_HORIZONTAL:
+                return [list(row[::-1]) for row in values]
+            case ArrayTransformation.MIRROR_VERTICAL:
+                return values[::-1]
+
+        raise SapioException(f"Invalid transformation: {transformation}")
+
+    @staticmethod
+    def flatten_to_list(values: Iterable[Iterable[Any]]) -> list[Any]:
+        """
+        Flatten a list of lists into a single list.
+
+        :param values: An iterable of iterables.
+        :return: A single list containing all the values from the input. Elements are in the order they appear in the
+            input.
+        """
+        return [item for sublist in values for item in sublist]
+
+    @staticmethod
+    def flatten_to_set(values: Iterable[Iterable[Any]]) -> set[Any]:
+        """
+        Flatten a list of lists into a single set.
+
+        :param values: An iterable of iterables.
+        :return: A single set containing all the values from the input. Elements are in the order they appear in the
+            input.
+        """
+        return {item for subset in values for item in subset}
+
+    @staticmethod
+    def invert_dictionary(dictionary: dict[Any, Any], list_values: bool = False) \
+            -> dict[Any, Any] | dict[Any, list[Any]]:
+        """
+        Invert a dictionary, swapping keys and values. Note that the values of the input dictionary must be hashable.
+
+        :param dictionary: A dictionary to invert.
+        :param list_values: If false, keys that share the same value in the input dictionary will be overwritten in
+            the output dictionary so that only the last key remains. If true, the values of the output dictionary will
+            be lists where input keys that share the same value will be stored together.
+        :return: A new dictionary with the keys and values swapped.
+        """
+        if list_values:
+            inverted = {}
+            for key, value in dictionary.items():
+                inverted.setdefault(value, []).append(key)
+            return inverted
+        return {value: key for key, value in dictionary.items()}