sapiopycommons 2025.4.9a150__py3-none-any.whl → 2025.4.9a476__py3-none-any.whl

sapiopycommons/general/directive_util.py

@@ -0,0 +1,86 @@
+from typing import Iterable, cast
+
+from sapiopylib.rest.User import SapioUser
+from sapiopylib.rest.pojo.CustomReport import CustomReportCriteria, CustomReport
+from sapiopylib.rest.pojo.webhook.WebhookDirective import HomePageDirective, FormDirective, TableDirective, \
+    CustomReportDirective, ElnExperimentDirective, ExperimentEntryDirective
+
+from sapiopycommons.general.aliases import SapioRecord, AliasUtil, ExperimentIdentifier, ExperimentEntryIdentifier, \
+    UserIdentifier
+from sapiopycommons.general.custom_report_util import CustomReportUtil
+
+
+# FR-47392: Create a DirectiveUtil class to simplify the creation of directives.
+class DirectiveUtil:
+    """
+    DirectiveUtil is a class for creating webhook directives. The utility functions reduce the provided variables
+    down to the exact type that the directives require, removing the need for the caller to handle the conversion.
+    """
+    user: SapioUser
+
+    def __init__(self, context: UserIdentifier):
+        """
+        :param context: The current webhook context or a user object to send requests from.
+        """
+        self.user = AliasUtil.to_sapio_user(context)
+
+    @staticmethod
+    def homepage() -> HomePageDirective:
+        """
+        :return: A directive that sends the user back to their home page.
+        """
+        return HomePageDirective()
+
+    @staticmethod
+    def record_form(record: SapioRecord) -> FormDirective:
+        """
+        :param record: A record in the system.
+        :return: A directive that sends the user to a specific data record form.
+        """
+        return FormDirective(AliasUtil.to_data_record(record))
+
+    @staticmethod
+    def record_table(records: Iterable[SapioRecord]) -> TableDirective:
+        """
+        :param records: A list of records in the system.
+        :return: A directive that sends the user to a table of data records.
+        """
+        return TableDirective(AliasUtil.to_data_records(records))
+
+    @staticmethod
+    def record_adaptive(records: Iterable[SapioRecord]) -> TableDirective | FormDirective:
+        """
+        :param records: A list of records in the system.
+        :return: A directive that sends the user to a table of data records if there are multiple records,
+            or a directive that sends the user to a specific data record form if there is only one record.
+        """
+        records: list[SapioRecord] = list(records)
+        if len(records) == 1:
+            return DirectiveUtil.record_form(records[0])
+        return DirectiveUtil.record_table(records)
+
+    def custom_report(self, report: CustomReport | CustomReportCriteria | str) -> CustomReportDirective:
+        """
+        :param report: A custom report, the criteria for a custom report, or the name of a system report.
+        :return: A directive that sends the user to the results of the provided custom report.
+        """
+        if isinstance(report, str):
+            report: CustomReport = CustomReportUtil.get_system_report_criteria(self.user, report)
+        return CustomReportDirective(cast(CustomReport, report))
+
+    @staticmethod
+    def eln_experiment(experiment: ExperimentIdentifier) -> ElnExperimentDirective:
+        """
+        :param experiment: An identifier for an experiment.
+        :return: A directive that sends the user to the ELN experiment.
+        """
+        return ElnExperimentDirective(AliasUtil.to_notebook_id(experiment))
+
+    @staticmethod
+    def eln_entry(experiment: ExperimentIdentifier, entry: ExperimentEntryIdentifier) -> ExperimentEntryDirective:
+        """
+        :param experiment: An identifier for an experiment.
+        :param entry: An identifier for an entry in the experiment.
+        :return: A directive that sends the user to the provided experiment entry within its ELN experiment.
+        """
+        return ExperimentEntryDirective(AliasUtil.to_notebook_id(experiment), AliasUtil.to_entry_id(entry))

sapiopycommons/general/exceptions.py

@@ -1,3 +1,20 @@
+from enum import Enum
+
+
+class MessageDisplayType(Enum):
+    """
+    An enum representing the different ways in which a message can be displayed to the user.
+    """
+    TOASTER_SUCCESS = 0
+    TOASTER_INFO = 1
+    TOASTER_WARNING = 2
+    TOASTER_ERROR = 3
+    OK_DIALOG = 4
+    DISPLAY_INFO = 5
+    DISPLAY_WARNING = 6
+    DISPLAY_ERROR = 7
+
+
 # FR-46064 - Initial port of PyWebhookUtils to sapiopycommons.
 class SapioException(Exception):
     """
@@ -29,7 +46,29 @@ class SapioDialogTimeoutException(SapioException):
     pass
 
 
-class SapioUserErrorException(SapioException):
+class DisplayableException(SapioException):
+    """
+    A generic exception that promises to return a user-friendly message explaining the error that should be displayed to
+    the user. Note that it is up to whichever class that catches this exception to actually display the message.
+    """
+    msg: str
+    display_type: MessageDisplayType | None
+    title: str | None
+
+    def __init__(self, msg: str, display_type: MessageDisplayType | None = None, title: str | None = None):
+        """
+        :param msg: The message that should be displayed to the user.
+        :param display_type: The manner in which the message should be displayed. If None, then the display type should
+            be controlled by the class that catches this exception.
+        :param title: If the display type is able to have a title, this is the title that will be displayed. If None,
+            then the title should be controlled by the class that catches this exception.
+        """
+        self.msg = msg
+        self.display_type = display_type
+        self.title = title
+
+
+class SapioUserErrorException(DisplayableException):
     """
     An exception caused by user error (e.g. user provided a CSV when an XLSX was expected), which promises to return a
     user-friendly message explaining the error that should be displayed to the user.
@@ -39,7 +78,7 @@ class SapioUserErrorException(SapioException):
     pass
 
 
-class SapioCriticalErrorException(SapioException):
+class SapioCriticalErrorException(DisplayableException):
     """
     A critical exception caused by user error, which promises to return a user-friendly message explaining the error
     that should be displayed to the user.

sapiopycommons/general/popup_util.py

@@ -311,7 +311,7 @@ class PopupUtil:
             raise SapioException("Multiple data type names encountered in records list for record table popup.")
         data_type: str = data_types.pop()
         # Get the field maps from the records.
-        field_map_list: list[FieldMap] = AliasUtil.to_field_map_lists(records)
+        field_map_list: list[FieldMap] = AliasUtil.to_field_map_list(records)
         # Get the field definitions of the data type.
         type_man = DataMgmtServer.get_data_type_manager(context.user)
         type_def: DataTypeDefinition = type_man.get_data_type_definition(data_type)
@@ -366,7 +366,7 @@ class PopupUtil:
             raise SapioException("Multiple data type names encountered in records list for record table popup.")
         data_type: str = data_types.pop()
         # Get the field maps from the records.
-        field_map_list: list[FieldMap] = AliasUtil.to_field_map_lists(records)
+        field_map_list: list[FieldMap] = AliasUtil.to_field_map_list(records)
         # Get the field definitions of the data type.
         type_man = DataMgmtServer.get_data_type_manager(context.user)
         type_def: DataTypeDefinition = type_man.get_data_type_definition(data_type)

sapiopycommons/multimodal/multimodal.py

@@ -6,6 +6,7 @@ from weakref import WeakValueDictionary
 
 from databind.json import dumps, loads
 from sapiopylib.rest.User import SapioUser
+from sapiopylib.rest.pojo.DataRecord import DataRecord
 
 from sapiopycommons.general.exceptions import SapioException
 from sapiopycommons.multimodal.multimodal_data import *

sapiopycommons/processtracking/custom_workflow_handler.py

@@ -3,12 +3,13 @@ from typing import Iterable
 from sapiopylib.rest.User import SapioUser
 from sapiopylib.rest.pojo.CustomReport import CustomReportCriteria
 from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
+from sapiopylib.rest.utils.recordmodel.PyRecordModel import PyRecordModel
 from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedType
 
+from sapiopycommons.customreport.auto_pagers import CustomReportDictAutoPager, CustomReportRecordAutoPager
 from sapiopycommons.customreport.custom_report_builder import CustomReportBuilder
 from sapiopycommons.datatype.data_fields import ProcessQueueItemFields, SystemFields, ProcessWorkflowTrackingFields
 from sapiopycommons.general.aliases import UserIdentifier, AliasUtil, SapioRecord
-from sapiopycommons.general.custom_report_util import CustomReportUtil
 from sapiopycommons.general.exceptions import SapioException
 from sapiopycommons.general.time_util import TimeUtil
 from sapiopycommons.recordmodel.record_handler import RecordHandler
@@ -104,24 +105,28 @@ class QueueItemHandler:
         """
         self.user = AliasUtil.to_sapio_user(context)
         self.rec_handler = RecordHandler(self.user)
-        if isinstance(context, SapioWebhookContext):
+        # PR-47565: Only initialize a ProcessQueueContext if the given context object has context_data.
+        if isinstance(context, SapioWebhookContext) and context.context_data:
             self.context = ProcessQueueContext(context)
         else:
             self.context = None
 
-    def get_process_queue_items_from_context(self, wrapper: type[WrappedType],
+    # CR-47491: Support providing a data type name string to receive PyRecordModels instead of requiring a WrapperType.
+    def get_process_queue_items_from_context(self, wrapper: type[WrappedType] | str,
                                              context: SapioWebhookContext | ProcessQueueContext | None = None) \
-            -> list[WrappedType]:
+            -> list[WrappedType] | list[PyRecordModel]:
         """
         When you launch records from a custom process queue, the process queue items related to the selected records
         are provided as record IDs to the process queue context. Using these record IDs, query for the queue item
         records and wrap them as record models.
 
-        :param wrapper: The record model wrapper for the process queue items.
+        :param wrapper: The record model wrapper or data type name for the process queue items.
         :param context: If this handler was not initialized with a context object, or you wish to retrieve
             data from a different context object than the initializing context, then provide the context to retrieve the
             record IDs from.
         :return: The process queue items corresponding to the record IDs from the context wrapped as record models.
+            If a data type name was used instead of a model wrapper, then the returned records will be PyRecordModels
+            instead of WrappedRecordModels.
         """
         if context is None and self.context is not None:
             record_ids: list[int] = self.context.process_queue_item_record_ids
@@ -175,46 +180,52 @@ class QueueItemHandler:
                 ret_val[queue_item] = record
         return ret_val
 
-    def get_queue_items_from_report(self, wrapper: type[WrappedType], criteria: QueueItemReportCriteria) \
-            -> list[WrappedType]:
+    def get_queue_items_from_report(self, wrapper: type[WrappedType] | None, criteria: QueueItemReportCriteria) \
+            -> list[WrappedType] | list[PyRecordModel]:
         """
         Run a custom report that retrieves every queue item in the system for the given search criteria.
 
-        :param wrapper: The record model wrapper for the process queue items.
+        :param wrapper: The record model wrapper for the process queue items. If not provided, the returned records will
+            be PyRecordModels instead of WrappedRecordModels.
         :param criteria: The search criteria to query for queue items with.
         :return: A list of every queue item in the system that matches the search criteria.
         """
         report = self.build_queue_item_report(criteria)
-        return self.rec_handler.query_models_by_report(wrapper, report)
+        dt: type[WrappedType] | str = wrapper if wrapper else ProcessQueueItemFields.DATA_TYPE_NAME
+        return CustomReportRecordAutoPager(self.user, report, dt).get_all_at_once()
 
-    def get_records_from_item_report(self, wrapper: type[WrappedType],
-                                     criteria: QueueItemReportCriteria = QueueItemReportCriteria()) -> list[WrappedType]:
+    def get_records_from_item_report(self, wrapper: type[WrappedType] | str,
+                                     criteria: QueueItemReportCriteria = QueueItemReportCriteria()) \
+            -> list[WrappedType] | list[PyRecordModel]:
         """
         Run a custom report that retrieves for queue items that match the given search criteria, then query for the
         data records that those queue items refer to.
 
-        :param wrapper: The record model wrapper for the records being queried for.
+        :param wrapper: The record model wrapper or data type name for the records being queried for.
         :param criteria: Additional search criteria to filter the results. This function forces the data_type_names
             parameter of the criteria to match the data type of the given record model wrapper.
         :return: A list of all records related to the queue items in the system that match the search criteria.
+            If a data type name was used instead of a model wrapper, then the returned records will be PyRecordModels
+            instead of WrappedRecordModels.
         """
         # Don't try to query for process queue items that don't match the data type of this wrapper.
-        criteria.data_type_names = [wrapper.get_wrapper_data_type_name()]
+        criteria.data_type_names = [AliasUtil.to_data_type_name(wrapper)]
         criteria.not_data_type_names = None
         report = self.build_queue_item_report(criteria)
         record_ids: list[int] = [x[ProcessQueueItemFields.DATA_RECORD_ID__FIELD.field_name]
-                                 for x in CustomReportUtil.run_custom_report(self.user, report)]
+                                 for x in CustomReportDictAutoPager(self.user, report)]
         return self.rec_handler.query_models_by_id(wrapper, record_ids)
 
-    def get_queue_items_for_records(self, records: Iterable[SapioRecord], wrapper: type[WrappedType],
+    def get_queue_items_for_records(self, records: Iterable[SapioRecord], wrapper: type[WrappedType] | None = None,
                                     criteria: QueueItemReportCriteria = QueueItemReportCriteria()) \
-            -> dict[SapioRecord, list[WrappedType]]:
+            -> dict[SapioRecord, list[WrappedType] | list[PyRecordModel]]:
         """
         Given a list of records, query the system for every process queue item that refers to those records and matches
         the provided search criteria.
 
         :param records: The queued records to query for the process queue items of.
-        :param wrapper: The record model wrapper for the returned process queue item records.
+        :param wrapper: The record model wrapper for the returned process queue item records. If not provided, the
+            returned records will be PyRecordModels instead of WrappedRecordModels.
         :param criteria: Additional search criteria to filter the results. This function forces the data_record_ids and
             data_type_names parameters on the criteria to match the given records.
         :return: A dictionary mapping the input records to a list of the process queue items that refer to them. If a
@@ -226,40 +237,43 @@ class QueueItemHandler:
         criteria.not_data_record_ids = None
         criteria.data_type_names = AliasUtil.to_data_type_names(records)
         criteria.not_data_type_names = None
-        items: list[WrappedType] = self.get_queue_items_from_report(wrapper, criteria)
+        items: list[WrappedType] | list[PyRecordModel] = self.get_queue_items_from_report(wrapper, criteria)
         return self.map_records_to_queue_items(records, items)
 
-    def get_records_for_queue_items(self, queue_items: Iterable[SapioRecord], wrapper: type[WrappedType]) \
-            -> dict[SapioRecord, WrappedType]:
+    def get_records_for_queue_items(self, queue_items: Iterable[SapioRecord], wrapper: type[WrappedType] | str) \
+            -> dict[SapioRecord, WrappedType | PyRecordModel]:
         """
         Given a list of process queue items, query the system for the records that those queue items refer to.
 
         :param queue_items: The process queue items to query for the referenced records of.
-        :param wrapper: The record model wrapper for the records being queried.
-        :return: A dictionary mapping the input process queue items to the record tht they refer to.
+        :param wrapper: The record model wrapper or data type name for the records being queried.
+        :return: A dictionary mapping the input process queue items to the record tht they refer to. If a data type
+            name was used instead of a model wrapper, then the returned records will be PyRecordModels instead of
+            WrappedRecordModels.
         """
         record_ids: set[int] = {x.get_field_value(ProcessQueueItemFields.DATA_RECORD_ID__FIELD) for x in queue_items}
-        records: list[WrappedType] = self.rec_handler.query_models_by_id(wrapper, record_ids)
+        records: list[WrappedType] | list[PyRecordModel] = self.rec_handler.query_models_by_id(wrapper, record_ids)
         return self.map_queue_items_to_records(queue_items, records)
 
     def queue_records_for_process(self, records: Iterable[SapioRecord], process: str, step: str,
-                                  wrapper: type[WrappedType]) -> dict[SapioRecord, WrappedType]:
+                                  wrapper: type[WrappedType] | None = None) -> dict[SapioRecord, WrappedType | PyRecordModel]:
         """
         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.
 
         :param records: The records to create process queue items for.
-        :param wrapper: The record model wrapper for the process queue items being created.
         :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
             Process Workflow record corresponding to the step you want to assign these records to. For steps that
             launch an experiment, this is the name of the template that will be launched. For the other types of custom
             process steps, this is the "Workflow Name" as defined in the process manager config.
+        :param wrapper: The record model wrapper for the process queue items being created. If not provided, the
+            returned records will be PyRecordModels instead of WrappedRecordModels.
         :return: A dictionary mapping each input record to the newly created process queue item for that record.
         """
         ret_val: dict[SapioRecord, WrappedType] = {}
         for record in records:
-            item = self.rec_handler.add_model(wrapper)
+            item = self.rec_handler.add_model(wrapper if wrapper else ProcessQueueItemFields.DATA_TYPE_NAME)
             item.set_field_values({
                 ProcessQueueItemFields.PROCESS_HEADER_NAME__FIELD.field_name: process,
                 ProcessQueueItemFields.WORKFLOW_HEADER_NAME__FIELD.field_name: step,
@@ -271,16 +285,17 @@ class QueueItemHandler:
             ret_val[record] = item
         return ret_val
 
-    def dequeue_records_for_process(self, records: Iterable[SapioRecord], wrapper: type[WrappedType],
+    def dequeue_records_for_process(self, records: Iterable[SapioRecord], wrapper: type[WrappedType] | None = None,
                                     criteria: QueueItemReportCriteria = QueueItemReportCriteria()) \
-            -> dict[SapioRecord, list[WrappedType]]:
+            -> dict[SapioRecord, list[WrappedType] | list[PyRecordModel]]:
         """
         Given a list of records, locate the process queue items that refer to them and that match the given search
         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.
 
         :param records: The records to remove from the queue.
-        :param wrapper: The record model wrapper for the process queue items being updated.
+        :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.
         :param criteria: Additional search criteria to filter the results. This function forces the show_in_queue
             parameter on the criteria to True.
         :return: A dictionary mapping each input record to the queue item records that refer to that record and were
@@ -289,7 +304,8 @@ class QueueItemHandler:
         """
         # Only locate queue items that are currently visible in the queue.
         criteria.shown_in_queue = True
-        dequeue: dict[SapioRecord, list[WrappedType]] = self.get_queue_items_for_records(records, wrapper, criteria)
+        dequeue: dict[SapioRecord, list[WrappedType] | list[PyRecordModel]]
+        dequeue = self.get_queue_items_for_records(records, wrapper, criteria)
         for record, items in dequeue.items():
             for item in items:
                 item.set_field_value(ProcessQueueItemFields.SHOW_IN_QUEUE__FIELD.field_name, False)