sapiopycommons 2025.4.17a486__tar.gz → 2025.4.17a487__tar.gz

{sapiopycommons-2025.4.17a486 → sapiopycommons-2025.4.17a487}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sapiopycommons
-Version: 2025.4.17a486
+Version: 2025.4.17a487
 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.4.17a486 → sapiopycommons-2025.4.17a487}/pyproject.toml

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

{sapiopycommons-2025.4.17a486 → sapiopycommons-2025.4.17a487}/src/sapiopycommons/eln/experiment_handler.py

@@ -8,7 +8,7 @@ from weakref import WeakValueDictionary
 from sapiopycommons.eln.experiment_cache import ExperimentCacheManager
 from sapiopycommons.eln.experiment_report_util import ExperimentReportUtil
 from sapiopycommons.general.aliases import AliasUtil, SapioRecord, ExperimentIdentifier, UserIdentifier, \
-    DataTypeIdentifier, RecordModel, ExperimentEntryIdentifier, TabIdentifier
+    DataTypeIdentifier, RecordModel, ExperimentEntryIdentifier
 from sapiopycommons.general.exceptions import SapioException
 from sapiopycommons.general.time_util import TimeUtil
 from sapiopycommons.recordmodel.record_handler import RecordHandler
@@ -40,8 +40,11 @@ from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedType
 from sapiopylib.rest.utils.recordmodel.properties import Child
 
 Step: TypeAlias = str | ExperimentEntryIdentifier
-"""An object representing an identifier to an ElnEntryStep. May be either the name of the step or the ElnEntryStep
-itself."""
+"""An object representing an identifier to an entry in a particular experiment. This may be the name of the experiment,
+or a typical experiment entry identifier."""
+Tab: TypeAlias = int | str | ElnExperimentTab
+"""An object representing an identifier to a tab in a particular experiment. This may be the tab's order, its name,
+or the tab object itself."""
 
 
 # FR-46064 - Initial port of PyWebhookUtils to sapiopycommons.
@@ -686,7 +689,7 @@ class ExperimentHandler:
             # Re-sort the steps in case any new steps were added before the last time that this was called.
             def sort_steps(step: ElnEntryStep) -> tuple:
                 entry = step.eln_entry
-                tab_order: int = self.get_tab(entry.notebook_experiment_tab_id).tab_order
+                tab_order: int = self.get_tab_for_step(step).tab_order
                 entry_order: int = entry.order
                 column_order: int = entry.column_order
                 return tab_order, entry_order, column_order
@@ -1114,128 +1117,45 @@ class ExperimentHandler:
             If you wish to add options to the existing map of options that an entry has, use the
             add_step_options method.
         """
-        # FR-47468: Deprecating this since the parameters are ordered. The new method requires keyword parameters, so
-        # that we can add new parameters wherever we want without breaking existing code.
-        warnings.warn("Update step is deprecated. Use force_entry_update_params instead.",
+        # 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)
-        self.force_step_update_params(step,
-                                      entry_name=entry_name,
-                                      related_entry_set=related_entry_set,
-                                      dependency_set=dependency_set,
-                                      entry_status=entry_status,
-                                      order=order,
-                                      description=description,
-                                      requires_grabber_plugin=requires_grabber_plugin,
-                                      is_initialization_required=is_initialization_required,
-                                      notebook_experiment_tab_id=notebook_experiment_tab_id,
-                                      entry_height=entry_height,
-                                      column_order=column_order,
-                                      column_span=column_span,
-                                      is_removable=is_removable,
-                                      is_renamable=is_renamable,
-                                      source_entry_id=source_entry_id,
-                                      clear_source_entry_id=clear_source_entry_id,
-                                      is_hidden=is_hidden,
-                                      is_static_view=is_static_View,
-                                      is_shown_in_template=is_shown_in_template,
-                                      template_item_fulfilled_timestamp=template_item_fulfilled_timestamp,
-                                      clear_template_item_fulfilled_timestamp=clear_template_item_fulfilled_timestamp,
-                                      entry_options_map=entry_options_map)
-
-    # FR-47468: Some functions that can help with entry updates.
-    def force_step_update_params(self, step: Step, *,
-                                 entry_name: str | None = None,
-                                 related_entry_set: Iterable[int] | None = None,
-                                 dependency_set: Iterable[int] | None = None,
-                                 entry_status: ExperimentEntryStatus | None = None,
-                                 order: int | None = None,
-                                 description: str | None = None,
-                                 requires_grabber_plugin: bool | None = None,
-                                 is_initialization_required: bool | None = None,
-                                 notebook_experiment_tab_id: int | None = None,
-                                 entry_height: int | None = None,
-                                 column_order: int | None = None,
-                                 column_span: int | None = None,
-                                 is_removable: bool | None = None,
-                                 is_renamable: bool | None = None,
-                                 source_entry_id: int | None = None,
-                                 clear_source_entry_id: bool | None = None,
-                                 is_hidden: bool | None = None,
-                                 is_static_view: bool | None = None,
-                                 is_shown_in_template: bool | None = None,
-                                 template_item_fulfilled_timestamp: int | None = None,
-                                 clear_template_item_fulfilled_timestamp: bool | None = None,
-                                 entry_options_map: dict[str, str] | None = None) -> None:
-        """
-        Immediately sent an update to an entry in this experiment. All changes will be reflected by the ExperimentEntry
-        of the Step that is being updated.
+        step: ElnEntryStep = self.__to_eln_step(step)
+        update = AbstractElnEntryUpdateCriteria(step.eln_entry.entry_type)
 
-        Consider using store_step_update and commit_step_updates instead if the update does not need to be immediate.
+        # These two variables could be iterables that aren't lists. Convert them to plain
+        # lists, since that's what the update criteria is expecting.
+        if related_entry_set is not None:
+            related_entry_set = list(related_entry_set)
+        if dependency_set is not None:
+            dependency_set = list(dependency_set)
 
-        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.
+        update.entry_name = entry_name
+        update.related_entry_set = related_entry_set
+        update.dependency_set = dependency_set
+        update.entry_status = entry_status
+        update.order = order
+        update.description = description
+        update.requires_grabber_plugin = requires_grabber_plugin
+        update.is_initialization_required = is_initialization_required
+        update.notebook_experiment_tab_id = notebook_experiment_tab_id
+        update.entry_height = entry_height
+        update.column_order = column_order
+        update.column_span = column_span
+        update.is_removable = is_removable
+        update.is_renamable = is_renamable
+        update.source_entry_id = source_entry_id
+        update.clear_source_entry_id = clear_source_entry_id
+        update.is_hidden = is_hidden
+        update.is_static_View = is_static_View
+        update.is_shown_in_template = is_shown_in_template
+        update.template_item_fulfilled_timestamp = template_item_fulfilled_timestamp
+        update.clear_template_item_fulfilled_timestamp = clear_template_item_fulfilled_timestamp
+        update.entry_options_map = entry_options_map
 
-        :param step:
-            The entry step to update.
-            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 entry_name: The new name of this entry.
-        :param related_entry_set: The new set of entry IDs for the entries that are related (implicitly dependent) to
-            this entry. Completely overwrites the existing related entries.
-        :param dependency_set: The new set of entry IDs for the entries that are dependent (explicitly dependent) on
-            this entry. Completely overwrites the existing dependent entries.
-        :param entry_status: The new status of this entry.
-        :param order: The row order of this entry in its tab.
-        :param description: The new description of this entry.
-        :param requires_grabber_plugin: Whether this entry's initialization is handled by a grabber plugin. If true,
-            then is_initialization_required is forced to true by the server.
-        :param is_initialization_required: Whether the user is required to manually initialize this entry.
-        :param notebook_experiment_tab_id: The ID of the tab that this entry should appear on.
-        :param entry_height: The height of this entry.
-        :param column_order: The column order of this entry.
-        :param column_span: How many columns this entry spans.
-        :param is_removable: Whether this entry can be removed by the user.
-        :param is_renamable: Whether this entry can be renamed by the user.
-        :param source_entry_id: The ID of this entry from its template.
-        :param clear_source_entry_id: True if the source entry ID should be cleared.
-        :param is_hidden: Whether this entry is hidden from the user.
-        :param is_static_view: Whether this entry is static. Static entries are uneditable and shared across all
-            experiments of the same template.
-        :param is_shown_in_template: Whether this entry is saved to and shown in the experiment's template.
-        :param template_item_fulfilled_timestamp: A timestamp in milliseconds for when this entry was initialized.
-        :param clear_template_item_fulfilled_timestamp: True if the template item fulfilled timestamp should be cleared,
-            uninitializing the entry.
-        :param entry_options_map:
-            The new map of options for this entry. Completely overwrites the existing options map.
-            Any changes to the entry options will update this ExperimentHandler's cache of entry options.
-            If you wish to add options to the existing map of options that an entry has, use the
-            add_step_options method.
-        """
-        update = self._criteria_from_params(step,
-                                            entry_name=entry_name,
-                                            related_entry_set=related_entry_set,
-                                            dependency_set=dependency_set,
-                                            entry_status=entry_status,
-                                            order=order,
-                                            description=description,
-                                            requires_grabber_plugin=requires_grabber_plugin,
-                                            is_initialization_required=is_initialization_required,
-                                            notebook_experiment_tab_id=notebook_experiment_tab_id,
-                                            entry_height=entry_height,
-                                            column_order=column_order,
-                                            column_span=column_span,
-                                            is_removable=is_removable,
-                                            is_renamable=is_renamable,
-                                            source_entry_id=source_entry_id,
-                                            clear_source_entry_id=clear_source_entry_id,
-                                            is_hidden=is_hidden,
-                                            is_static_view=is_static_view,
-                                            is_shown_in_template=is_shown_in_template,
-                                            template_item_fulfilled_timestamp=template_item_fulfilled_timestamp,
-                                            clear_template_item_fulfilled_timestamp=clear_template_item_fulfilled_timestamp,
-                                            entry_options_map=entry_options_map)
         self.force_step_update(step, update)
 
+    # FR-47468: Some functions that can help with entry updates.
     def force_step_update(self, step: Step, update: AbstractElnEntryUpdateCriteria) -> None:
         """
         Immediately sent an update to an entry in this experiment. All changes will be reflected by the ExperimentEntry
@@ -1307,67 +1227,6 @@ class ExperimentHandler:
             self._update_entry_details(self._steps_by_id[step_id], criteria)
         self._step_updates.clear()
 
-    def _criteria_from_params(self, step: Step, *,
-                              entry_name: str | None = None,
-                              related_entry_set: Iterable[int] | None = None,
-                              dependency_set: Iterable[int] | None = None,
-                              entry_status: ExperimentEntryStatus | None = None,
-                              order: int | None = None,
-                              description: str | None = None,
-                              requires_grabber_plugin: bool | None = None,
-                              is_initialization_required: bool | None = None,
-                              notebook_experiment_tab_id: int | None = None,
-                              entry_height: int | None = None,
-                              column_order: int | None = None,
-                              column_span: int | None = None,
-                              is_removable: bool | None = None,
-                              is_renamable: bool | None = None,
-                              source_entry_id: int | None = None,
-                              clear_source_entry_id: bool | None = None,
-                              is_hidden: bool | None = None,
-                              is_static_view: bool | None = None,
-                              is_shown_in_template: bool | None = None,
-                              template_item_fulfilled_timestamp: int | None = None,
-                              clear_template_item_fulfilled_timestamp: bool | None = None,
-                              entry_options_map: dict[str, str] | None = None) -> AbstractElnEntryUpdateCriteria:
-        """
-        Create an abstract update criteria object from the provided parameters for the given step.
-        """
-        step: ElnEntryStep = self.__to_eln_step(step)
-        update = AbstractElnEntryUpdateCriteria(step.eln_entry.entry_type)
-
-        # These two variables could be iterables that aren't lists. Convert them to plain
-        # lists, since that's what the update criteria is expecting.
-        if related_entry_set is not None:
-            related_entry_set = list(related_entry_set)
-        if dependency_set is not None:
-            dependency_set = list(dependency_set)
-
-        update.entry_name = entry_name
-        update.related_entry_set = related_entry_set
-        update.dependency_set = dependency_set
-        update.entry_status = entry_status
-        update.order = order
-        update.description = description
-        update.requires_grabber_plugin = requires_grabber_plugin
-        update.is_initialization_required = is_initialization_required
-        update.notebook_experiment_tab_id = notebook_experiment_tab_id
-        update.entry_height = entry_height
-        update.column_order = column_order
-        update.column_span = column_span
-        update.is_removable = is_removable
-        update.is_renamable = is_renamable
-        update.source_entry_id = source_entry_id
-        update.clear_source_entry_id = clear_source_entry_id
-        update.is_hidden = is_hidden
-        update.is_static_View = is_static_view
-        update.is_shown_in_template = is_shown_in_template
-        update.template_item_fulfilled_timestamp = template_item_fulfilled_timestamp
-        update.clear_template_item_fulfilled_timestamp = clear_template_item_fulfilled_timestamp
-        update.entry_options_map = entry_options_map
-
-        return update
-
     @staticmethod
     def _merge_updates(new_update: AbstractElnEntryUpdateCriteria, old_update: AbstractElnEntryUpdateCriteria) -> None:
         """
@@ -1552,12 +1411,14 @@ 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 mapping: The new options and values to add to the existing step options, provided as some Mapping
-            (e.g. a Dict). If an option key already exists and is provided in the mapping, overwrites the existing value
-            for that key.
+            (e.g. a dictionary). If an option key already exists and is provided in the mapping, overwrites the existing
+            value for that key.
         """
         options: dict[str, str] = self.get_step_options(step)
         options.update(mapping)
-        self.force_step_update_params(step, entry_options_map=options)
+        update = AbstractElnEntryUpdateCriteria(step.eln_entry.entry_type)
+        update.entry_options_map = options
+        self.force_step_update(step, update)
 
     def initialize_step(self, step: Step) -> None:
         """
@@ -1575,7 +1436,9 @@ class ExperimentHandler:
         # Avoid unnecessary calls if the step is already initialized.
         step: ElnEntryStep = self.__to_eln_step(step)
         if step.eln_entry.template_item_fulfilled_timestamp is None:
-            self.force_step_update_params(step, template_item_fulfilled_timestamp=TimeUtil.now_in_millis())
+            update = AbstractElnEntryUpdateCriteria(step.eln_entry.entry_type)
+            update.template_item_fulfilled_timestamp = TimeUtil.now_in_millis()
+            self.force_step_update(step, update)
 
     def uninitialize_step(self, step: Step) -> None:
         """
@@ -1593,7 +1456,9 @@ class ExperimentHandler:
         # Avoid unnecessary calls if the step is already uninitialized.
         step: ElnEntryStep = self.__to_eln_step(step)
         if step.eln_entry.template_item_fulfilled_timestamp is not None:
-            self.force_step_update_params(step, clear_template_item_fulfilled_timestamp=True)
+            update = AbstractElnEntryUpdateCriteria(step.eln_entry.entry_type)
+            update.clear_template_item_fulfilled_timestamp = True
+            self.force_step_update(step, update)
 
     def complete_step(self, step: Step) -> None:
         """
@@ -1650,7 +1515,9 @@ class ExperimentHandler:
         """
         step = self.__to_eln_step(step)
         if step.eln_entry.entry_status in self._ENTRY_LOCKED_STATUSES:
-            self.force_step_update_params(step, entry_status=ExperimentEntryStatus.Disabled)
+            update = AbstractElnEntryUpdateCriteria(step.eln_entry.entry_type)
+            update.entry_status = ExperimentEntryStatus.Disabled
+            self.force_step_update(step, update)
 
     def step_is_submitted(self, step: Step) -> bool:
         """
@@ -1728,28 +1595,33 @@ class ExperimentHandler:
         self.add_tab_to_cache(tab)
         return tab
 
-    def get_tab(self, tab_name: str | int, exception_on_none: bool = True) -> ElnExperimentTab:
+    def get_tab(self, tab: str | int, exception_on_none: bool = True) -> ElnExperimentTab:
         """
         Return the tab with the input name.
 
         If no tab functions have been called before and a tab is being searched for by name, queries for the
         list of tabs in the experiment and caches them.
 
-        :param tab_name: The name or ID of the tab to get.
+        :param tab: The name or order of the tab to get. The order is 1-indexed.
         :param exception_on_none: If True, raises an exception if no tab with the given name exists.
         :return: The tab with the input name, or None if no such tab exists.
         """
-        if tab_name not in self._tabs_by_name and tab_name not in self._tabs_by_id:
-            self.get_all_tabs()
-        if isinstance(tab_name, str):
-            tab = self._tabs_by_name.get(tab_name)
+        if isinstance(tab, str):
+            if tab not in self._tabs_by_name:
+                self.get_all_tabs()
+            eln_tab = self._tabs_by_name.get(tab)
+        elif isinstance(tab, int):
+            # The given integer is expected to be 1-indexed, but we read from the list with a 0-index.
+            tab -= 1
+            tabs = self.get_all_tabs()
+            eln_tab = tabs[tab] if len(tabs) > tab else None
         else:
-            tab = self._tabs_by_id.get(tab_name)
-        if tab is None and exception_on_none:
-            raise SapioException(f"No tab with the name\\ID \"{tab_name}\" exists in this experiment.")
-        return tab
+            raise SapioException(f"Tab must be a string or an integer, not {type(tab)}.")
+        if eln_tab is None and exception_on_none:
+            raise SapioException(f"No tab with the name\\order \"{tab}\" exists in this experiment.")
+        return eln_tab
 
-    def get_steps_in_tab(self, tab: TabIdentifier | str, data_type: DataTypeIdentifier | None = None) \
+    def get_steps_in_tab(self, tab: Tab, data_type: DataTypeIdentifier | None = None) \
             -> list[ElnEntryStep]:
         """
         Get all the steps in the input tab sorted in order of appearance.
@@ -1760,8 +1632,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 to get the steps of. This can be either an ElnExperimentTab object, or the name or ID of
-            the tab.
+        :param tab: The tab to get the steps of. This can be the tab's order, name, or the tab object itself.
+            The order is 1-indexed.
         :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.
         """
@@ -1772,7 +1644,29 @@ class ExperimentHandler:
                 steps.append(step)
         return steps
 
-    def get_next_entry_order_in_tab(self, tab: TabIdentifier | str) -> int:
+    def get_tab_for_step(self, step: Step) -> ElnExperimentTab:
+        """
+        Get the tab that a particular step is located in.
+
+        If no tab functions have been called before and a tab is being searched for by name, queries for the
+        list of tabs in the experiment and caches them.
+
+        If the steps in the experiment have not been queried before, 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 tab that the input step is located in.
+        """
+        step = self.__to_eln_step(step)
+        tab_id = step.eln_entry.notebook_experiment_tab_id
+        if tab_id not in self._tabs_by_id:
+            self.get_all_tabs()
+        return self._tabs_by_id.get(tab_id)
+
+    def get_next_entry_order_in_tab(self, tab: Tab) -> int:
         """
         Get the next available order for a new entry in the input tab.
 
@@ -1782,8 +1676,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 to get the next entry order of. This can be either an ElnExperimentTab object, or the name
-            or ID of the tab.
+        :param tab: The tab to get the steps of. This can be the tab's order, name, or the tab object itself.
+            The order is 1-indexed.
         :return: The next available order for a new entry in the input tab.
         """
         steps = self.get_steps_in_tab(tab)
@@ -1863,16 +1757,14 @@ class ExperimentHandler:
             return self.add_entry_to_caches(step)
         return step
 
-    def __to_eln_tab(self, tab: TabIdentifier | str) -> ElnExperimentTab:
+    def __to_eln_tab(self, tab: Tab) -> ElnExperimentTab:
         """
-        Convert a variable that could be either a string or an ElnExperimentTab to just an ElnExperimentTab.
+        Convert a variable that could be either a tab name, tab order, or ElnExperimentTab to just a tab object.
         This will query and cache the tabs for the experiment if the input tab is a name and the tabs have not been
         cached before.
 
         :return: The input tab as an ElnExperimentTab.
         """
-        if isinstance(tab, str):
+        if not isinstance(tab, ElnExperimentTab):
             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-2025.4.17a486 → sapiopycommons-2025.4.17a487}/src/sapiopycommons/general/aliases.py

@@ -38,8 +38,6 @@ ExperimentIdentifier: TypeAlias = ElnExperimentProtocol | ElnExperiment | int
 ID."""
 ExperimentEntryIdentifier: TypeAlias = ElnEntryStep | ExperimentEntry | int
 """An ExperimentEntryIdentifier is either an ELN entry step, experiment entry, or an integer for the entry's ID."""
-TabIdentifier: TypeAlias = int | ElnExperimentTab
-"""A TabIdentifier is either an integer for the tab's ID or an ElnExperimentTab object."""
 FieldMap: TypeAlias = dict[str, FieldValue]
 """A field map is simply a dict of data field names to values. The purpose of aliasing this is to help distinguish
 any random dict in a webhook from one which is explicitly used for record fields."""