sapiopycommons 2024.11.10a363__py3-none-any.whl → 2024.11.12a365__py3-none-any.whl

sapiopycommons/general/audit_log.py

@@ -0,0 +1,189 @@
+from enum import Enum
+
+from sapiopylib.rest.User import SapioUser
+from sapiopylib.rest.pojo.CustomReport import ReportColumn, CustomReportCriteria
+
+from sapiopycommons.customreport.column_builder import ColumnBuilder
+from sapiopycommons.customreport.term_builder import TermBuilder
+from sapiopycommons.datatype.pseudo_data_types import AuditLogPseudoDef
+from sapiopycommons.general.aliases import RecordIdentifier, AliasUtil, UserIdentifier, FieldIdentifier, FieldValue
+from sapiopycommons.general.custom_report_util import CustomReportUtil
+
+
+class EventType(Enum):
+    """An enum to represent the possible event type values with the event type column in the audit log table."""
+    ADD = 0
+    DELETE = 1
+    MODIFY = 2
+    INFO = 3
+    ERROR = 4
+    WARNING = 5
+    IMPORT = 6
+    GENERATE = 7
+    EXPORT = 8
+    ADDREF = 9
+    REMOVEREF = 10
+    ESIGNATURE = 11
+    ROLEASSIGNMENT = 12
+
+
+class AuditLogEntry:
+    __event_type: EventType
+    __date: int
+    __data_type_name: str
+    __record_id: int
+    __description: str
+    __users_login_name: str
+    __comment: str
+    __data_record_name: str
+    __data_field_name: str
+    __original_value: str
+    __new_value: str
+
+    @property
+    def event_type(self) -> EventType:
+        return self.__event_type
+
+    @property
+    def date(self) -> int:
+        return self.__date
+
+    @property
+    def data_type_name(self) -> str:
+        return self.__data_type_name
+
+    @property
+    def record_id(self) -> int:
+        return self.__record_id
+
+    @property
+    def description(self) -> str:
+        return self.__description
+
+    @property
+    def users_login_name(self) -> str:
+        return self.__users_login_name
+
+    @property
+    def comment(self) -> str:
+        return self.__comment
+
+    @property
+    def data_record_name(self) -> str:
+        return self.__data_record_name
+
+    @property
+    def data_field_name(self) -> str:
+        return self.__data_field_name
+
+    @property
+    def original_value(self) -> str:
+        return self.__original_value
+
+    @property
+    def new_value(self) -> str:
+        return self.__new_value
+
+    def __init__(self, report_row: dict[str, FieldValue]):
+        self.__event_type = EventType((report_row[AuditLogPseudoDef.EVENT_TYPE__FIELD_NAME.field_name]))
+        self.__date = report_row[AuditLogPseudoDef.TIME_STAMP__FIELD_NAME.field_name]
+        self.__data_type_name = report_row[AuditLogPseudoDef.DATA_TYPE_NAME__FIELD_NAME.field_name]
+        self.__record_id = report_row[AuditLogPseudoDef.RECORD_ID__FIELD_NAME.field_name]
+        self.__description = report_row[AuditLogPseudoDef.DESCRIPTION__FIELD_NAME.field_name]
+        self.__users_login_name = report_row[AuditLogPseudoDef.USER_NAME__FIELD_NAME.field_name]
+        self.__comment = report_row[AuditLogPseudoDef.USER_COMMENT__FIELD_NAME.field_name]
+        self.__data_record_name = report_row[AuditLogPseudoDef.RECORD_NAME__FIELD_NAME]
+        self.__data_field_name = report_row[AuditLogPseudoDef.DATA_FIELD_NAME__FIELD_NAME.field_name]
+        self.__original_value = report_row[AuditLogPseudoDef.ORIGINAL_VALUE__FIELD_NAME.field_name]
+        self.__new_value = report_row[AuditLogPseudoDef.NEW_VALUE__FIELD_NAME.field_name]
+
+
+class AuditLogUtil:
+    user: SapioUser
+
+    def __init__(self, context: UserIdentifier):
+        self.user = AliasUtil.to_sapio_user(context)
+
+    @staticmethod
+    def report_columns() -> list[ReportColumn]:
+        return [
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.EVENT_TYPE__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.TIME_STAMP__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.DATA_TYPE_NAME__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.RECORD_ID__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.DESCRIPTION__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.USER_NAME__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.USER_COMMENT__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.RECORD_NAME__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.DATA_FIELD_NAME__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.ORIGINAL_VALUE__FIELD_NAME),
+            ColumnBuilder.build_column(AuditLogPseudoDef.DATA_TYPE_NAME, AuditLogPseudoDef.NEW_VALUE__FIELD_NAME)
+        ]
+
+    @staticmethod
+    def create_data_record_audit_log_report(records: list[RecordIdentifier],
+                                            fields: list[FieldIdentifier] | None = None) -> CustomReportCriteria:
+        """
+        This method creates a CustomReportCriteria object for running an audit log query based on data records.
+
+        Creates a CustomReportCriteria object with a query term based on the record ids/records passed into the method.
+        Optionally, the fields parameter can be populated to limit the search to particular fields. If the fields
+        parameter is not populated, the search will include results for all field changes.
+
+        :param records: The DataRecords, RecordModels, or record ids to base the search on.
+        :param fields: The data field names to include changes for.
+        :return: The constructed CustomReportCriteria object, which can be used to run a report on the audit log.
+        """
+        # Build the raw report term querying for any entry with a matching record ID value to the record ID's
+        # passed in.
+        record_ids = AliasUtil.to_record_ids(records)
+        root_term = TermBuilder.is_term(AuditLogPseudoDef.DATA_TYPE_NAME,
+                                        AuditLogPseudoDef.RECORD_ID__FIELD_NAME,
+                                        record_ids)
+
+        # If the user passed in any specific fields, then we should limit the query to those fields.
+        if fields:
+            fields: list[str] = AliasUtil.to_data_field_names(fields)
+            field_term = TermBuilder.is_term(AuditLogPseudoDef.DATA_TYPE_NAME,
+                                             AuditLogPseudoDef.DATA_FIELD_NAME__FIELD_NAME,
+                                             fields)
+            root_term = TermBuilder.and_terms(root_term, field_term)
+
+        return CustomReportCriteria(AuditLogUtil.report_columns(), root_term)
+
+    def run_data_record_audit_log_report(self, records: list[RecordIdentifier],
+                                         fields: list[FieldIdentifier] | None = None) \
+            -> dict[RecordIdentifier, list[AuditLogEntry]]:
+        """
+        This method runs a custom report for changes made to the given data records using the audit log.
+        See "create_data_record_audit_log_report" for more details about the data record audit log report.
+
+        :param records: The DataRecords, RecordModels, or record ids to base the search on.
+        :param fields: The data field names to include changes for.
+        :return: A dictionary where the keys are the record identifiers passed in, and the values are a list of
+            AuditLogEntry objects which match the record id value of those records.
+        """
+        fields: list[str] = AliasUtil.to_data_field_names(fields)
+        # First, we must build our report criteria for running the Custom Report.
+        criteria = AuditLogUtil.create_data_record_audit_log_report(records, fields)
+
+        # Then we must run the custom report using that criteria.
+        raw_report_data: list[dict[str, FieldValue]] = CustomReportUtil.run_custom_report(self.user, criteria)
+
+        # This section will prepare a map matching the original RecordIdentifier by record id.
+        # This is because the audit log entries will have record ids, but we want the keys in our result map
+        # to match the record identifiers that the user passed in, for convenience.
+        record_identifier_mapping: dict[int, RecordIdentifier] = dict()
+        for record in records:
+            record_id = AliasUtil.to_record_id(record)
+            record_identifier_mapping[record_id] = record
+
+        # Finally, we compile our audit data into a map where the keys are the record identifiers passed in,
+        # and the value is a list of applicable audit log entries.
+        final_audit_data: dict[RecordIdentifier, list[AuditLogEntry]] = dict()
+        for audit_entry_data in raw_report_data:
+            audit_entry: AuditLogEntry = AuditLogEntry(audit_entry_data)
+            identifier: RecordIdentifier = record_identifier_mapping.get(audit_entry.record_id)
+            final_audit_data.setdefault(identifier, []).append(audit_entry)
+
+        return final_audit_data

sapiopycommons/general/custom_report_util.py

@@ -1,19 +1,21 @@
 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
-from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
+from sapiopylib.rest.pojo.CustomReport import ReportColumn, CustomReport, CustomReportCriteria, RawReportTerm
+
+from sapiopycommons.general.aliases import UserIdentifier, FieldValue, AliasUtil, FieldIdentifierKey
 
 
 # FR-46064 - Initial port of PyWebhookUtils to sapiopycommons.
 class CustomReportUtil:
     @staticmethod
-    def run_system_report(context: SapioWebhookContext | SapioUser,
+    def run_system_report(context: UserIdentifier,
                           report_name: str,
-                          filters: dict[str, Iterable[Any]] | None = None,
-                          page_limit: int | None = None) -> list[dict[str, Any]]:
+                          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 system report and return the results of that report as a list of dictionaries for the values of each
         column in each row.
@@ -27,29 +29,97 @@ 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 = CustomReportUtil.__exhaust_system_report(context, report_name, page_limit)
+        results: tuple = CustomReportUtil.__exhaust_system_report(context, report_name, page_limit,
+                                                                  page_size, page_number)
         columns: list[ReportColumn] = results[0]
-        rows: list[list[Any]] = results[1]
+        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 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)
+        columns: list[ReportColumn] = results[0]
+        rows: list[list[FieldValue]] = results[1]
+        return CustomReportUtil.__process_results(rows, columns, filters)
 
     @staticmethod
-    def get_system_report_criteria(context: SapioWebhookContext | SapioUser, report_name: str) -> CustomReport:
+    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.
+
+        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)
+
+    @staticmethod
+    def get_system_report_criteria(context: UserIdentifier, 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.
@@ -64,27 +134,132 @@ 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 = context if isinstance(context, SapioUser) else context.user
+        user: SapioUser = AliasUtil.to_sapio_user(context)
         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: 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
+    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)
         report_man = DataMgmtServer.get_custom_report_manager(user)
 
-        report = None
-        page_size: int | None = None
-        page_number: int | None = None
+        result = None
+        if page_size is not None:
+            report.page_size = page_size
+        if page_number is not None:
+            report.page_number = page_number
         has_next_page: bool = True
-        rows: list[list[Any]] = []
+        rows: list[list[FieldValue]] = []
         cur_page: int = 1
-        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)
+        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)
             cur_page += 1
-        return report.column_list, rows
+        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

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/general/popup_util.py

@@ -1,3 +1,5 @@
+import warnings
+
 from sapiopylib.rest.DataMgmtService import DataMgmtServer
 from sapiopylib.rest.pojo.datatype.DataType import DataTypeDefinition
 from sapiopylib.rest.pojo.datatype.FieldDefinition import VeloxStringFieldDefinition, AbstractVeloxFieldDefinition, \
@@ -51,6 +53,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         if display_name is None:
             display_name = data_type
         if plural_display_name is None:
@@ -97,6 +100,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         # Get the field definitions of the data type.
         data_type: str = record.data_type_name
         type_man = DataMgmtServer.get_data_type_manager(context.user)
@@ -155,6 +159,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         if max_length is None:
             max_length = len(default_value) if default_value else 100
         string_field = VeloxStringFieldDefinition(data_type, field_name, field_name, default_value=default_value,
@@ -191,6 +196,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         if default_value is None:
             default_value = max(0, min_value)
         integer_field = VeloxIntegerFieldDefinition(data_type, field_name, field_name, default_value=default_value,
@@ -229,6 +235,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         if default_value is None:
             default_value = min_value
         double_field = VeloxDoubleFieldDefinition(data_type, field_name, field_name, default_value=default_value,
@@ -260,6 +267,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         if display_name is None:
             display_name = data_type
         if plural_display_name is None:
@@ -295,6 +303,9 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
+        if not records:
+            raise SapioException("No records provided.")
         data_types: set[str] = {x.data_type_name for x in records}
         if len(data_types) > 1:
             raise SapioException("Multiple data type names encountered in records list for record table popup.")
@@ -347,6 +358,9 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
+        if not records:
+            raise SapioException("No records provided.")
         data_types: set[str] = {x.data_type_name for x in records}
         if len(data_types) > 1:
             raise SapioException("Multiple data type names encountered in records list for record table popup.")
@@ -391,6 +405,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         callback = ListDialogRequest(title, multi_select, options,
                                      callback_context_data=request_context)
         return SapioWebhookResult(True, client_callback_request=callback)
@@ -415,6 +430,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         callback = OptionDialogRequest(title, msg, options, default_option, user_can_cancel,
                                        callback_context_data=request_context)
         return SapioWebhookResult(True, client_callback_request=callback)
@@ -437,6 +453,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         return PopupUtil.option_popup(title, msg, ["OK"], 0, user_can_cancel, request_context=request_context)
 
     @staticmethod
@@ -458,6 +475,7 @@ class PopupUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the popup as its client callback request.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         return PopupUtil.option_popup(title, msg, ["Yes", "No"], 0 if default_yes else 1, user_can_cancel,
                                       request_context=request_context)
 
@@ -470,6 +488,7 @@ class PopupUtil:
 
         Deprecated for PopupUtil.text_field_popup.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         return PopupUtil.string_field_popup(title, "", field_name, msg, len(msg), False, data_type,
                                             request_context=request_context, auto_size=True)
 
@@ -481,6 +500,7 @@ class PopupUtil:
 
         Deprecated for PopupUtil.option_popup.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         return PopupUtil.option_popup(title, msg, options, 0, user_can_cancel, request_context=request_context)
 
     @staticmethod
@@ -490,4 +510,5 @@ class PopupUtil:
 
         Deprecated for PopupUtil.ok_popup.
         """
+        warnings.warn("PopupUtil is deprecated as of 24.5+. Use CallbackUtil instead.", DeprecationWarning)
         return PopupUtil.ok_popup(title, msg, False, request_context=request_context)