sapiopycommons 2024.11.8a355__py3-none-any.whl → 2024.11.8a359__py3-none-any.whl

sapiopycommons/general/aliases.py

@@ -1,51 +1,24 @@
 from collections.abc import Iterable
 from typing import Any
 
-from sapiopylib.rest.User import SapioUser
 from sapiopylib.rest.pojo.DataRecord import DataRecord
-from sapiopylib.rest.pojo.datatype.FieldDefinition import FieldType
 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.webhook.WebhookContext import SapioWebhookContext
-from sapiopylib.rest.utils.Protocols import ElnExperimentProtocol, ElnEntryStep
+from sapiopylib.rest.utils.Protocols import ElnExperimentProtocol
 from sapiopylib.rest.utils.recordmodel.PyRecordModel import PyRecordModel
-from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedRecordModel, WrappedType, WrapperField
+from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedRecordModel, WrappedType
 
-from sapiopycommons.general.exceptions import SapioException
-
-FieldValue = int | float | str | bool | None
-"""Allowable values for fields in the system."""
-RecordModel = PyRecordModel | WrappedRecordModel
+RecordModel = PyRecordModel | WrappedRecordModel | WrappedType
 """Different forms that a record model could take."""
 SapioRecord = DataRecord | RecordModel
 """A record could be provided as either a DataRecord, PyRecordModel, or WrappedRecordModel (WrappedType)."""
 RecordIdentifier = SapioRecord | int
 """A RecordIdentifier is either a record type or an integer for the record's record ID."""
-DataTypeIdentifier = SapioRecord | type[WrappedType] | str
-"""A DataTypeIdentifier is either a SapioRecord, a record model wrapper type, or a string."""
-FieldIdentifier = WrapperField | str | tuple[str, FieldType]
-"""A FieldIdentifier is either wrapper field from a record model wrapper, a string, or a tuple of string
-and field type."""
-FieldIdentifierKey = WrapperField | str
-"""A FieldIdentifierKey is a FieldIdentifier, except it can't be a tuple, s tuples can't be used as keys in
-dictionaries.."""
-HasFieldWrappers = type[WrappedType] | WrappedRecordModel
-"""An identifier for classes that have wrapper fields."""
 ExperimentIdentifier = ElnExperimentProtocol | ElnExperiment | int
-"""An ExperimentIdentifier is either an experiment protocol, experiment, or an integer for the experiment's notebook
+"""An ExperimentIdentifier is either an experiment protocol, experiment, or an integer for te experiment's notebook
 ID."""
-ExperimentEntryIdentifier = ElnEntryStep | ExperimentEntry | int
-"""An ExperimentEntryIdentifier is either an ELN entry step, experiment entry, or an integer for the entry's ID."""
-FieldMap = dict[str, FieldValue]
+FieldMap = dict[str, Any]
 """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."""
-FieldIdentifierMap = dict[FieldIdentifierKey, FieldValue]
-"""A field identifier map is the same thing as a field map, except the keys can be field identifiers instead
-of just strings. Note that although one of the allowed field identifiers is a tuple, you can't use tuples as
-keys in a dictionary."""
-UserIdentifier = SapioWebhookContext | SapioUser
-"""An identifier for classes from which a user object can be used for sending requests."""
 
 
 # FR-46064 - Initial port of PyWebhookUtils to sapiopycommons.
@@ -77,132 +50,7 @@ class AliasUtil:
 
         :return: A list of record IDs for the input records.
         """
-        return [(AliasUtil.to_record_id(x)) for x in records]
-
-    @staticmethod
-    def to_record_id(record: RecordIdentifier):
-        """
-        Convert a single variable that could be either an integer, DataRecord, PyRecordModel,
-        or WrappedRecordModel to just an integer (taking the record ID from the record).
-
-        :return: A record ID for the input record.
-        """
-        return record if isinstance(record, int) else record.record_id
-
-    @staticmethod
-    def to_data_type_name(value: DataTypeIdentifier, convert_eln_dts: bool = True) -> str:
-        """
-        Convert a given value to a data type name.
-
-        :param value: A value which is a string, record, or record model type.
-        :param convert_eln_dts: If true, convert ELN data types to their base data type name.
-        :return: A string of the data type name of the input value.
-        """
-        if isinstance(value, SapioRecord):
-            value = value.data_type_name
-        elif not isinstance(value, str):
-            value = value.get_wrapper_data_type_name()
-        if convert_eln_dts and ElnBaseDataType.is_eln_type(value):
-            return ElnBaseDataType.get_base_type(value).data_type_name
-        return value
-
-    @staticmethod
-    def to_data_type_names(values: Iterable[DataTypeIdentifier], return_set: bool = False,
-                           convert_eln_dts: bool = True) -> list[str] | set[str]:
-        """
-        Convert a given iterable of values to a list or set of data type names.
-
-        :param values: An iterable of values which are strings, records, or record model types.
-        :param return_set: If true, return a set instead of a list.
-        :param convert_eln_dts: If true, convert ELN data types to their base data type name.
-        :return: A list or set of strings of the data type name of the input value.
-        """
-        values = [AliasUtil.to_data_type_name(x, convert_eln_dts) for x in values]
-        return set(values) if return_set else values
-
-    @staticmethod
-    def to_singular_data_type_name(values: Iterable[DataTypeIdentifier], convert_eln_dts: bool = True) -> str:
-        """
-        Convert a given iterable of values to a singular data type name that they share. Throws an exception if more
-        than one data type name exists in the provided list of identifiers.
-
-        :param values: An iterable of values which are strings, records, or record model types.
-        :param convert_eln_dts: If true, convert ELN data types to their base data type name.
-        :return: The single data type name that the input vales share. Returns an empty string if an empty iterable
-            was provided.
-        """
-        if not values:
-            return ""
-        data_types: set[str] = AliasUtil.to_data_type_names(values, True, convert_eln_dts)
-        if len(data_types) > 1:
-            raise SapioException(f"Provided values contain multiple data types: {data_types}. "
-                                 f"Only expecting a single data type.")
-        return data_types.pop()
-
-    @staticmethod
-    def to_data_field_name(value: FieldIdentifier) -> str:
-        """
-        Convert a string or WrapperField to a data field name string.
-
-        :param value: A string or WrapperField.
-        :return: A string of the data field name of the input value.
-        """
-        if isinstance(value, tuple):
-            return value[0]
-        if isinstance(value, WrapperField):
-            return value.field_name
-        return value
-
-    @staticmethod
-    def to_data_field_names(values: Iterable[FieldIdentifier]) -> list[str]:
-        """
-        Convert an iterable of strings or WrapperFields to a list of data field name strings.
-
-        :param values: An iterable of strings or WrapperFields.
-        :return: A list of strings of the data field names of the input values.
-        """
-        return [AliasUtil.to_data_field_name(x) for x in values]
-
-    @staticmethod
-    def to_data_field_names_dict(values: dict[FieldIdentifierKey, Any]) -> dict[str, Any]:
-        """
-        Take a dictionary whose keys are field identifiers and convert them all to strings for the data field name.
-
-        :param values: A dictionary of field identifiers to field values.
-        :return: A dictionary of strings of the data field names to field values for the input values.
-        """
-        ret_dict: dict[str, FieldValue] = {}
-        for field, value in values.items():
-            ret_dict[AliasUtil.to_data_field_name(field)] = value
-        return ret_dict
-
-    @staticmethod
-    def to_data_field_names_list_dict(values: list[dict[FieldIdentifierKey, Any]]) -> list[dict[str, Any]]:
-        ret_list: list[dict[str, Any]] = []
-        for field_map in values:
-            ret_list.append(AliasUtil.to_data_field_names_dict(field_map))
-        return ret_list
-
-    @staticmethod
-    def to_field_type(field: FieldIdentifier, data_type: HasFieldWrappers | None = None) -> FieldType:
-        """
-        Convert a given field identifier to the field type for that field.
-
-        :param field: A string or WrapperField.
-        :param data_type: If the field is provided as a string, then a record model wrapper or wrapped record model
-            must be provided to determine the field type.
-        :return: The field type of the given field.
-        """
-        if isinstance(field, tuple):
-            return field[1]
-        if isinstance(field, WrapperField):
-            return field.field_type
-        for var in dir(data_type):
-            attr = getattr(data_type, var)
-            if isinstance(attr, WrapperField) and attr.field_name == field:
-                return attr.field_type
-        raise SapioException(f"The wrapper of data type \"{data_type.get_wrapper_data_type_name()}\" doesn't have a "
-                             f"field with the name \"{field}\",")
+        return [(x if isinstance(x, int) else x.record_id) for x in records]
 
     @staticmethod
     def to_field_map_lists(records: Iterable[SapioRecord]) -> list[FieldMap]:
@@ -215,7 +63,6 @@ class AliasUtil:
         field_map_list: list[FieldMap] = []
         for record in records:
             if isinstance(record, DataRecord):
-                # noinspection PyTypeChecker
                 field_map_list.append(record.get_fields())
             else:
                 field_map_list.append(record.fields.copy_to_dict())
@@ -233,51 +80,3 @@ class AliasUtil:
         if isinstance(experiment, ElnExperiment):
             return experiment.notebook_experiment_id
         return experiment.get_id()
-
-    @staticmethod
-    def to_notebook_ids(experiments: list[ExperimentIdentifier]) -> list[int]:
-        """
-        Convert a list of objects that identify ELN experiments to their notebook IDs.
-
-        :return: The list of notebook IDs for the experiment identifiers.
-        """
-        notebook_ids: list[int] = []
-        for experiment in experiments:
-            notebook_ids.append(AliasUtil.to_notebook_id(experiment))
-        return notebook_ids
-
-    @staticmethod
-    def to_entry_id(entry: ExperimentEntryIdentifier) -> int:
-        """
-        Convert an object that identifies an experiment entry to its entry ID.
-
-        :return: The entry ID for the entry identifier.
-        """
-        if isinstance(entry, int):
-            return entry
-        elif isinstance(entry, ExperimentEntry):
-            return entry.entry_id
-        elif isinstance(entry, ElnEntryStep):
-            return entry.get_id()
-        raise SapioException(f"Unrecognized entry identifier of type {type(entry)}")
-
-    @staticmethod
-    def to_entry_ids(entries: list[ExperimentEntryIdentifier]) -> list[int]:
-        """
-        Convert a list of objects that identify experiment entries to their entry IDs.
-
-        :return: The list of entry IDs for the entry identifiers.
-        """
-        entry_ids: list[int] = []
-        for entry in entries:
-            entry_ids.append(AliasUtil.to_entry_id(entry))
-        return entry_ids
-
-    @staticmethod
-    def to_sapio_user(context: UserIdentifier) -> SapioUser:
-        """
-        Convert an object that could be either a SapioUser or SapioWebhookContext to just a SapioUser.
-
-        :return: A SapioUser object.
-        """
-        return context if isinstance(context, SapioUser) else context.user

sapiopycommons/general/custom_report_util.py

@@ -1,21 +1,19 @@
 from collections.abc import Iterable
+from typing import Any
 
 from sapiopylib.rest.DataMgmtService import DataMgmtServer
 from sapiopylib.rest.User import SapioUser
-from sapiopylib.rest.pojo.CustomReport import ReportColumn, CustomReport, CustomReportCriteria, RawReportTerm
-
-from sapiopycommons.general.aliases import UserIdentifier, FieldValue, AliasUtil, FieldIdentifierKey
+from sapiopylib.rest.pojo.CustomReport import ReportColumn, CustomReport
+from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
 
 
 # FR-46064 - Initial port of PyWebhookUtils to sapiopycommons.
 class CustomReportUtil:
     @staticmethod
-    def run_system_report(context: UserIdentifier,
+    def run_system_report(context: SapioWebhookContext | SapioUser,
                           report_name: str,
-                          filters: dict[FieldIdentifierKey, Iterable[FieldValue]] | None = None,
-                          page_limit: int | None = None,
-                          page_size: int | None = None,
-                          page_number: int | None = None) -> list[dict[str, FieldValue]]:
+                          filters: dict[str, Iterable[Any]] | None = None,
+                          page_limit: int | None = None) -> list[dict[str, Any]]:
         """
         Run a system report and return the results of that report as a list of dictionaries for the values of each
         column in each row.
@@ -29,97 +27,29 @@ class CustomReportUtil:
             filter on. Only those headers that both the filters and the custom report share will take effect. That is,
             any filters that have a header name that isn't in the custom report will be ignored.
         :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages.
-        :param page_size: The size of each page of results in the search. If None, the page size is set by the server.
-        :param page_number: The page number to start the search from, If None, starts on the first page.
-        :return: The results of the report listed row by row, mapping each cell to the header it is under. The header
-            values in the dicts are the data field names of the columns.
-            If two columns in the search have the same data field name but differing data type names, then the
-            dictionary key to the value in the column will be "DataTypeName.DataFieldName". For example, if you
-            had a Sample column with a data field name of Identifier and a Request column with the same data field name,
-            then the dictionary keys for these columns would be Sample.Identifier and Request.Identifier respectively.
-        """
-        results: tuple = CustomReportUtil.__exhaust_system_report(context, report_name, page_limit,
-                                                                  page_size, page_number)
-        columns: list[ReportColumn] = results[0]
-        rows: list[list[FieldValue]] = results[1]
-        return CustomReportUtil.__process_results(rows, columns, filters)
-
-    @staticmethod
-    def run_custom_report(context: UserIdentifier,
-                          report_criteria: CustomReportCriteria,
-                          filters: dict[FieldIdentifierKey, Iterable[FieldValue]] | None = None,
-                          page_limit: int | None = None,
-                          page_size: int | None = None,
-                          page_number: int | None = None) -> list[dict[str, FieldValue]]:
-        """
-        Run a custom report and return the results of that report as a list of dictionaries for the values of each
-        column in each row.
-
-        Custom reports are constructed by the caller, specifying the report terms and the columns that will be in the
-        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.
-
-        :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
-            filter on. Only those headers that both the filters and the custom report share will take effect. That is,
-            any filters that have a header name that isn't in the custom report will be ignored.
-            Note that this parameter is only provided for parity with the other run report functions. If you need to
-            filter the results of a search, it would likely be more beneficial to have just added a new term to the
-            input report criteria that corresponds to the filter.
-        :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages.
-        :param page_size: The size of each page of results in the search. If None, uses the value from the given report
-            criteria. If not None, overwrites the value from the given report criteria.
-        :param page_number: The page number to start the search from, If None, uses the value from the given report
-            criteria. If not None, overwrites the value from the given report criteria.
         :return: The results of the report listed row by row, mapping each cell to the header it is under. The header
             values in the dicts are the data field names of the columns.
-            If two columns in the search have the same data field name but differing data type names, then the
-            dictionary key to the value in the column will be "DataTypeName.DataFieldName". For example, if you
-            had a Sample column with a data field name of Identifier and a Request column with the same data field name,
-            then the dictionary keys for these columns would be Sample.Identifier and Request.Identifier respectively.
         """
-        results: tuple = CustomReportUtil.__exhaust_custom_report(context, report_criteria, page_limit,
-                                                                  page_size, page_number)
+        results = CustomReportUtil.__exhaust_system_report(context, report_name, page_limit)
         columns: list[ReportColumn] = results[0]
-        rows: list[list[FieldValue]] = results[1]
-        return CustomReportUtil.__process_results(rows, columns, filters)
-
-    @staticmethod
-    def run_quick_report(context: UserIdentifier,
-                         report_term: RawReportTerm,
-                         filters: dict[FieldIdentifierKey, Iterable[FieldValue]] | None = None,
-                         page_limit: int | None = None,
-                         page_size: int | None = None,
-                         page_number: int | None = None) -> list[dict[str, FieldValue]]:
-        """
-        Run a quick report and return the results of that report as a list of dictionaries for the values of each
-        column in each row.
+        rows: list[list[Any]] = results[1]
 
-        Quick reports are helpful for cases where you need to query record field values in a more complex manner than
-        the data record manager allows, but still simpler than a full-blown custom report. The columns that are returned
-        in a quick search are every visible field from the data type that corresponds to the given report term. (Fields
-        which are not marked as visible in the data designer will be excluded.)
-
-        :param context: The current webhook context or a user object to send requests from.
-        :param report_term: The raw report term to use for the quick report.
-        :param filters: If provided, filter the results of the report using the given mapping of headers to values to
-            filter on. Only those headers that both the filters and the custom report share will take effect. That is,
-            any filters that have a header name that isn't in the custom report will be ignored.
-        :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages.
-        :param page_size: The size of each page of results in the search. If None, the page size is set by the server.
-        :param page_number: The page number to start the search from, If None, starts on the first page.
-        :return: The results of the report listed row by row, mapping each cell to the header it is under. The header
-            values in the dicts are the data field names of the columns.
-        """
-        results: tuple = CustomReportUtil.__exhaust_quick_report(context, report_term, page_limit,
-                                                                 page_size, page_number)
-        columns: list[ReportColumn] = results[0]
-        rows: list[list[FieldValue]] = results[1]
-        return CustomReportUtil.__process_results(rows, columns, filters)
+        ret: list[dict[str, Any]] = []
+        for row in rows:
+            row_data: dict[str, Any] = {}
+            filter_row: bool = False
+            for value, column in zip(row, columns):
+                header: str = column.data_field_name
+                if filters is not None and header in filters and value not in filters.get(header):
+                    filter_row = True
+                    break
+                row_data.update({header: value})
+            if filter_row is False:
+                ret.append(row_data)
+        return ret
 
     @staticmethod
-    def get_system_report_criteria(context: UserIdentifier, report_name: str) -> CustomReport:
+    def get_system_report_criteria(context: SapioWebhookContext | SapioUser, report_name: str) -> CustomReport:
         """
         Retrieve a custom report from the system given the name of the report. This works by querying the system report
         with a page number and size of 1 to minimize the amount of data transfer needed to retrieve the report's config.
@@ -134,132 +64,27 @@ class CustomReportUtil:
         :param report_name: The name of the system report to run.
         :return: The CustomReport object for the given system report name.
         """
-        user: SapioUser = AliasUtil.to_sapio_user(context)
+        user: SapioUser = context if isinstance(context, SapioUser) else context.user
         report_man = DataMgmtServer.get_custom_report_manager(user)
         return report_man.run_system_report_by_name(report_name, 1, 1)
 
     @staticmethod
-    def __exhaust_system_report(context: UserIdentifier,
-                                report_name: str,
-                                page_limit: int | None,
-                                page_size: int | None,
-                                page_number: int | None) \
-            -> tuple[list[ReportColumn], list[list[FieldValue]]]:
-        """
-        Given a system report, iterate over every page of the report and collect the results
-        until there are no remaining pages.
-        """
-        user: SapioUser = AliasUtil.to_sapio_user(context)
-        report_man = DataMgmtServer.get_custom_report_manager(user)
-
-        result = None
-        has_next_page: bool = True
-        rows: list[list[FieldValue]] = []
-        cur_page: int = 1
-        while has_next_page and (not page_limit or cur_page <= page_limit):
-            result = report_man.run_system_report_by_name(report_name, page_size, page_number)
-            page_size = result.page_size
-            page_number = result.page_number
-            has_next_page = result.has_next_page
-            rows.extend(result.result_table)
-            cur_page += 1
-        return result.column_list, rows
-
-    @staticmethod
-    def __exhaust_custom_report(context: UserIdentifier,
-                                report: CustomReportCriteria,
-                                page_limit: int | None,
-                                page_size: int | None,
-                                page_number: int | None) \
-            -> tuple[list[ReportColumn], list[list[FieldValue]]]:
-        """
-        Given a custom report, iterate over every page of the report and collect the results
-        until there are no remaining pages.
-        """
-        user: SapioUser = AliasUtil.to_sapio_user(context)
+    def __exhaust_system_report(context: SapioWebhookContext | SapioUser, report_name: str, page_limit: int | None = None) \
+            -> tuple[list[ReportColumn], list[list[Any]]]:
+        user: SapioUser = context if isinstance(context, SapioUser) else context.user
         report_man = DataMgmtServer.get_custom_report_manager(user)
 
-        result = None
-        if page_size is not None:
-            report.page_size = page_size
-        if page_number is not None:
-            report.page_number = page_number
+        report = None
+        page_size: int | None = None
+        page_number: int | None = None
         has_next_page: bool = True
-        rows: list[list[FieldValue]] = []
+        rows: list[list[Any]] = []
         cur_page: int = 1
-        while has_next_page and (not page_limit or cur_page <= page_limit):
-            result = report_man.run_custom_report(report)
-            report.page_size = result.page_size
-            report.page_number = result.page_number
-            has_next_page = result.has_next_page
-            rows.extend(result.result_table)
+        while has_next_page and (not page_limit or cur_page < page_limit):
+            report = report_man.run_system_report_by_name(report_name, page_size, page_number)
+            page_size = report.page_size
+            page_number = report.page_number
+            has_next_page = report.has_next_page
+            rows.extend(report.result_table)
             cur_page += 1
-        return result.column_list, rows
-
-    @staticmethod
-    def __exhaust_quick_report(context: UserIdentifier,
-                               report_term: RawReportTerm,
-                               page_limit: int | None,
-                               page_size: int | None,
-                               page_number: int | None) \
-            -> tuple[list[ReportColumn], list[list[FieldValue]]]:
-        """
-        Given a quick report, iterate over every page of the report and collect the results
-        until there are no remaining pages.
-        """
-        user: SapioUser = AliasUtil.to_sapio_user(context)
-        report_man = DataMgmtServer.get_custom_report_manager(user)
-
-        result = None
-        has_next_page: bool = True
-        rows: list[list[FieldValue]] = []
-        cur_page: int = 1
-        while has_next_page and (not page_limit or cur_page <= page_limit):
-            result = report_man.run_quick_report(report_term, page_size, page_number)
-            page_size = result.page_size
-            page_number = result.page_number
-            has_next_page = result.has_next_page
-            rows.extend(result.result_table)
-            cur_page += 1
-        return result.column_list, rows
-
-    @staticmethod
-    def __process_results(rows: list[list[FieldValue]], columns: list[ReportColumn],
-                          filters: dict[FieldIdentifierKey, Iterable[FieldValue]] | None) -> list[dict[str, FieldValue]]:
-        """
-        Given the results of a report as a list of row values and the report's columns, combine these lists to
-        result in a singular list of dictionaries for each row in the results.
-
-        If any filter criteria has been provided, also use that to filter the row.
-        """
-        # It may be the case that two columns have the same data field name but differing data type names.
-        # If this occurs, then we need to be able to differentiate these columns in the resulting dictionary.
-        prepend_dt: set[str] = set()
-        encountered_names: list[str] = []
-        for column in columns:
-            field_name: str = column.data_field_name
-            if field_name in encountered_names:
-                prepend_dt.add(field_name)
-            else:
-                encountered_names.append(field_name)
-
-        if filters:
-            filters: dict[str, Iterable[FieldValue]] = AliasUtil.to_data_field_names_dict(filters)
-
-        ret: list[dict[str, FieldValue]] = []
-        for row in rows:
-            row_data: dict[str, FieldValue] = {}
-            filter_row: bool = False
-            for value, column in zip(row, columns):
-                header: str = column.data_field_name
-                # If two columns share the same data field name, prepend the data type name of the column to the
-                # data field name.
-                if header in prepend_dt:
-                    header = column.data_type_name + "." + header
-                if filters is not None and header in filters and value not in filters.get(header):
-                    filter_row = True
-                    break
-                row_data.update({header: value})
-            if filter_row is False:
-                ret.append(row_data)
-        return ret
+        return report.column_list, rows

sapiopycommons/general/exceptions.py

@@ -3,47 +3,34 @@ 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.
-
-    CommonsWebhookHandler's default behavior is to return the error message in a toaster popup.
+    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).
     """
     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.
-
-    CommonsWebhookHandler's default behavior is to return the error message in a display_error callback.
+    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).
     """
     pass