sapiopycommons 2024.8.15a304__py3-none-any.whl → 2024.8.19a305__py3-none-any.whl

sapiopycommons/files/file_writer.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import warnings
 from abc import abstractmethod
 from enum import Enum
 from typing import Any
@@ -18,7 +19,7 @@ class FileWriter:
     body: list[list[Any]]
     delimiter: str
     line_break: str
-    column_definitions: list[ColumnDef]
+    column_definitions: dict[str, ColumnDef]
 
     def __init__(self, headers: list[str], delimiter: str = ",", line_break: str = "\r\n"):
         """
@@ -30,7 +31,7 @@ class FileWriter:
         self.delimiter = delimiter
         self.line_break = line_break
         self.body = []
-        self.column_definitions = []
+        self.column_definitions = {}
 
     def add_row_list(self, row: list[Any]) -> None:
         """
@@ -65,21 +66,49 @@ class FileWriter:
             new_row.append(row.get(header, ""))
         self.body.append(new_row)
 
-    def add_column_definitions(self, column_defs: list[ColumnDef]) -> None:
+    def add_column_definition(self, header: str, column_def: ColumnDef) -> None:
         """
-        Add new column definitions to this FileWriter. Column definitions are evaluated in the order they are added,
-        meaning that they map to the header with the equivalent index. Before the file is built, the number of column
-        definitions must equal the number of headers if any column definition is provided.
+        Add a new column definition to this FileWriter for a specific header.
 
-        ColumnDefs are only used if the build_file function is provided with a list of RowBundles.
+        ColumnDefs are only used if the build_file function is provided with a list of RowBundles. Every header must
+        have a column definition if this is the case.
 
         Custom column definitions can be created by defining a class that extends ColumnDef and implements the print
         method.
 
-        :param column_defs: A list of column definitions to be used to construct the file when build_file is
+        :param column_def: A column definitions to be used to construct the file when build_file is
             called.
+        :param header: The header that this column definition is for. If a header is provided that isn't in the headers
+            list, the header is appended to the end of the list.
         """
-        self.column_definitions.extend(column_defs)
+        if header not in self.headers:
+            self.headers.append(header)
+        self.column_definitions[header] = column_def
+
+    def add_column_definitions(self, column_defs: dict[str, ColumnDef]) -> None:
+        """
+        Add new column definitions to this FileWriter.
+
+        ColumnDefs are only used if the build_file function is provided with a list of RowBundles. Every header must
+        have a column definition if this is the case.
+
+        Custom column definitions can be created by defining a class that extends ColumnDef and implements the print
+        method.
+
+        :param column_defs: A dictionary of header names to column definitions to be used to construct the file when
+            build_file is called.
+        """
+        # For backwards compatibility purposes, if column definitions are provided as a list,
+        # add them in order of appearance of the headers. This will only work if the headers are defined first, though.
+        if isinstance(column_defs, list):
+            warnings.warn("Adding column definitions is no longer expected as a list. Continuing to provide a list to "
+                          "this function may result in undesirable behavior.", UserWarning)
+            if not self.headers:
+                raise SapioException("No headers provided to FileWriter before the column definitions were added.")
+            for header, column_def in zip(self.headers, column_defs):
+                self.column_definitions[header] = column_def
+        for header, column_def in column_defs.items():
+            self.add_column_definition(header, column_def)
 
     def build_file(self, rows: list[RowBundle] | None = None, sorter=None, reverse: bool = False) -> str:
         """
@@ -100,11 +129,10 @@ class FileWriter:
         """
         # If any column definitions have been provided, the number of column definitions and headers must be equal.
         if self.column_definitions:
-            def_count: int = len(self.column_definitions)
-            header_count: int = len(self.headers)
-            if def_count != header_count:
-                raise SapioException(f"FileWriter has {def_count} column definitions defined but {header_count} "
-                                     f"headers. The number of column definitions must equal the number of headers.")
+            for header in self.headers:
+                if header not in self.column_definitions:
+                    raise SapioException(f"FileWriter has no column definition for the header {header}. If any column "
+                                         f"definitions are provided, then all headers must have a column definition.")
         # If any RowBundles have been provided, there must be column definitions for mapping them to the file.
         elif rows:
             raise SapioException(f"FileWriter was given RowBundles but contains no column definitions for mapping "
@@ -130,7 +158,8 @@ class FileWriter:
         rows.sort(key=lambda x: x.index)
         for row in rows:
             new_row: list[Any] = []
-            for column in self.column_definitions:
+            for header in self.headers:
+                column = self.column_definitions[header]
                 if column.may_skip and row.may_skip:
                     new_row.append("")
                 else:

sapiopycommons/general/aliases.py

@@ -2,10 +2,13 @@ from collections.abc import Iterable
 from typing import Any
 
 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.utils.Protocols import ElnExperimentProtocol
 from sapiopylib.rest.utils.recordmodel.PyRecordModel import PyRecordModel
-from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedRecordModel, WrappedType
+from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedRecordModel, WrappedType, WrapperField
+
+from sapiopycommons.general.exceptions import SapioException
 
 RecordModel = PyRecordModel | WrappedRecordModel | WrappedType
 """Different forms that a record model could take."""
@@ -13,6 +16,13 @@ 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."""
+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 te experiment's notebook
 ID."""
@@ -50,7 +60,88 @@ class AliasUtil:
 
         :return: A list of record IDs for the input records.
         """
-        return [(x if isinstance(x, int) else x.record_id) for x in 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) -> str:
+        """
+        Convert a given value to a data type name.
+
+        :param value: A value which is a string, record, or record model type.
+        :return: A string of the data type name of the input value.
+        """
+        if isinstance(value, str):
+            return value
+        if isinstance(value, SapioRecord):
+            return value.data_type_name
+        return value.get_wrapper_data_type_name()
+
+    @staticmethod
+    def to_data_type_names(values: Iterable[DataTypeIdentifier], return_set: bool = False) -> 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.
+        :return: A list or set of strings of the data type name of the input value.
+        """
+        values = [AliasUtil.to_data_type_name(x) for x in values]
+        return set(values) if return_set else values
+
+    @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_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}\",")
 
     @staticmethod
     def to_field_map_lists(records: Iterable[SapioRecord]) -> list[FieldMap]:

sapiopycommons/general/audit_log.py

@@ -0,0 +1,200 @@
+from enum import Enum
+from typing import Any
+
+from sapiopylib.rest.DataRecordManagerService import DataRecordManager
+from sapiopylib.rest.User import SapioUser
+from sapiopylib.rest.pojo.CustomReport import ReportColumn, RawReportTerm, CustomReportCriteria, RawTermOperation, \
+    CompositeReportTerm, CompositeTermOperation
+from sapiopylib.rest.pojo.datatype.FieldDefinition import FieldType
+from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
+
+from sapiopycommons.general.aliases import RecordIdentifier, AliasUtil
+from sapiopycommons.general.custom_report_util import CustomReportUtil
+
+EVENTTYPE_COLUMN = "EVENTTYPE"
+TIMESTAMP_COLUMN = "TIMESTAMP"
+DATATYPENAME_COLUMN = "DATATYPENAME"
+RECORDID_COLUMN = "RECORDID"
+DESCRIPTION_COLUMN = "DESCRIPTION"
+USERNAME_COLUMN = "USERNAME"
+USERCOMMENT_COLUMN = "USERCOMMENT"
+RECORDNAME_COLUMN = "RECORDNAME"
+DATAFIELDNAME_COLUMN = "DATAFIELDNAME"
+ORIGINALVALUE_COLUMN = "ORIGINALVALUE"
+NEWVALUE_COLUMN = "NEWVALUE"
+
+
+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, Any]):
+        self.__event_type = EventType((report_row[EVENTTYPE_COLUMN]))
+        self.__date = report_row[TIMESTAMP_COLUMN]
+        self.__data_type_name = report_row[DATATYPENAME_COLUMN]
+        self.__record_id = report_row[RECORDID_COLUMN]
+        self.__description = report_row[DESCRIPTION_COLUMN]
+        self.__users_login_name = report_row[USERNAME_COLUMN]
+        self.__comment = report_row[USERCOMMENT_COLUMN]
+        self.__data_record_name = report_row[RECORDNAME_COLUMN]
+        self.__data_field_name = report_row[DATAFIELDNAME_COLUMN]
+        self.__original_value = report_row[ORIGINALVALUE_COLUMN]
+        self.__new_value = report_row[NEWVALUE_COLUMN]
+
+
+class AuditLog:
+    AUDIT_LOG_PSEUDO_DATATYPE: str = "AUDITLOG"
+    EVENT_TYPE: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, EVENTTYPE_COLUMN, FieldType.ENUM)
+    DATE: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, TIMESTAMP_COLUMN, FieldType.DATE)
+    DATA_TYPE_NAME: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, DATATYPENAME_COLUMN, FieldType.STRING)
+    RECORD_ID: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, RECORDID_COLUMN, FieldType.LONG)
+    DESCRIPTION: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, DESCRIPTION_COLUMN, FieldType.STRING)
+    USERS_LOGIN_NAME: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, USERNAME_COLUMN, FieldType.STRING)
+    COMMENT: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, USERCOMMENT_COLUMN, FieldType.STRING)
+    DATA_RECORD_NAME: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, RECORDNAME_COLUMN, FieldType.STRING)
+    DATA_FIELD_NAME: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, DATAFIELDNAME_COLUMN, FieldType.STRING)
+    ORIGINAL_VALUE: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, ORIGINALVALUE_COLUMN, FieldType.STRING)
+    NEW_VALUE: ReportColumn = ReportColumn(AUDIT_LOG_PSEUDO_DATATYPE, NEWVALUE_COLUMN, FieldType.STRING)
+
+    AUDIT_LOG_COLUMNS = [EVENT_TYPE, DATE, DATA_TYPE_NAME, RECORD_ID, DESCRIPTION, USERS_LOGIN_NAME, COMMENT,
+                         DATA_RECORD_NAME, DATA_FIELD_NAME, ORIGINAL_VALUE, NEW_VALUE]
+    user: SapioUser
+
+    def __init__(self, context: SapioWebhookContext | SapioUser):
+        self.user = context if isinstance(context, SapioUser) else context.user
+
+    @staticmethod
+    def create_data_record_audit_log_report(records: list[RecordIdentifier], fields: list[str] | 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.
+        """
+        # We need to compile the record ids from these record identifiers as "str" variables, so they can be
+        # concatenated.
+        record_ids = AliasUtil.to_record_ids(records)
+        id_strs = [str(id_int) for id_int in record_ids]
+
+        # Next we'll build the raw report term querying for any entry with a matching record id value to the record ID's
+        # passed in
+        root_term = RawReportTerm(AuditLog.AUDIT_LOG_PSEUDO_DATATYPE, RECORDID_COLUMN,
+                                  RawTermOperation.EQUAL_TO_OPERATOR, "{" + ",".join(id_strs) + "}")
+
+        # If the user passed in any specific fields, then we should limit the query to those fields.
+        if fields:
+            field_term = RawReportTerm(AuditLog.AUDIT_LOG_PSEUDO_DATATYPE, DATAFIELDNAME_COLUMN,
+                                       RawTermOperation.EQUAL_TO_OPERATOR, "{" + ",".join(fields) + "}")
+            root_term = CompositeReportTerm(root_term, CompositeTermOperation.AND_OPERATOR, field_term)
+
+        return CustomReportCriteria(AuditLog.AUDIT_LOG_COLUMNS, root_term)
+
+    def run_data_record_audit_log_report(self, records: list[RecordIdentifier], fields: list[str] | 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.
+        """
+        # First, we must build our report criteria for running the Custom Report.
+        criteria = AuditLog.create_data_record_audit_log_report(records, fields)
+
+        # Then we must run the custom report using that criteria.
+        raw_report_data: list[dict[str, Any]] = 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/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,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)
         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 +356,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)
         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 +401,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 +426,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 +449,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 +471,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 +484,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 +496,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 +506,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)

sapiopycommons/general/sapio_links.py

@@ -0,0 +1,48 @@
+from sapiopylib.rest.User import SapioUser
+from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
+
+from sapiopycommons.general.aliases import RecordIdentifier, ExperimentIdentifier, AliasUtil
+from sapiopycommons.general.exceptions import SapioException
+
+
+class SapioNavigationLinker:
+    """
+    Given a URL to a system's webservice API (example: https://company.exemplareln.com/webservice/api), construct
+    URLs for navigation links to various locations in the system.
+    """
+    base_url: str
+
+    def __init__(self, url: str | SapioUser | SapioWebhookContext):
+        """
+        :param url: A user or context object that is being used to send requests to a Sapio system, or a URL to a
+            system's webservice API.
+        """
+        if isinstance(url, SapioWebhookContext):
+            url = url.user.url
+        elif isinstance(url, SapioUser):
+            url = url.url
+        self.base_url = url.rstrip("/").replace('webservice/api', 'veloxClient')
+
+    def data_record(self, record_identifier: RecordIdentifier, data_type_name: str | None = None) -> str:
+        """
+        :param record_identifier: An object that can be used to identify a record in the system, be that a record ID,
+            a data record, or a record model.
+        :param data_type_name: If the provided record identifier is a record ID, then the data type name of the record
+            must be provided in this parameter. Otherwise, this parameter is ignored.
+        :return: A URL for navigating to the input record.
+        """
+        record_id: int = AliasUtil.to_record_id(record_identifier)
+        if not isinstance(record_identifier, int):
+            data_type_name = AliasUtil.to_data_type_name(record_identifier)
+        if not data_type_name:
+            raise SapioException("Unable to create a data record link without a data type name. "
+                                 "Only a record ID was provided.")
+        return self.base_url + f"/#dataType={data_type_name};recordId={record_id};view=dataRecord"
+
+    def experiment(self, experiment: ExperimentIdentifier) -> str:
+        """
+        :param experiment: An object that can be used to identify an experiment in the system, be that an experiment
+            object, experiment protocol, or a notebook ID.
+        :return: A URL for navigating to the input experiment.
+        """
+        return self.base_url + f"/#notebookExperimentId={AliasUtil.to_notebook_id(experiment)};view=eln"

sapiopycommons/general/time_util.py

@@ -1,8 +1,12 @@
+from __future__ import annotations
+
 import time
 from datetime import datetime
 
 import pytz
 
+from sapiopycommons.general.exceptions import SapioException
+
 __timezone = None
 """The default timezone. Use TimeUtil.set_default_timezone in a global context before making use of TimeUtil."""
 
@@ -137,3 +141,39 @@ class TimeUtil:
             return True
         except Exception:
             return False
+
+
+class DateRange:
+    start: int | None
+    end: int | None
+
+    @staticmethod
+    def from_string(value: str | None) -> DateRange:
+        """
+        Construct a DateRange object from a string. The field value of date range fields is a string of the form
+        <start timestamp>/<end timestamp>.
+
+        :param value: A date range field value.
+        :return: A DateRange object matching the input field value.
+        """
+        if not value:
+            return DateRange(None, None)
+        values: list[str] = value.split("/")
+        return DateRange(int(values[0]), int(values[1]))
+
+    def __init__(self, start: int | None, end: int | None):
+        """
+        :param start: The timestamp for the start of the date range.
+        :param end: The timestamp for the end of the date rate.
+        """
+        if (start and end is None) or (end and start is None):
+            raise SapioException("Both start and end values must be present in a date range.")
+        if start and end and end < start:
+            raise SapioException(f"End timestamp {end} is earlier than the start timestamp {start}.")
+        self.start = start
+        self.end = end
+
+    def __str__(self) -> str | None:
+        if not self.start and not self.end:
+            return None
+        return f"{self.start}/{self.end}"