sapiopycommons 2025.1.7rc401__py3-none-any.whl → 2025.1.20a403__py3-none-any.whl

sapiopycommons/general/aliases.py

@@ -1,50 +1,50 @@
 from collections.abc import Iterable
-from typing import Any
+from typing import Any, TypeAlias
 
 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.datatype.FieldDefinition import FieldType, AbstractVeloxFieldDefinition
 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.recordmodel.PyRecordModel import PyRecordModel
+from sapiopylib.rest.utils.recordmodel.PyRecordModel import PyRecordModel, AbstractRecordModel
 from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedRecordModel, WrappedType, WrapperField
 
 from sapiopycommons.general.exceptions import SapioException
 
-FieldValue = int | float | str | bool | None
+FieldValue: TypeAlias = int | float | str | bool | None
 """Allowable values for fields in the system."""
-RecordModel = PyRecordModel | WrappedRecordModel
+RecordModel: TypeAlias = PyRecordModel | AbstractRecordModel | WrappedRecordModel
 """Different forms that a record model could take."""
-SapioRecord = DataRecord | RecordModel
+SapioRecord: TypeAlias = DataRecord | RecordModel
 """A record could be provided as either a DataRecord, PyRecordModel, or WrappedRecordModel (WrappedType)."""
-RecordIdentifier = SapioRecord | int
+RecordIdentifier: TypeAlias = SapioRecord | int
 """A RecordIdentifier is either a record type or an integer for the record's record ID."""
-DataTypeIdentifier = SapioRecord | type[WrappedType] | str
+DataTypeIdentifier: TypeAlias = SapioRecord | type[WrappedType] | str
 """A DataTypeIdentifier is either a SapioRecord, a record model wrapper type, or a string."""
-FieldIdentifier = WrapperField | str | tuple[str, FieldType]
+FieldIdentifier: TypeAlias = AbstractVeloxFieldDefinition | 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
+FieldIdentifierKey: TypeAlias = 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
+HasFieldWrappers: TypeAlias = type[WrappedType] | WrappedRecordModel
 """An identifier for classes that have wrapper fields."""
-ExperimentIdentifier = ElnExperimentProtocol | ElnExperiment | int
+ExperimentIdentifier: TypeAlias = ElnExperimentProtocol | ElnExperiment | int
 """An ExperimentIdentifier is either an experiment protocol, experiment, or an integer for the experiment's notebook
 ID."""
-ExperimentEntryIdentifier = ElnEntryStep | ExperimentEntry | int
+ExperimentEntryIdentifier: TypeAlias = 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: TypeAlias = dict[str, FieldValue]
 """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]
+FieldIdentifierMap: TypeAlias = 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
+UserIdentifier: TypeAlias = SapioWebhookContext | SapioUser
 """An identifier for classes from which a user object can be used for sending requests."""
 
 
@@ -142,23 +142,25 @@ class AliasUtil:
     @staticmethod
     def to_data_field_name(value: FieldIdentifier) -> str:
         """
-        Convert a string or WrapperField to a data field name string.
+        Convert an object that can be used to identify a data field to a data field name string.
 
-        :param value: A string or WrapperField.
+        :param value: An object that can be used to identify a data field.
         :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
+        if isinstance(value, AbstractVeloxFieldDefinition):
+            return value.data_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.
+        Convert an iterable of objects that can be used to identify data fields to a list of data field name strings.
 
-        :param values: An iterable of strings or WrapperFields.
+        :param values: An iterable of objects that can be used to identify a data field.
         :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]
@@ -204,21 +206,32 @@ class AliasUtil:
         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(record: SapioRecord) -> FieldMap:
+        """
+        Convert a given record value to a field map. This includes the given RecordId of the given record.
+
+        :return: The field map for the input record.
+        """
+        if isinstance(record, DataRecord):
+            # noinspection PyTypeChecker
+            fields: FieldMap = record.get_fields()
+        else:
+            fields: FieldMap = record.fields.copy_to_dict()
+        fields["RecordId"] = AliasUtil.to_record_id(record)
+        return fields
+
     @staticmethod
     def to_field_map_lists(records: Iterable[SapioRecord]) -> list[FieldMap]:
         """
-        Convert a list of variables that could either be DataRecords, PyRecordModels,
-        or WrappedRecordModels to a list of their field maps.
+        Convert a list of variables that could either be DataRecords, PyRecordModels, or WrappedRecordModels
+        to a list of their field maps. This includes the given RecordId of the given records.
 
         :return: A list of field maps for the input records.
         """
         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())
+            field_map_list.append(AliasUtil.to_field_map(record))
         return field_map_list
 
     @staticmethod

sapiopycommons/general/directive_util.py

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

sapiopycommons/general/exceptions.py

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