sapiopycommons 2024.10.1a337__tar.gz → 2024.10.4a339__tar.gz

{sapiopycommons-2024.10.1a337 → sapiopycommons-2024.10.4a339}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sapiopycommons
-Version: 2024.10.1a337
+Version: 2024.10.4a339
 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-2024.10.1a337 → sapiopycommons-2024.10.4a339}/pyproject.toml

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

{sapiopycommons-2024.10.1a337 → sapiopycommons-2024.10.4a339}/src/sapiopycommons/callbacks/callback_util.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import io
 from weakref import WeakValueDictionary
 
+from requests import ReadTimeout
 from sapiopylib.rest.ClientCallbackService import ClientCallback
 from sapiopylib.rest.DataMgmtService import DataMgmtServer
 from sapiopylib.rest.User import SapioUser
@@ -27,7 +28,8 @@ from sapiopycommons.files.file_util import FileUtil
 from sapiopycommons.general.aliases import FieldMap, SapioRecord, AliasUtil, RecordIdentifier, FieldValue, \
     UserIdentifier
 from sapiopycommons.general.custom_report_util import CustomReportUtil
-from sapiopycommons.general.exceptions import SapioUserCancelledException, SapioException, SapioUserErrorException
+from sapiopycommons.general.exceptions import SapioUserCancelledException, SapioException, SapioUserErrorException, \
+    SapioDialogTimeoutException
 from sapiopycommons.recordmodel.record_handler import RecordHandler
 
 
@@ -35,6 +37,8 @@ class CallbackUtil:
     user: SapioUser
     callback: ClientCallback
     dt_cache: DataTypeCacheManager
+    _original_timeout: int
+    timeout_seconds: int
     width_pixels: int | None
     width_percent: float | None
 
@@ -64,6 +68,8 @@ class CallbackUtil:
         self.user = AliasUtil.to_sapio_user(context)
         self.callback = DataMgmtServer.get_client_callback(self.user)
         self.dt_cache = DataTypeCacheManager(self.user)
+        self._original_timeout = self.user.timeout_seconds
+        self.timeout_seconds = self.user.timeout_seconds
         self.width_pixels = None
         self.width_percent = None
 
@@ -80,6 +86,17 @@ class CallbackUtil:
         self.width_pixels = width_pixels
         self.width_percent = width_percent
 
+    def set_dialog_timeout(self, timeout: int):
+        """
+        Alter the timeout time used for callback requests that create dialogs for the user to interact with. By default,
+        a CallbackUtil will use the timeout time of the SapioUser provided to it. By altering this, a different timeout
+        time is used.
+
+        :param timeout: The number of seconds that must elapse before a SapioDialogTimeoutException is thrown by
+            any callback that creates a dialog for the user to interact with.
+        """
+        self.timeout_seconds = timeout
+
     def toaster_popup(self, message: str, title: str = "", popup_type: PopupType = PopupType.Info) -> None:
         """
         Display a toaster popup in the bottom right corner of the user's screen.
@@ -134,7 +151,13 @@ class CallbackUtil:
         """
         request = OptionDialogRequest(title, msg, options, default_option, user_can_cancel,
                                       width_in_pixels=self.width_pixels, width_percentage=self.width_percent)
-        response: int | None = self.callback.show_option_dialog(request)
+        try:
+            self.user.timeout_seconds = self.timeout_seconds
+            response: int | None = self.callback.show_option_dialog(request)
+        except ReadTimeout:
+            raise SapioDialogTimeoutException()
+        finally:
+            self.user.timeout_seconds = self._original_timeout
         if response is None:
             raise SapioUserCancelledException()
         return options[response]
@@ -187,7 +210,13 @@ class CallbackUtil:
         """
         request = ListDialogRequest(title, multi_select, options, preselected_values,
                                     width_in_pixels=self.width_pixels, width_percentage=self.width_percent)
-        response: list[str] | None = self.callback.show_list_dialog(request)
+        try:
+            self.user.timeout_seconds = self.timeout_seconds
+            response: list[str] | None = self.callback.show_list_dialog(request)
+        except ReadTimeout:
+            raise SapioDialogTimeoutException()
+        finally:
+            self.user.timeout_seconds = self._original_timeout
         if response is None:
             raise SapioUserCancelledException()
         return response
@@ -239,7 +268,13 @@ class CallbackUtil:
 
         request = FormEntryDialogRequest(title, msg, builder.get_temporary_data_type(), values,
                                          width_in_pixels=self.width_pixels, width_percentage=self.width_percent)
-        response: FieldMap | None = self.callback.show_form_entry_dialog(request)
+        try:
+            self.user.timeout_seconds = self.timeout_seconds
+            response: FieldMap | None = self.callback.show_form_entry_dialog(request)
+        except ReadTimeout:
+            raise SapioDialogTimeoutException()
+        finally:
+            self.user.timeout_seconds = self._original_timeout
         if response is None:
             raise SapioUserCancelledException()
         return response
@@ -297,7 +332,13 @@ class CallbackUtil:
 
         request = FormEntryDialogRequest(title, msg, builder.get_temporary_data_type(), values,
                                          width_in_pixels=self.width_pixels, width_percentage=self.width_percent)
-        response: FieldMap | None = self.callback.show_form_entry_dialog(request)
+        try:
+            self.user.timeout_seconds = self.timeout_seconds
+            response: FieldMap | None = self.callback.show_form_entry_dialog(request)
+        except ReadTimeout:
+            raise SapioDialogTimeoutException()
+        finally:
+            self.user.timeout_seconds = self._original_timeout
         if response is None:
             raise SapioUserCancelledException()
         return response
@@ -313,7 +354,13 @@ class CallbackUtil:
         """
         request = InputDialogCriteria(title, msg, field,
                                       width_in_pixels=self.width_pixels, width_percentage=self.width_percent)
-        response: FieldValue | None = self.callback.show_input_dialog(request)
+        try:
+            self.user.timeout_seconds = self.timeout_seconds
+            response: FieldValue | None = self.callback.show_input_dialog(request)
+        except ReadTimeout:
+            raise SapioDialogTimeoutException()
+        finally:
+            self.user.timeout_seconds = self._original_timeout
         if response is None:
             raise SapioUserCancelledException()
         return response
@@ -432,7 +479,13 @@ class CallbackUtil:
         request = TableEntryDialogRequest(title, msg, builder.get_temporary_data_type(), values,
                                           record_image_data_list=image_data, group_by_field=group_by,
                                           width_in_pixels=self.width_pixels, width_percentage=self.width_percent)
-        response: list[FieldMap] | None = self.callback.show_table_entry_dialog(request)
+        try:
+            self.user.timeout_seconds = self.timeout_seconds
+            response: list[FieldMap] | None = self.callback.show_table_entry_dialog(request)
+        except ReadTimeout:
+            raise SapioDialogTimeoutException()
+        finally:
+            self.user.timeout_seconds = self._original_timeout
         if response is None:
             raise SapioUserCancelledException()
         return response
@@ -496,7 +549,13 @@ class CallbackUtil:
         request = TableEntryDialogRequest(title, msg, builder.get_temporary_data_type(), field_map_list,
                                           record_image_data_list=image_data, group_by_field=group_by,
                                           width_in_pixels=self.width_pixels, width_percentage=self.width_percent)
-        response: list[FieldMap] | None = self.callback.show_table_entry_dialog(request)
+        try:
+            self.user.timeout_seconds = self.timeout_seconds
+            response: list[FieldMap] | None = self.callback.show_table_entry_dialog(request)
+        except ReadTimeout:
+            raise SapioDialogTimeoutException()
+        finally:
+            self.user.timeout_seconds = self._original_timeout
         if response is None:
             raise SapioUserCancelledException()
         return response
@@ -654,7 +713,13 @@ class CallbackUtil:
 
         request = TableEntryDialogRequest(title, msg, builder.get_temporary_data_type(), values,
                                           width_in_pixels=self.width_pixels, width_percentage=self.width_percent)
-        response: list[FieldMap] | None = self.callback.show_table_entry_dialog(request)
+        try:
+            self.user.timeout_seconds = self.timeout_seconds
+            response: list[FieldMap] | None = self.callback.show_table_entry_dialog(request)
+        except ReadTimeout:
+            raise SapioDialogTimeoutException()
+        finally:
+            self.user.timeout_seconds = self._original_timeout
         if response is None:
             raise SapioUserCancelledException()
         return response
@@ -704,7 +769,13 @@ class CallbackUtil:
 
         request = DataRecordDialogRequest(title, record, layout, minimized, access_level, plugin_path_list,
                                           width_in_pixels=self.width_pixels, width_percentage=self.width_percent)
-        response: bool = self.callback.data_record_form_view_dialog(request)
+        try:
+            self.user.timeout_seconds = self.timeout_seconds
+            response: bool = self.callback.data_record_form_view_dialog(request)
+        except ReadTimeout:
+            raise SapioDialogTimeoutException()
+        finally:
+            self.user.timeout_seconds = self._original_timeout
         if not response:
             raise SapioUserCancelledException()
     
@@ -744,7 +815,13 @@ class CallbackUtil:
 
         request = TempTableSelectionRequest(builder.get_temporary_data_type(), msg, values,
                                             multi_select=multi_select)
-        response: list[FieldMap] | None = self.callback.show_temp_table_selection_dialog(request)
+        try:
+            self.user.timeout_seconds = self.timeout_seconds
+            response: list[FieldMap] | None = self.callback.show_temp_table_selection_dialog(request)
+        except ReadTimeout:
+            raise SapioDialogTimeoutException()
+        finally:
+            self.user.timeout_seconds = self._original_timeout
         if response is None:
             raise SapioUserCancelledException()
         return response
@@ -796,7 +873,13 @@ class CallbackUtil:
 
         request = TempTableSelectionRequest(builder.get_temporary_data_type(), msg, field_map_list,
                                             multi_select=multi_select)
-        response: list[FieldMap] | None = self.callback.show_temp_table_selection_dialog(request)
+        try:
+            self.user.timeout_seconds = self.timeout_seconds
+            response: list[FieldMap] | None = self.callback.show_temp_table_selection_dialog(request)
+        except ReadTimeout:
+            raise SapioDialogTimeoutException()
+        finally:
+            self.user.timeout_seconds = self._original_timeout
         if response is None:
             raise SapioUserCancelledException()
         # Map the field maps in the response back to the record they come from, returning the chosen record instead of
@@ -872,7 +955,13 @@ class CallbackUtil:
         request = InputSelectionRequest(data_type, msg, search_types, only_key_fields, record_blacklist,
                                         record_whitelist, preselected_records, custom_search, scan_criteria,
                                         multi_select)
-        response: list[DataRecord] | None = self.callback.show_input_selection_dialog(request)
+        try:
+            self.user.timeout_seconds = self.timeout_seconds
+            response: list[DataRecord] | None = self.callback.show_input_selection_dialog(request)
+        except ReadTimeout:
+            raise SapioDialogTimeoutException()
+        finally:
+            self.user.timeout_seconds = self._original_timeout
         if response is None:
             raise SapioUserCancelledException()
         return RecordHandler(self.user).wrap_models(response, wrapper_type)
@@ -898,7 +987,13 @@ class CallbackUtil:
             temp_dt = builder.get_temporary_data_type()
         request = ESigningRequestPojo(title, msg, show_comment, temp_dt,
                                       width_in_pixels=self.width_pixels, width_percentage=self.width_percent)
-        response: ESigningResponsePojo | None = self.callback.show_esign_dialog(request)
+        try:
+            self.user.timeout_seconds = self.timeout_seconds
+            response: ESigningResponsePojo | None = self.callback.show_esign_dialog(request)
+        except ReadTimeout:
+            raise SapioDialogTimeoutException()
+        finally:
+            self.user.timeout_seconds = self._original_timeout
         if response is None:
             raise SapioUserCancelledException()
         return response
@@ -929,7 +1024,13 @@ class CallbackUtil:
                 return sink.consume_data(chunk, io_obj)
 
             request = FilePromptRequest(title, show_image_editor, ",".join(exts), show_camera_button)
-            file_path: str | None = self.callback.show_file_dialog(request, do_consume)
+            try:
+                self.user.timeout_seconds = self.timeout_seconds
+                file_path: str | None = self.callback.show_file_dialog(request, do_consume)
+            except ReadTimeout:
+                raise SapioDialogTimeoutException()
+            finally:
+                self.user.timeout_seconds = self._original_timeout
         if file_path is None:
             raise SapioUserCancelledException()
 
@@ -954,7 +1055,13 @@ class CallbackUtil:
             exts: list[str] = []
 
         request = MultiFilePromptRequest(title, show_image_editor, ",".join(exts), show_camera_button)
-        file_paths: list[str] | None = self.callback.show_multi_file_dialog(request)
+        try:
+            self.user.timeout_seconds = self.timeout_seconds
+            file_paths: list[str] | None = self.callback.show_multi_file_dialog(request)
+        except ReadTimeout:
+            raise SapioDialogTimeoutException()
+        finally:
+            self.user.timeout_seconds = self._original_timeout
         if not file_paths:
             raise SapioUserCancelledException()
 

{sapiopycommons-2024.10.1a337 → sapiopycommons-2024.10.4a339}/src/sapiopycommons/general/exceptions.py

@@ -3,34 +3,47 @@ class SapioException(Exception):
     """
     A generic exception thrown by sapiopycommons methods. Typically caused by programmer error, but may also be from
     extremely edge case user errors. For expected user errors, use SapioUserErrorException.
+
+    CommonsWebhookHandler's default behavior for this and any other exception that doesn't extend SapioException is
+    to return a generic toaster message saying that an unexpected error has occurred.
     """
     pass
 
 
-# CommonsWebhookHandler catches this exception and returns "User Cancelled."
 class SapioUserCancelledException(SapioException):
     """
     An exception thrown when the user cancels a client callback.
+
+    CommonsWebhookHandler's default behavior is to simply end the webhook session with a true result without logging
+    the exception.
+    """
+    pass
+
+
+class SapioDialogTimeoutException(SapioException):
+    """
+    An exception thrown when the user leaves a client callback open for too long.
+
+    CommonsWebhookHandler's default behavior is to display an OK popup notifying the user that the dialog has timed out.
     """
     pass
 
 
-# CommonsWebhookHandler catches this exception and returns the text to the user as display text in a webhook result.
 class SapioUserErrorException(SapioException):
     """
     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. It is the responsibility of the
-    programmer to catch any such exceptions and return the value in e.args[0] as text for the user to see (such as
-    through the display text of a webhook result).
+    user-friendly message explaining the error that should be displayed to the user.
+
+    CommonsWebhookHandler's default behavior is to return the error message in a toaster popup.
     """
     pass
 
 
-# CommonsWebhookHandler catches this exception and returns the text in a display_error client callback.
 class SapioCriticalErrorException(SapioException):
     """
     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. It is the responsibility of the programmer to catch any such exceptions and
-    return the value in e.args[0] as text for the user to see (such as through a dialog form client callback request).
+    that should be displayed to the user.
+
+    CommonsWebhookHandler's default behavior is to return the error message in a display_error callback.
     """
     pass

{sapiopycommons-2024.10.1a337 → sapiopycommons-2024.10.4a339}/src/sapiopycommons/webhook/webhook_handlers.py

@@ -18,7 +18,7 @@ from sapiopylib.rest.utils.recordmodel.ancestry import RecordModelAncestorManage
 from sapiopycommons.callbacks.callback_util import CallbackUtil
 from sapiopycommons.eln.experiment_handler import ExperimentHandler
 from sapiopycommons.general.exceptions import SapioUserErrorException, SapioCriticalErrorException, \
-    SapioUserCancelledException, SapioException
+    SapioUserCancelledException, SapioException, SapioDialogTimeoutException
 from sapiopycommons.general.sapio_links import SapioNavigationLinker
 from sapiopycommons.recordmodel.record_handler import RecordHandler
 from sapiopycommons.rules.eln_rule_handler import ElnRuleHandler
@@ -90,6 +90,8 @@ class CommonsWebhookHandler(AbstractWebhookHandler):
             return self.handle_critical_error_exception(e)
         except SapioUserCancelledException as e:
             return self.handle_user_cancelled_exception(e)
+        except SapioDialogTimeoutException as e:
+            return self.handle_dialog_timeout_exception(e)
         except Exception as e:
             return self.handle_unexpected_exception(e)
 
@@ -111,11 +113,12 @@ class CommonsWebhookHandler(AbstractWebhookHandler):
     # the run method and into their own functions.
     def handle_user_error_exception(self, e: SapioUserErrorException) -> SapioWebhookResult:
         """
-        Handle a SapioUserErrorException. Default behavior returns the error message as display text in a webhook
-        result.
+        Handle a SapioUserErrorException.
+
+        Default behavior returns a false result and the error message as display text in a webhook result.
 
         :param e: The exception that was raised.
-        :return: A SapioWebhookResult reporting the exception to the user.
+        :return: A SapioWebhookResult to end the webhook session with.
         """
         result: SapioWebhookResult | None = self.handle_any_exception(e)
         if result is not None:
@@ -125,50 +128,84 @@ class CommonsWebhookHandler(AbstractWebhookHandler):
 
     def handle_critical_error_exception(self, e: SapioCriticalErrorException) -> SapioWebhookResult:
         """
-        Handle a SapioCriticalErrorException. Default behavior makes a display_error client callback.
+        Handle a SapioCriticalErrorException.
+
+        Default behavior makes a display_error client callback with the error message and returns a false result.
 
         :param e: The exception that was raised.
-        :return: A SapioWebhookResult reporting the exception to the user.
+        :return: A SapioWebhookResult to end the webhook session with.
         """
         result: SapioWebhookResult | None = self.handle_any_exception(e)
         if result is not None:
             return result
         self.log_error(traceback.format_exc())
+        # This error be thrown by endpoints that can't send client callbacks. If that happens, fall back onto sending
+        # display text instead.
         if self.can_send_client_callback():
-            DataMgmtServer.get_client_callback(self.user).display_error(e.args[0])
+            self.callback.display_error(e.args[0])
+        else:
+            return SapioWebhookResult(False, e.args[0])
         return SapioWebhookResult(False)
 
-    def handle_unexpected_exception(self, e: Exception) -> SapioWebhookResult:
+    def handle_user_cancelled_exception(self, e: SapioUserCancelledException) -> SapioWebhookResult:
         """
-        Handle a generic exception which isn't a SapioUserErrorException or SapioCriticalErrorException. Default
-        behavior returns a generic error message as display text informing the user to contact Sapio support.
+        Handle a SapioUserCancelledException.
+
+        Default behavior simply ends the webhook session with a true result (since the user cancelling is a valid
+        action).
 
         :param e: The exception that was raised.
-        :return: A SapioWebhookResult reporting the exception to the user.
+        :return: A SapioWebhookResult to end the webhook session with.
         """
         result: SapioWebhookResult | None = self.handle_any_exception(e)
         if result is not None:
             return result
-        msg: str = traceback.format_exc()
-        self.log_error(msg)
-        # FR-47079: Also log all unexpected exception messages to the webhook execution log within the platform.
-        self.log_error_to_webhook_execution_log(msg)
-        return SapioWebhookResult(False, display_text="Unexpected error occurred during webhook execution. "
-                                                      "Please contact Sapio support.")
+        return SapioWebhookResult(True)
 
-    def handle_user_cancelled_exception(self, e: SapioUserCancelledException) -> SapioWebhookResult:
+    def handle_dialog_timeout_exception(self, e: SapioDialogTimeoutException) -> SapioWebhookResult:
         """
-        Handle a SapioUserCancelledException. Default behavior returns "User Cancelled" as display text in a webhook
-        result.
+        Handle a SapioDialogTimeoutException.
+
+        Default behavior displays an OK popup notifying the user that the dialog has timed out and returns a false
+        webhook result.
 
         :param e: The exception that was raised.
-        :return: A SapioWebhookResult with display text saying the user cancelled the request.
+        :return: A SapioWebhookResult to end the webhook session with.
         """
         result: SapioWebhookResult | None = self.handle_any_exception(e)
         if result is not None:
             return result
+        # This dialog could time out too! Ignore it if it does.
+        # No need to check can_send_client_callback() here, as this exception should only be thrown by endpoints that
+        # are capable of sending callbacks.
+        try:
+            self.callback.ok_dialog("Notice", "You have remained idle for too long and this dialog has timed out. "
+                                              "Close and re-initiate it to continue.")
+        except SapioDialogTimeoutException:
+            pass
         return SapioWebhookResult(False)
 
+    def handle_unexpected_exception(self, e: Exception) -> SapioWebhookResult:
+        """
+        Handle a generic exception which isn't one of the handled Sapio exceptions.
+
+        Default behavior returns a false webhook result with a generic error message as display text informing the user
+        to contact Sapio support. Additionally, the stace trace of the exception that was thrown is logged to the
+        execution log for the webhook call in the system.
+
+        :param e: The exception that was raised.
+        :return: A SapioWebhookResult to end the webhook session with.
+        """
+        result: SapioWebhookResult | None = self.handle_any_exception(e)
+        if result is not None:
+            return result
+        msg: str = traceback.format_exc()
+        self.log_error(msg)
+        # FR-47079: Also log all unexpected exception messages to the webhook execution log within the platform.
+        self.log_error_to_webhook_execution_log(msg)
+        return SapioWebhookResult(False, display_text="Unexpected error occurred during webhook execution. "
+                                                      "Please contact Sapio support.")
+
     # noinspection PyMethodMayBeStatic,PyUnusedLocal
     def handle_any_exception(self, e: Exception) -> SapioWebhookResult | None:
         """
@@ -177,7 +214,8 @@ class CommonsWebhookHandler(AbstractWebhookHandler):
 
         :param e: The exception that was raised.
         :return: An optional SapioWebhookResult. May return a custom message to the client that wouldn't have been
-            sent by one of the normal exception handlers, or may return None if no result needs returned.
+            sent by one of the normal exception handlers, or may return None if no result needs returned. It a result is
+            returned, then the default behavior of other exception handlers is skipped.
         """
         return None