sapiopycommons 2025.6.16a562__tar.gz → 2025.6.19a564__tar.gz

{sapiopycommons-2025.6.16a562 → sapiopycommons-2025.6.19a564}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sapiopycommons
-Version: 2025.6.16a562
+Version: 2025.6.19a564
 Summary: Official Sapio Python API Utilities Package
 Project-URL: Homepage, https://github.com/sapiosciences
 Author-email: Jonathan Steck <jsteck@sapiosciences.com>, Yechen Qiao <yqiao@sapiosciences.com>

{sapiopycommons-2025.6.16a562 → sapiopycommons-2025.6.19a564}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sapiopycommons"
-version='2025.06.16a562'
+version='2025.06.19a564'
 authors = [
     { name="Jonathan Steck", email="jsteck@sapiosciences.com" },
     { name="Yechen Qiao", email="yqiao@sapiosciences.com" },

{sapiopycommons-2025.6.16a562 → sapiopycommons-2025.6.19a564}/src/sapiopycommons/customreport/auto_pagers.py

@@ -62,6 +62,12 @@ class CustomReportDictAutoPager(_DictReportPagerBase):
     def __init__(self, user: UserIdentifier, report_criteria: CustomReportCriteria,
                  page_number: int = 0, page_size: int = _default_report_page_size):
         """
+        IMPORTANT NOTICE: Custom reports that are not single data type (i.e. they have terms or columns from multiple
+        data types) may not be 100% time accurate. Such reports use the system's ancestor table to retrieve the
+        relationships, and this table takes some time to update after relationships are updated, especially for more
+        populous data types. If you need 100% time accurate results to the current state of the records and
+        relationships in the database, you should query for the records directly instead of using a custom report.
+
         :param user: The current webhook context or a user object to send requests from.
         :param report_criteria: The custom report criteria to run.
         :param page_number: The page number to start on. The first page is page 0.
@@ -83,6 +89,12 @@ class SystemReportDictAutoPager(_DictReportPagerBase):
     def __init__(self, user: UserIdentifier, report_name: str,
                  page_number: int = 0, page_size: int = _default_report_page_size):
         """
+        IMPORTANT NOTICE: Custom reports that are not single data type (i.e. they have terms or columns from multiple
+        data types) may not be 100% time accurate. Such reports use the system's ancestor table to retrieve the
+        relationships, and this table takes some time to update after relationships are updated, especially for more
+        populous data types. If you need 100% time accurate results to the current state of the records and
+        relationships in the database, you should query for the records directly instead of using a custom report.
+
         :param user: The current webhook context or a user object to send requests from.
         :param report_name: The name of the system report to run.
         :param page_number: The page number to start on. The first page is page 0.
@@ -173,6 +185,12 @@ class CustomReportRecordAutoPager(_RecordReportPagerBase):
                  wrapper_type: type[WrappedType] | str, page_number: int = 0,
                  page_size: int = _default_record_page_size):
         """
+        IMPORTANT NOTICE: Custom reports that are not single data type (i.e. they have terms or columns from multiple
+        data types) may not be 100% time accurate. Such reports use the system's ancestor table to retrieve the
+        relationships, and this table takes some time to update after relationships are updated, especially for more
+        populous data types. If you need 100% time accurate results to the current state of the records and
+        relationships in the database, you should query for the records directly instead of using a custom report.
+
         :param user: The current webhook context or a user object to send requests from.
         :param report_criteria: The custom report criteria to run.
         :param wrapper_type: The record model wrapper type or data type name of the records being searched for.
@@ -198,6 +216,12 @@ class SystemReportRecordAutoPager(_RecordReportPagerBase):
     def __init__(self, user: UserIdentifier, report_name: str, wrapper_type: type[WrappedType] | str,
                  page_number: int = 0, page_size: int = _default_record_page_size):
         """
+        IMPORTANT NOTICE: Custom reports that are not single data type (i.e. they have terms or columns from multiple
+        data types) may not be 100% time accurate. Such reports use the system's ancestor table to retrieve the
+        relationships, and this table takes some time to update after relationships are updated, especially for more
+        populous data types. If you need 100% time accurate results to the current state of the records and
+        relationships in the database, you should query for the records directly instead of using a custom report.
+
         :param user: The current webhook context or a user object to send requests from.
         :param report_name: The name of the system report to run.
         :param wrapper_type: The record model wrapper type or data type name of the records being searched for.

{sapiopycommons-2025.6.16a562 → sapiopycommons-2025.6.19a564}/src/sapiopycommons/eln/experiment_handler.py

@@ -290,12 +290,19 @@ class ExperimentHandler:
         :param entry: The entry to add to the cache.
         :return: The entry that was added to the cache as an ElnEntryStep.
         """
+        # ExperimentEntries are stored as ElnEntrySteps in the cache.
         if isinstance(entry, ExperimentEntry):
             entry = ElnEntryStep(self._protocol, entry)
-        self._steps.append(entry)
-        self._steps_by_name.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.
+        # PR-47699: Confirm that this entry is part of the experiment that this handler is for.
+        if entry.eln_entry.parent_experiment_id != self._exp_id:
+            raise SapioException(f"Entry with ID {entry.get_id()} is not part of the experiment with ID "
+                                 f"{self._exp_id}.")
+        # PR-47699: Don't add the entry if it is already in the cache.
+        if entry.get_id() not in self._steps_by_id:
+            self._steps.append(entry)
+            self._steps_by_name.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 that cache when necessary.
         return entry
 
     def add_entries_to_caches(self, entries: list[ExperimentEntry | ElnEntryStep]) -> list[ElnEntryStep]:
@@ -326,9 +333,11 @@ class ExperimentHandler:
         self._tabs_by_name[tab.tab_name] = tab
 
     # FR-46495: Split the creation of the experiment in launch_experiment into a create_experiment function.
+    # CR-47703: Allow create_experiment and launch_experiment to accept None as a template_name to create a blank
+    # experiment. Also allow a SapioUser object to be provided as context instead of a full SapioWebhookContext object.
     @staticmethod
-    def create_experiment(context: SapioWebhookContext,
-                          template_name: str,
+    def create_experiment(context: UserIdentifier,
+                          template_name: str | None = None,
                           experiment_name: str | None = None,
                           parent_record: SapioRecord | None = None, *,
                           template_version: int | None = None, active_templates_only: bool = True) -> ElnExperiment:
@@ -339,8 +348,9 @@ class ExperimentHandler:
         templates match the same criteria, the first template that is encountered in the query is used. Throws an
         exception if no template is found. Also makes a webservice request to create the experiment.
 
-        :param context: The current webhook context.
-        :param template_name: The name of the template to create the experiment from.
+        :param context: The current webhook context or a user object to send requests from.
+        :param template_name: The name of the template to create the experiment from. If None, a blank experiment
+            is created.
         :param experiment_name: The name to give to the experiment after it is created. If not provided, defaults to the
             display name of the template.
         :param parent_record: The parent record to attach this experiment under. This record must be an eligible
@@ -352,20 +362,27 @@ class ExperimentHandler:
         :param active_templates_only: Whether only active templates should be queried for.
         :return: The newly created experiment.
         """
-        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
+        user = AliasUtil.to_sapio_user(context)
+        cache = ExperimentCacheManager(user)
+        eln_manager: ElnManager = DataMgmtServer.get_eln_manager(user)
+
+        template_id: int | None = None
+        if template_name:
+            launch_template: ElnTemplate = cache.get_experiment_template(template_name, active_templates_only,
+                                                                         template_version, first_match=True)
+            template_id = launch_template.template_id
+            if experiment_name is None:
+                experiment_name: str = launch_template.display_name
+        elif experiment_name is None:
+            experiment_name = f"{user.username}'s Experiment"
         if parent_record is not None:
             parent_record: DataRecord = AliasUtil.to_data_record(parent_record)
-        notebook_init = InitializeNotebookExperimentPojo(experiment_name, launch_template.template_id, parent_record)
-        return context.eln_manager.create_notebook_experiment(notebook_init)
+        notebook_init = InitializeNotebookExperimentPojo(experiment_name, template_id, parent_record)
+        return eln_manager.create_notebook_experiment(notebook_init)
 
     @staticmethod
-    def launch_experiment(context: SapioWebhookContext,
-                          template_name: str,
+    def launch_experiment(context: UserIdentifier,
+                          template_name: str | None = None,
                           experiment_name: str | None = None,
                           parent_record: SapioRecord | None = None, *,
                           template_version: int | None = None,
@@ -378,8 +395,9 @@ class ExperimentHandler:
         templates match the same criteria, the first template that is encountered in the query is used. Throws an
         exception if no template is found. Also makes a webservice request to create the experiment.
 
-        :param context: The current webhook context.
-        :param template_name: The name of the template to create the experiment from.
+        :param context: The current webhook context or a user object to send requests from.
+        :param template_name: The name of the template to create the experiment from. If None, a blank experiment
+            is created.
         :param experiment_name: The name to give to the experiment after it is created. If not provided, defaults to the
             display name of the template.
         :param parent_record: The parent record to attach this experiment under. This record must be an eligible
@@ -629,14 +647,14 @@ class ExperimentHandler:
         """
         return all([x is not None for x in self.get_steps(step_names, False)])
 
-    def get_step(self, step_name: str | int, exception_on_none: bool = True) -> ElnEntryStep | None:
+    def get_step(self, step_name: Step, exception_on_none: bool = True) -> ElnEntryStep | None:
         """
         Get the step of the given name from 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_name: The name or ID for the step to return.
+        :param step_name: The identifier for the step to return.
         :param exception_on_none: If false, returns None if the entry can't be found. If true, raises an exception
             when the named entry doesn't exist in the experiment.
         :return: An ElnEntrySteps matching the provided name. If there is no match and no exception is to be thrown,
@@ -644,26 +662,43 @@ class ExperimentHandler:
         """
         return self.get_steps([step_name], exception_on_none)[0]
 
-    def get_steps(self, step_names: Iterable[str | int], exception_on_none: bool = True) -> list[ElnEntryStep | None]:
+    def get_steps(self, step_names: Iterable[Step], exception_on_none: bool = True) -> list[ElnEntryStep | None]:
         """
         Get a list of steps of the given names from the experiment, sorted in the same order as the names are provided.
 
         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_names: A list of names or IDs for the entries to return and the order to return them in.
+        :param step_names: A list of identifiers for the entries to return and the order to return them in.
         :param exception_on_none: If false, returns None for entries that can't be found. If true, raises an exception
             when the named entry doesn't exist in the experiment.
         :return: A list of ElnEntrySteps matching the provided names in the order they were provided in. If there is no
             match for a given step and no exception is to be thrown, returns None for that step.
         """
+        # CR-47700: Support getting steps from entry objects.
+        step_ids: list[str | int] = []
+        for step in step_names:
+            # Convert any ElnEntrySteps into ExperimentEntries.
+            if isinstance(step, ElnEntryStep):
+                step: ExperimentEntry = step.eln_entry
+            # If an ExperimentEntry is provided, then add its ID to the list of steps to return.
+            if isinstance(step, ExperimentEntry):
+                step_ids.append(step.entry_id)
+                # Add this entry to the caches so that it doesn't need to be queried for. This will also verify that
+                # this entry belongs to the experiment that this handler is for.
+                self.add_entry_to_caches(step)
+            elif isinstance(step, (str, int)):
+                step_ids.append(step)
+
         ret_list: list[ElnEntryStep | None] = []
-        for step_id in step_names:
+        for step_id in step_ids:
             # If we haven't queried the system for all steps in the experiment yet, then the reason that a step is
             # missing may be because it wasn't in the webhook context. Therefore, query all steps and then check
             # if the step name is still missing from the experiment before potentially throwing an exception.
-            if self._queried_all_steps is False and step_id not in self._steps_by_name and step_id not in self._steps_by_id:
-                self._query_all_steps()
+            if not self._queried_all_steps:
+                if ((isinstance(step_id, str) and step_id not in self._steps_by_name)
+                        or (isinstance(step_id, int) and step_id not in self._steps_by_id)):
+                    self._query_all_steps()
             if isinstance(step_id, str):
                 step: ElnEntryStep = self._steps_by_name.get(step_id)
             else:
@@ -758,7 +793,7 @@ class ExperimentHandler:
             If given a name, throws an exception if no step of the given name exists in the experiment.
         :return: The data records for the given step.
         """
-        return self.__to_eln_step(step).get_records()
+        return self.get_step(step).get_records()
 
     def get_step_models(self, step: Step, wrapper_type: type[WrappedType] | None = None) \
             -> list[WrappedType] | list[PyRecordModel]:
@@ -795,7 +830,7 @@ class ExperimentHandler:
             A list of records to add to the given step.
             The records may be provided as either DataRecords, PyRecordModels, or WrappedRecordModels.
         """
-        step = self.__to_eln_step(step)
+        step: ElnEntryStep = self.get_step(step)
         if not records:
             return
         dt: str = AliasUtil.to_singular_data_type_name(records)
@@ -810,8 +845,7 @@ class ExperimentHandler:
 
     def remove_step_records(self, step: Step, records: Iterable[SapioRecord]) -> None:
         """
-        Make a webservice call to remove a list of records from a step. Only functions for global data type table
-        entries. For removing from an ELN data type table entry, see remove_eln_rows.
+        Make a webservice call to remove a list of records from a step.
 
         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.
@@ -823,7 +857,7 @@ class ExperimentHandler:
             A list of records to remove from the given step.
             The records may be provided as either DataRecords, PyRecordModels, or WrappedRecordModels.
         """
-        step = self.__to_eln_step(step)
+        step: ElnEntryStep = self.get_step(step)
         if not records:
             return
         dt: str = AliasUtil.to_singular_data_type_name(records)
@@ -856,7 +890,7 @@ class ExperimentHandler:
             A list of records to set for the given step,
             The records may be provided as either DataRecords, PyRecordModels, or WrappedRecordModels.
         """
-        step = self.__to_eln_step(step)
+        step: ElnEntryStep = self.get_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.
@@ -888,7 +922,7 @@ class ExperimentHandler:
             The record may be provided as either a DataRecord, PyRecordModel, or WrappedRecordModel.
         """
         self.set_step_records(step, [record])
-        step = self.__to_eln_step(step)
+        step: ElnEntryStep = self.get_step(step)
         if isinstance(step.eln_entry, ExperimentFormEntry):
             step.eln_entry.record_id = AliasUtil.to_data_record(record).record_id
 
@@ -927,7 +961,7 @@ class ExperimentHandler:
             an unwrapped PyRecordModel.
         :return: A list of the newly created rows.
         """
-        step = self.__to_eln_step(step)
+        step: ElnEntryStep = self.get_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]
@@ -969,7 +1003,7 @@ class ExperimentHandler:
         :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)
+        step: ElnEntryStep = self.get_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]
@@ -1027,7 +1061,7 @@ class ExperimentHandler:
             A list of records to remove from the given step.
             The records may be provided as either DataRecords, PyRecordModels, or WrappedRecordModels.
         """
-        step = self.__to_eln_step(step)
+        step: ElnEntryStep = self.get_step(step)
         dt: str = step.get_data_type_names()[0]
         if not ElnBaseDataType.is_eln_type(dt):
             raise SapioException("The provided step is not an ELN data type entry.")
@@ -1120,7 +1154,7 @@ class ExperimentHandler:
         # FR-47468: Deprecating this since the entry-specific update criteria should be used instead.
         warnings.warn("Update step is deprecated. Use force_entry_update instead.",
                       DeprecationWarning)
-        step: ElnEntryStep = self.__to_eln_step(step)
+        step: ElnEntryStep = self.get_step(step)
         update = AbstractElnEntryUpdateCriteria(step.eln_entry.entry_type)
 
         # These two variables could be iterables that aren't lists. Convert them to plain
@@ -1171,7 +1205,7 @@ class ExperimentHandler:
             If given a name, throws an exception if no step of the given name exists in the experiment.
         :param update: The update to make to the step.
         """
-        step = self.__to_eln_step(step)
+        step: ElnEntryStep = self.get_step(step)
         self._eln_man.update_experiment_entry(self._exp_id, step.get_id(), update)
         self._update_entry_details(step, update)
 
@@ -1191,7 +1225,7 @@ class ExperimentHandler:
             If given a name, throws an exception if no step of the given name exists in the experiment.
         :param update: The update to make to the step.
         """
-        step = self.__to_eln_step(step)
+        step: ElnEntryStep = self.get_step(step)
         if step.eln_entry.entry_type != update.entry_type:
             raise SapioException(f"The provided step and update criteria are not of the same entry type. "
                                  f"The step is of type {step.eln_entry.entry_type} and the update criteria is of type "
@@ -1222,6 +1256,8 @@ class ExperimentHandler:
         Commit all the stored updates to the entries in this experiment. The updates are made in the order that they
         were stored.
         """
+        if not self._step_updates:
+            return
         self._eln_man.update_experiment_entries(self._exp_id, self._step_updates)
         for step_id, criteria in self._step_updates.items():
             self._update_entry_details(self._steps_by_id[step_id], criteria)
@@ -1388,7 +1424,7 @@ 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.
         """
-        step = self.__to_eln_step(step)
+        step: ElnEntryStep = self.get_step(step)
         if step not in self._step_options:
             self._step_options.update(ExperimentReportUtil.get_experiment_entry_options(self.user,
                                                                                         self.get_all_steps()))
@@ -1414,6 +1450,8 @@ class ExperimentHandler:
             (e.g. a dictionary). If an option key already exists and is provided in the mapping, overwrites the existing
             value for that key.
         """
+        # PR-47698: Convert the given step to an ElnEntryStep if it is not already one.
+        step: ElnEntryStep = self.get_step(step)
         options: dict[str, str] = self.get_step_options(step)
         options.update(mapping)
         update = AbstractElnEntryUpdateCriteria(step.eln_entry.entry_type)
@@ -1434,7 +1472,7 @@ class ExperimentHandler:
             If given a name, throws an exception if no step of the given name exists in the experiment.
         """
         # Avoid unnecessary calls if the step is already initialized.
-        step: ElnEntryStep = self.__to_eln_step(step)
+        step: ElnEntryStep = self.get_step(step)
         if step.eln_entry.template_item_fulfilled_timestamp is None:
             update = AbstractElnEntryUpdateCriteria(step.eln_entry.entry_type)
             update.template_item_fulfilled_timestamp = TimeUtil.now_in_millis()
@@ -1454,7 +1492,7 @@ class ExperimentHandler:
             If given a name, throws an exception if no step of the given name exists in the experiment.
         """
         # Avoid unnecessary calls if the step is already uninitialized.
-        step: ElnEntryStep = self.__to_eln_step(step)
+        step: ElnEntryStep = self.get_step(step)
         if step.eln_entry.template_item_fulfilled_timestamp is not None:
             update = AbstractElnEntryUpdateCriteria(step.eln_entry.entry_type)
             update.clear_template_item_fulfilled_timestamp = True
@@ -1473,7 +1511,7 @@ 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.
         """
-        step = self.__to_eln_step(step)
+        step: ElnEntryStep = self.get_step(step)
         if step.eln_entry.entry_status not in self._ENTRY_COMPLETE_STATUSES:
             step.complete_step()
             step.eln_entry.entry_status = ExperimentEntryStatus.Completed
@@ -1491,7 +1529,7 @@ 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.
         """
-        step = self.__to_eln_step(step)
+        step: ElnEntryStep = self.get_step(step)
         if step.eln_entry.entry_status in self._ENTRY_LOCKED_STATUSES:
             step.unlock_step()
             step.eln_entry.entry_status = ExperimentEntryStatus.UnlockedChangesRequired
@@ -1513,7 +1551,7 @@ 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.
         """
-        step = self.__to_eln_step(step)
+        step: ElnEntryStep = self.get_step(step)
         if step.eln_entry.entry_status in self._ENTRY_LOCKED_STATUSES:
             update = AbstractElnEntryUpdateCriteria(step.eln_entry.entry_type)
             update.entry_status = ExperimentEntryStatus.Disabled
@@ -1532,7 +1570,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._ENTRY_COMPLETE_STATUSES
+        return self.get_step(step).eln_entry.entry_status in self._ENTRY_COMPLETE_STATUSES
 
     def step_is_locked(self, step: Step) -> bool:
         """
@@ -1548,7 +1586,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._ENTRY_LOCKED_STATUSES
+        return self.get_step(step).eln_entry.entry_status in self._ENTRY_LOCKED_STATUSES
 
     # FR-47464: Some functions that can help with entry placement.
     def get_all_tabs(self) -> list[ElnExperimentTab]:
@@ -1660,7 +1698,7 @@ class ExperimentHandler:
             If given a name, throws an exception if no step of the given name exists in the experiment.
         :return: The tab that the input step is located in.
         """
-        step = self.__to_eln_step(step)
+        step: ElnEntryStep = self.get_step(step)
         tab_id = step.eln_entry.notebook_experiment_tab_id
         if tab_id not in self._tabs_by_id:
             self.get_all_tabs()
@@ -1697,7 +1735,7 @@ class ExperimentHandler:
             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)
+        step: ElnEntryStep = self.get_step(step)
         entry: ExperimentEntry = step.eln_entry
         return ElnEntryPosition(entry.notebook_experiment_tab_id,
                                 entry.order,
@@ -1741,21 +1779,7 @@ class ExperimentHandler:
         new_entries: list[ExperimentEntry] = self._eln_man.add_protocol_template(self._exp_id, protocol, position)
         return self.add_entries_to_caches(new_entries)
 
-    def __to_eln_step(self, step: Step) -> ElnEntryStep:
-        """
-        Convert a variable that could be either a string or an ElnEntryStep to just an ElnEntryStep.
-        This will query and cache the steps for the experiment if the input step is a name and the steps have not been
-        cached before.
-
-        :return: The input step as an ElnEntryStep.
-        """
-        if isinstance(step, str):
-            return self.get_step(step)
-        if isinstance(step, int):
-            return self._steps_by_id.get(step)
-        if isinstance(step, ExperimentEntry):
-            return self.add_entry_to_caches(step)
-        return step
+    # CR-47700: Deleted __to_eln_step since it became redundant with the get_step method.
 
     def __to_eln_tab(self, tab: Tab) -> ElnExperimentTab:
         """

{sapiopycommons-2025.6.16a562 → sapiopycommons-2025.6.19a564}/src/sapiopycommons/eln/experiment_report_util.py

@@ -2,7 +2,7 @@ from sapiopylib.rest.ELNService import ElnManager
 from sapiopylib.rest.User import SapioUser
 from sapiopylib.rest.pojo.CustomReport import CustomReportCriteria, AbstractReportTerm, RawReportTerm
 from sapiopylib.rest.pojo.datatype.FieldDefinition import FieldType
-from sapiopylib.rest.pojo.eln.ElnExperiment import ElnExperiment, ElnExperimentQueryCriteria
+from sapiopylib.rest.pojo.eln.ElnExperiment import ElnExperiment, ElnExperimentQueryCriteria, ElnTemplate
 from sapiopylib.rest.pojo.eln.SapioELNEnums import ElnExperimentStatus, ElnBaseDataType
 from sapiopylib.rest.utils.recordmodel.PyRecordModel import PyRecordModel
 from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedType
@@ -250,17 +250,22 @@ class ExperimentReportUtil:
         return {exp: list(records) for exp, records in exp_to_records.items()}
 
     @staticmethod
-    def get_experiment_options(context: UserIdentifier, experiments: list[ExperimentIdentifier]) \
+    def get_experiment_options(context: UserIdentifier, experiments: list[ExperimentIdentifier | ElnTemplate]) \
             -> dict[int, dict[str, str]]:
         """
-        Run a custom report to retrieve the experiment options for all the provided experiments. Effectively a batched
-        version of the get_notebook_experiment_options function of ElnManager.
+        Run a custom report to retrieve the experiment options for all the provided experiments or experiment templates.
+        Effectively a batched version of the get_notebook_experiment_options function of ElnManager.
 
         :param context: The current webhook context or a user object to send requests from.
-        :param experiments: The experiment identifiers to retrieve the experiment options for.
+        :param experiments: The experiment/template identifiers to retrieve the experiment options for.
         :return: A dictionary mapping the notebook experiment ID to the options for that experiment.
         """
-        exp_ids: list[int] = AliasUtil.to_notebook_ids(experiments)
+        exp_ids: list[int] = []
+        for exp in experiments:
+            if isinstance(exp, ElnTemplate):
+                exp_ids.append(exp.template_id)
+            else:
+                exp_ids.append(AliasUtil.to_notebook_id(exp))
 
         report_builder = CustomReportBuilder(NotebookExperimentOptionPseudoDef.DATA_TYPE_NAME)
         tb = report_builder.get_term_builder()

{sapiopycommons-2025.6.16a562 → sapiopycommons-2025.6.19a564}/src/sapiopycommons/files/file_util.py

@@ -331,7 +331,9 @@ class FileUtil:
             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()
+            # PR-47697: Indent the getvalue call into the outer with block. Making the call outside of the with block
+            # throws an I/O exception.
+            return zip_buffer.getvalue()
 
     # Deprecated functions:
 

{sapiopycommons-2025.6.16a562 → sapiopycommons-2025.6.19a564}/src/sapiopycommons/general/aliases.py

@@ -7,7 +7,6 @@ from sapiopylib.rest.pojo.datatype.FieldDefinition import FieldType, AbstractVel
 from sapiopylib.rest.pojo.eln.ElnExperiment import ElnExperiment
 from sapiopylib.rest.pojo.eln.ExperimentEntry import ExperimentEntry
 from sapiopylib.rest.pojo.eln.SapioELNEnums import ElnBaseDataType
-from sapiopylib.rest.pojo.eln.eln_headings import ElnExperimentTab
 from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
 from sapiopylib.rest.utils.Protocols import ElnExperimentProtocol, ElnEntryStep
 from sapiopylib.rest.utils.recordmodel.PyRecordModel import PyRecordModel, AbstractRecordModel

{sapiopycommons-2025.6.16a562 → sapiopycommons-2025.6.19a564}/src/sapiopycommons/general/audit_log.py

@@ -8,6 +8,7 @@ from sapiopycommons.customreport.column_builder import ColumnBuilder
 from sapiopycommons.customreport.term_builder import TermBuilder
 from sapiopycommons.datatype.pseudo_data_types import AuditLogPseudoDef
 from sapiopycommons.general.aliases import RecordIdentifier, AliasUtil, UserIdentifier, FieldIdentifier, FieldValue
+from sapiopycommons.general.exceptions import SapioException
 
 
 class EventType(Enum):
@@ -134,6 +135,9 @@ class AuditLogUtil:
         :param fields: The data field names to include changes for.
         :return: The constructed CustomReportCriteria object, which can be used to run a report on the audit log.
         """
+        # PR-47701: Throw an exception if no records are provided.
+        if not records:
+            raise SapioException("No records provided. Please provide at least one record to build a report for.")
         # Build the raw report term querying for any entry with a matching record ID value to the record ID's
         # passed in.
         record_ids = AliasUtil.to_record_ids(records)
@@ -160,6 +164,9 @@ class AuditLogUtil:
         :return: A dictionary where the keys are the record identifiers passed in, and the values are a list of
             AuditLogEntry objects which match the record id value of those records.
         """
+        # PR-47701: Return an empty dictionary if no records are provided.
+        if not records:
+            return {}
         # First, we must build our report criteria for running the Custom Report.
         criteria = AuditLogUtil.create_data_record_audit_log_report(records, fields)
 

{sapiopycommons-2025.6.16a562 → sapiopycommons-2025.6.19a564}/src/sapiopycommons/general/custom_report_util.py

@@ -24,6 +24,12 @@ class CustomReportUtil:
         System reports are also known as predefined searches in the system and must be defined in the data designer for
         a specific data type. That is, saved searches created by users cannot be run using this function.
 
+        IMPORTANT NOTICE: Custom reports that are not single data type (i.e. they have terms or columns from multiple
+        data types) may not be 100% time accurate. Such reports use the system's ancestor table to retrieve the
+        relationships, and this table takes some time to update after relationships are updated, especially for more
+        populous data types. If you need 100% time accurate results to the current state of the records and
+        relationships in the database, you should query for the records directly instead of using a custom report.
+
         :param context: The current webhook context or a user object to send requests from.
         :param report_name: The name of the system report to run.
         :param filters: If provided, filter the results of the report using the given mapping of headers to values to
@@ -63,6 +69,12 @@ class CustomReportUtil:
         results. They are like advanced or predefined searches from the system, except they are constructed from
         within the webhook instead of from within the system.
 
+        IMPORTANT NOTICE: Custom reports that are not single data type (i.e. they have terms or columns from multiple
+        data types) may not be 100% time accurate. Such reports use the system's ancestor table to retrieve the
+        relationships, and this table takes some time to update after relationships are updated, especially for more
+        populous data types. If you need 100% time accurate results to the current state of the records and
+        relationships in the database, you should query for the records directly instead of using a custom report.
+
         :param context: The current webhook context or a user object to send requests from.
         :param report_criteria: The custom report criteria to run.
         :param filters: If provided, filter the results of the report using the given mapping of headers to values to

{sapiopycommons-2025.6.16a562 → sapiopycommons-2025.6.19a564}/src/sapiopycommons/processtracking/custom_workflow_handler.py

@@ -94,6 +94,9 @@ class QueueItemHandler:
     """
     A class used for handling the display of records in custom process queues, which are controlled in the system by
     ProcessQueueItem data types.
+
+    IMPORTANT NOTICE: This is only for custom processes that make use of ProcessQueueItem records. For experiment
+    processes that use AssignedProcess records, see the ProcessTracking class.
     """
     user: SapioUser
     context: ProcessQueueContext | None
@@ -261,6 +264,9 @@ class QueueItemHandler:
         Given a list of records, create process queue item records for them at the provided process and step names.
         You must store and commit using the record model manager in order for these changes to take effect.
 
+        IMPORTANT NOTICE: This is only for custom processes that make use of ProcessQueueItem records. For experiment
+        processes that use AssignedProcess records, see the ProcessTracking class.
+
         :param records: The records to create process queue items for.
         :param process: The name of the process to queue for.
         :param step: The name of the step in the above process to queue for. This is the "Workflow Name" field of the
@@ -293,6 +299,9 @@ class QueueItemHandler:
         criteria and remove them from the queue by setting the ShowInQueue field on the process queue items to false.
         You must store and commit using the record model manager in order for these changes to take effect.
 
+        IMPORTANT NOTICE: This is only for custom processes that make use of ProcessQueueItem records. For experiment
+        processes that use AssignedProcess records, see the ProcessTracking class.
+
         :param records: The records to remove from the queue.
         :param wrapper: The record model wrapper for the process queue items being updated. If not provided, the
             returned records will be PyRecordModels instead of WrappedRecordModels.

{sapiopycommons-2025.6.16a562 → sapiopycommons-2025.6.19a564}/src/sapiopycommons/processtracking/endpoints.py

@@ -5,6 +5,12 @@ from sapiopycommons.general.aliases import RecordIdentifier, AliasUtil, Experime
 
 
 class ProcessTracking:
+    """
+    A class for calling the Foundations process tracking endpoints.
+
+    IMPORTANT NOTICE: This is only for experiment processes that make use of AssignedProcess records. For custom
+    processes that use ProcessQueueItem records, see the QueueItemHandler class.
+    """
     @staticmethod
     def assign_to_process(context: UserIdentifier, data_type: DataTypeIdentifier, records: list[RecordIdentifier],
                           process_name: str, step_number: int | None = None, branch_id: int | None = None,
@@ -14,6 +20,9 @@ class ProcessTracking:
         at that step.
         Synonymous with what occurs during request creation or when using the assign to process button.
 
+        IMPORTANT NOTICE: This is only for experiment processes that make use of AssignedProcess records. For custom
+        processes that use ProcessQueueItem records, see the QueueItemHandler class.
+
         :param context: The current webhook context or a user object to send requests from.
         :param data_type: The data type of the tracked records.
         :param records: A list of the tracked records.
@@ -46,6 +55,9 @@ class ProcessTracking:
         tracked records from "Ready for -" to "In Process -" for their current step.
         Synonymous with what occurs when starting a process step in the system.
 
+        IMPORTANT NOTICE: This is only for experiment processes that make use of AssignedProcess records. For custom
+        processes that use ProcessQueueItem records, see the QueueItemHandler class.
+
         :param context: The current webhook context or a user object to send requests from.
         :param data_type: The data type of the tracked records.
         :param records: A list of the tracked records.
@@ -73,6 +85,9 @@ class ProcessTracking:
         Moves the assigned process down to the descendant sample(s) if both samples are provided in the records list.
         Synonymous with what occurs when completing an experiment in the system.
 
+        IMPORTANT NOTICE: This is only for experiment processes that make use of AssignedProcess records. For custom
+        processes that use ProcessQueueItem records, see the QueueItemHandler class.
+
         :param context: The current webhook context or a user object to send requests from.
         :param data_type: The data type of the tracked records.
         :param records: A list of the tracked records.
@@ -96,6 +111,9 @@ class ProcessTracking:
         records must be "In Process -" for the given step.
         Synonymous with what occurs when failing a sample due to a QC failure in a process in the system.
 
+        IMPORTANT NOTICE: This is only for experiment processes that make use of AssignedProcess records. For custom
+        processes that use ProcessQueueItem records, see the QueueItemHandler class.
+
         :param context: The current webhook context or a user object to send requests from.
         :param data_type: The data type of the tracked records.
         :param records: A list of the tracked records.
@@ -122,6 +140,9 @@ class ProcessTracking:
         will move their status to "Ready for -" for the next step in the process, or "Completed -" if this was the
         last step.
 
+        IMPORTANT NOTICE: This is only for experiment processes that make use of AssignedProcess records. For custom
+        processes that use ProcessQueueItem records, see the QueueItemHandler class.
+
         :param context: The current webhook context or a user object to send requests from.
         :param data_type: The data type of the tracked records.
         :param records: A list of the tracked records.
@@ -149,6 +170,9 @@ class ProcessTracking:
         step will move their status to "Ready for -" for the next step in the process, or "Completed -" if this was the
         last step.
 
+        IMPORTANT NOTICE: This is only for experiment processes that make use of AssignedProcess records. For custom
+        processes that use ProcessQueueItem records, see the QueueItemHandler class.
+
         :param context: The current webhook context or a user object to send requests from.
         :param data_type: The data type of the tracked records.
         :param records: A list of the tracked records.
@@ -180,6 +204,9 @@ class ProcessTracking:
         Synonymous with what occurs when reprocessing records to a previous step due to QC failures in a process in the
         system.
 
+        IMPORTANT NOTICE: This is only for experiment processes that make use of AssignedProcess records. For custom
+        processes that use ProcessQueueItem records, see the QueueItemHandler class.
+
         :param context: The current webhook context or a user object to send requests from.
         :param records: A list of ReturnPoint records to reprocess to.
         """