sapiopycommons 2024.5.24a240__py3-none-any.whl → 2024.6.6a248__py3-none-any.whl

sapiopycommons/callbacks/callback_util.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import io
 from typing import Any
 
@@ -9,7 +11,7 @@ from sapiopylib.rest.pojo.DataRecord import DataRecord
 from sapiopylib.rest.pojo.datatype.DataType import DataTypeDefinition
 from sapiopylib.rest.pojo.datatype.DataTypeLayout import DataTypeLayout
 from sapiopylib.rest.pojo.datatype.FieldDefinition import AbstractVeloxFieldDefinition, VeloxStringFieldDefinition, \
-    VeloxIntegerFieldDefinition, VeloxDoubleFieldDefinition
+    VeloxIntegerFieldDefinition, VeloxDoubleFieldDefinition, FieldDefinitionParser
 from sapiopylib.rest.pojo.webhook.ClientCallbackRequest import OptionDialogRequest, ListDialogRequest, \
     FormEntryDialogRequest, InputDialogCriteria, TableEntryDialogRequest, ESigningRequestPojo, \
     DataRecordSelectionRequest, DataRecordDialogRequest, InputSelectionRequest, FilePromptRequest, \
@@ -209,15 +211,15 @@ class CallbackUtil:
         type_def: DataTypeDefinition = self.dt_cache.get_data_type(data_type)
         field_defs: dict[str, AbstractVeloxFieldDefinition] = self.dt_cache.get_fields_for_type(data_type)
 
+        # Make everything visible, because presumably the caller gave a field name because they want it to be seen.
+        modifier = FieldModifier(visible=True, editable=editable)
+
         # Build the form using only those fields that are desired.
         builder = FormBuilder(data_type, type_def.display_name, type_def.plural_display_name)
         for field_name in fields:
             field_def = field_defs.get(field_name)
             if field_def is None:
                 raise SapioException(f"No field of name \"{field_name}\" in field definitions of type \"{data_type}\"")
-            if editable is not None:
-                field_def.editable = editable
-            field_def.visible = True
             if hasattr(field_def, "default_value"):
                 field_def.default_value = record.get_field_value(field_name)
             column: int = 0
@@ -226,7 +228,7 @@ class CallbackUtil:
                 position = column_positions.get(field_name)
                 column = position[0]
                 span = position[1]
-            builder.add_field(field_def, column, span)
+            builder.add_field(modifier.modify_field(field_def), column, span)
 
         request = FormEntryDialogRequest(title, msg, builder.get_temporary_data_type())
         response: FieldMap | None = self.callback.show_form_entry_dialog(request)
@@ -259,7 +261,7 @@ class CallbackUtil:
         :param field_name: The name and display name of the string field.
         :param default_value: The default value to place into the string field, if any.
         :param max_length: The max length of the string value. If not provided, uses the length of the default value.
-            If neither this or a default value are not provided, defaults to 100 characters.
+            If neither this nor a default value are provided, defaults to 100 characters.
         :param editable: Whether the field is editable by the user.
         :param kwargs: Any additional keyword arguments to pass to the field definition.
         :return: The string that the user input into the dialog.
@@ -346,9 +348,13 @@ class CallbackUtil:
         if plural_display_name is None:
             plural_display_name = display_name + "s"
 
+        # Key fields display their columns in order before all non-key fields.
+        # Unmark key fields so that the column order is respected exactly as the caller provides it.
+        modifier = FieldModifier(key_field=False)
+
         builder = FormBuilder(data_type, display_name, plural_display_name)
-        for column in fields:
-            builder.add_field(column)
+        for field in fields:
+            builder.add_field(modifier.modify_field(field))
 
         request = TableEntryDialogRequest(title, msg, builder.get_temporary_data_type(), values)
         response: list[FieldMap] | None = self.callback.show_table_entry_dialog(request)
@@ -364,8 +370,9 @@ class CallbackUtil:
                             editable: bool | None = True) -> list[FieldMap]:
         """
         Create a table dialog where the user may input data into the fields of the table. The table is constructed from
-        a given list of records. Provided field names must match fields on the definition of the data type of the given
-        records. The fields that are displayed will have their default value be that of the fields on the given records.
+        a given list of records of a singular type. Provided field names must match fields on the definition of the data
+        type of the given records. The fields that are displayed will have their default value be that of the fields on
+        the given records.
 
         Makes webservice calls to get the data type definition and fields of the given records if they weren't
         previously cached.
@@ -390,25 +397,181 @@ class CallbackUtil:
         type_def: DataTypeDefinition = self.dt_cache.get_data_type(data_type)
         field_defs: dict[str, AbstractVeloxFieldDefinition] = self.dt_cache.get_fields_for_type(data_type)
 
+        # Key fields display their columns in order before all non-key fields.
+        # Unmark key fields so that the column order is respected exactly as the caller provides it.
+        # Also make everything visible, because presumably the caller gave a field name because they want it to be seen.
+        modifier = FieldModifier(visible=True, key_field=False, editable=editable)
+
         # Build the form using only those fields that are desired.
         builder = FormBuilder(data_type, type_def.display_name, type_def.plural_display_name)
         for field_name in fields:
             field_def = field_defs.get(field_name)
             if field_def is None:
                 raise SapioException(f"No field of name \"{field_name}\" in field definitions of type \"{data_type}\"")
-            if editable is not None:
-                field_def.editable = editable
-            field_def.visible = True
-            # Key fields display their columns in order before all non-key fields.
-            # Unmark key fields so that the column order is respected exactly as the caller provides it.
-            field_def.key_field = False
-            builder.add_field(field_def)
+            builder.add_field(modifier.modify_field(field_def))
 
         request = TableEntryDialogRequest(title, msg, builder.get_temporary_data_type(), field_map_list)
         response: list[FieldMap] | None = self.callback.show_table_entry_dialog(request)
         if response is None:
             raise SapioUserCancelledException()
         return response
+
+    def multi_type_table_dialog(self,
+                                title: str,
+                                msg: str,
+                                fields: list[(str, str) | AbstractVeloxFieldDefinition],
+                                row_contents: list[list[SapioRecord | FieldMap]],
+                                *,
+                                default_modifier: FieldModifier | None = None,
+                                field_modifiers: dict[str, FieldModifier] | None = None,
+                                data_type: str = "Default",
+                                display_name: str | None = None,
+                                plural_display_name: str | None = None) -> list[FieldMap]:
+        """
+        Create a table dialog where the user may input data into the fields of the table. The table is constructed from
+        a given list of records of multiple data types or field maps. Provided field names must match with field names
+        from the data type definition of the given records. The fields that are displayed will have their default value
+        be that of the fields on the given records or field maps.
+
+        Makes webservice calls to get the data type field definitions of the given records if they weren't
+        previously cached.
+
+        :param title: The title of the dialog.
+        :param msg: The message to display in the dialog.
+        :param fields: A list of objects representing the fields in the table. This could either be a two-element tuple
+            where the first element is a data type name and the second is a field name, or it could be a field
+            definition. If it is the former, a query will be made to find the field definition matching tht data type.
+            The data type names of the fields must match the data type names of the records in the row contents.
+            See the description of row_contents for what to do if you want to construct a field that pulls from a field
+            map.
+            If two fields share the same field name, an exception will be thrown. This is even true in the case where
+            the data type name of the fields is different. If you wish to display two fields from two data types with
+            the same name, then you must provide a FieldModifier for at least one of the fields where prepend_data_type
+            is True in order to make that field's name unique again. Note that if you do this for a field, the mapping
+            of record to field name will use the unedited field name, but the return results of this function will
+            use the edited field name in the results dictionary for a row.
+        :param row_contents: A list where each element is another list representing the records or a field map that will
+            be used to populate the columns of the table. If the data type of a given record doesn't match any of the
+            data type names of the given fields, then it will not be used.
+            This list can contain up to one field map, which are fields not tied to a record. This is so that you can
+            create abstract field definition not tied to a specific record in the system. If you want to define an
+            abstract field that pulls from the field map in the row contents, then you must set the data type name to
+            Default.
+            If a record of a given data type appears more than once in one of the inner-lists of the row contents, or
+            there is more than one field map, then an exception will be thrown, as there is no way of distinguishing
+            which record should be used for a field, and not all fields could have their values combined across multiple
+            records.
+            The row contents may have an inner-list which is missing a record of a data type that matches one of the
+            fields. In this case, the field value for that row under that column will be null.
+            The inner-list does not need to be sorted in any way, as this function will map the inner-list contents to
+            fields as necessary.
+            The inner-list may contain null elements; these will simply be discarded by this function.
+        :param default_modifier: A default field modifier that will be applied to the given fields. This can be used to
+            make field definitions from the system behave differently than their system values. If this value is None,
+            then a default field modifier is created that causes all specified fields to be both visible and not key
+            fields. (Key fields get displayed first before any non-key fields in tables, so the key field setting is
+            disabled by default in order to have the columns in the table respect the order of the fields as they are
+            provided to this function.)
+        :param field_modifiers: A mapping of data field name to field modifier for changes that should be applied to
+            the matching field. If a data field name is not present in the provided dict, or the provided dictionary is
+            None, then the default modifier will be used.
+        :param data_type: The data type name for the temporary data type that will be created for this table.
+        :param display_name: The display name for the temporary data type. If not provided, defaults to the data type
+            name.
+        :param plural_display_name: The plural display name for the temporary data type. If not provided, defaults to
+            the display name + "s".
+        :return: A list of dictionaries mapping the data field names of the given field definitions to the response
+            value from the user for that field for each row.
+        """
+        # Set the default modifier to make all fields visible and not key if no default was provided.
+        if default_modifier is None:
+            default_modifier = FieldModifier(visible=True, key_field=False)
+        # To make things simpler, treat null field modifiers as an empty dict.
+        if field_modifiers is None:
+            field_modifiers = {}
+
+        # Construct the final fields list from the possible field objects.
+        final_fields: list[AbstractVeloxFieldDefinition] = []
+        # Keep track of whether any given field name appears more than once, as two fields could have the same
+        # field name but different data types. In this case, the user should provide a field modifier or field
+        # definition that changes one of the field names.
+        field_names: list[str] = []
+        for field in fields:
+            # Find the field definition for this field object.
+            if isinstance(field, tuple):
+                field_def: AbstractVeloxFieldDefinition = self.dt_cache.get_fields_for_type(field[0]).get(field[1])
+            elif isinstance(field, AbstractVeloxFieldDefinition):
+                field_def: AbstractVeloxFieldDefinition = field
+            else:
+                raise SapioException("Unrecognized field object.")
+
+            # Locate the modifier for this field and store the modified field.
+            name: str = field_def.data_field_name
+            modifier: FieldModifier = field_modifiers.get(name, default_modifier)
+            field_def: AbstractVeloxFieldDefinition = modifier.modify_field(field_def)
+            final_fields.append(field_def)
+
+            # Verify that this field name isn't a duplicate.
+            # The field name may have changed due to the modifier.
+            name: str = field_def.data_field_name
+            if name in field_names:
+                raise SapioException(f"The field name \"{name}\" appears more than once in the given fields. "
+                                     f"If you have provided two fields with the same name but different data types, "
+                                     f"consider providing a FieldModifier where prepend_data_type is true for one of "
+                                     f"the fields so that the field names will be different.")
+            field_names.append(name)
+
+        # Get the values for each row.
+        values: list[dict[str, Any]] = []
+        for row in row_contents:
+            # The final values for this row:
+            row_values: dict[str, Any] = {}
+
+            # Map the records for this row by their data type. If a field map is provided, its data type is Default.
+            row_records: dict[str, SapioRecord | FieldMap] = {}
+            for rec in row:
+                # Toss out null elements.
+                if rec is None:
+                    continue
+                # Map records to their data type name. Map field maps to Default.
+                dt: str = "Default" if isinstance(rec, dict) else rec.data_type_name
+                # Warn if the same data type name appears more than once.
+                if dt in row_records:
+                    raise SapioException(f"The data type \"{dt}\" appears more than once in the given row contents.")
+                row_records[dt] = rec
+
+            # Get the field values from the above records.
+            for field in final_fields:
+                # Find the object that corresponds to this field given its data type name.
+                record: SapioRecord | FieldMap | None = row_records.get(field.data_type_name)
+                # This could be either a record, a field map, or null. Convert any records to field maps.
+                if not isinstance(record, dict) and record is not None:
+                    record: FieldMap | None = AliasUtil.to_field_map_lists([record])[0]
+
+                # Find out if this field had its data type prepended to it. If this is the case, then we need to find
+                # the true data field name before retrieving the value from the field map.
+                name: str = field.data_field_name
+                if field_modifiers.get(name, default_modifier).prepend_data_type is True:
+                    name = name.split(".")[1]
+
+                # Set the value for this particular field.
+                row_values[field.data_field_name] = record.get(name) if record else None
+            values.append(row_values)
+
+        if display_name is None:
+            display_name = data_type
+        if plural_display_name is None:
+            plural_display_name = display_name + "s"
+
+        builder = FormBuilder(data_type, display_name, plural_display_name)
+        for field in final_fields:
+            builder.add_field(field)
+
+        request = TableEntryDialogRequest(title, msg, builder.get_temporary_data_type(), values)
+        response: list[FieldMap] | None = self.callback.show_table_entry_dialog(request)
+        if response is None:
+            raise SapioUserCancelledException()
+        return response
     
     def record_view_dialog(self,
                            title: str,
@@ -521,17 +684,18 @@ class CallbackUtil:
         type_def: DataTypeDefinition = self.dt_cache.get_data_type(data_type)
         field_defs: dict[str, AbstractVeloxFieldDefinition] = self.dt_cache.get_fields_for_type(data_type)
 
+        # Key fields display their columns in order before all non-key fields.
+        # Unmark key fields so that the column order is respected exactly as the caller provides it.
+        # Also make everything visible, because presumably the caller give a field name because they want it to be seen.
+        modifier = FieldModifier(visible=True, key_field=False)
+
         # Build the form using only those fields that are desired.
         field_def_list: list = []
         for field_name in fields:
             field_def = field_defs.get(field_name)
             if field_def is None:
                 raise SapioException(f"No field of name \"{field_name}\" in field definitions of type \"{data_type}\"")
-            field_def.visible = True
-            # Key fields display their columns in order before all non-key fields.
-            # Unmark key fields so that the column order is respected exactly as the caller provides it.
-            field_def.key_field = False
-            field_def_list.append(field_def)
+            field_def_list.append(modifier.modify_field(field_def))
 
         request = DataRecordSelectionRequest(type_def.display_name, type_def.plural_display_name,
                                              field_def_list, field_map_list, msg, multi_select)
@@ -736,3 +900,73 @@ class CallbackUtil:
         """
         data = io.StringIO(file_data) if isinstance(file_data, str) else io.BytesIO(file_data)
         self.callback.send_file(file_name, False, data)
+
+
+class FieldModifier:
+    """
+    A FieldModifier can be used to update the settings of a field definition from the system.
+    """
+    prepend_data_type: bool
+    display_name: str | None
+    required: bool | None
+    editable: bool | None
+    visible: bool | None
+    key_field: bool | None
+    column_width: int | None
+
+    def __init__(self, *, prepend_data_type: bool = False,
+                 display_name: str | None = None, required: bool | None = None, editable: bool | None = None,
+                 visible: bool | None = None, key_field: bool | None = None, column_width: int | None = None):
+        """
+        If any values are given as None then that value will not be changed on the given field.
+
+        :param prepend_data_type: If true, prepends the data type name of the field to the data field name. For example,
+            if a field has a data type name X and a data field name Y, then the field name would become "X.Y". This is
+            useful for cases where you have the same field name on two different data types and want to distinguish one
+            or both of them.
+        :param display_name: Change the display name.
+        :param required: Change the required status.
+        :param editable: Change the editable status.
+        :param visible: Change the visible status.
+        :param key_field: Change the key field status.
+        :param column_width: Change the column width.
+        """
+        self.prepend_data_type = prepend_data_type
+        self.display_name = display_name
+        self.required = required
+        self.editable = editable
+        self.visible = visible
+        self.key_field = key_field
+        self.column_width = column_width
+
+    def modify_field(self, field: AbstractVeloxFieldDefinition) -> AbstractVeloxFieldDefinition:
+        """
+        Apply modifications to a given field.
+
+        :param field: The field to modify.
+        :return: A copy of the input field with the modifications applied.
+        """
+        field = copy_field(field)
+        if self.prepend_data_type is True:
+            field._data_field_name = field.data_field_name + "." + field.data_field_name
+        if self.display_name is not None:
+            field.display_name = self.display_name
+        if self.required is not None:
+            field.required = self.required
+        if self.editable is not None:
+            field.editable = self.editable
+        if self.visible is not None:
+            field.visible = self.visible
+        if self.key_field is not None:
+            field.key_field = self.key_field
+        if self.column_width is not None:
+            field.default_table_column_width = self.column_width
+        return field
+
+
+def copy_field(field: AbstractVeloxFieldDefinition) -> AbstractVeloxFieldDefinition:
+    """
+    Create a copy of a given field definition. This is used to modify field definitions from the server for existing
+    data types without also modifying the field definition in the cache.
+    """
+    return FieldDefinitionParser.to_field_definition(field.to_json())

sapiopycommons/files/file_bridge.py

@@ -16,7 +16,8 @@ class FileBridge:
         Read a file from FileBridge.
 
         :param context: The current webhook context or a user object to send requests from.
-        :param bridge_name: The name of the bridge to use.
+        :param bridge_name: The name of the bridge to use. This is the "connection name" in the
+            file bridge configurations.
         :param file_path: The path to read the file from.
         :param base64_decode: If true, base64 decode the file. Files are by default base64 encoded when retrieved from
             FileBridge.
@@ -42,7 +43,8 @@ class FileBridge:
         Write a file to FileBridge.
 
         :param context: The current webhook context or a user object to send requests from.
-        :param bridge_name: The name of the bridge to use.
+        :param bridge_name: The name of the bridge to use. This is the "connection name" in the
+            file bridge configurations.
         :param file_path: The path to write the file to. If a file already exists at the given path then the file is
             overwritten.
         :param file_data: A string or bytes of the file to be written.
@@ -63,9 +65,10 @@ class FileBridge:
         List the contents of a FileBridge directory.
 
         :param context: The current webhook context or a user object to send requests from.
-        :param bridge_name: The name of the bridge to use.
+        :param bridge_name: The name of the bridge to use. This is the "connection name" in the
+            file bridge configurations.
         :param file_path: The path to read the directory from.
-        :return: A list of name of files and folders in the directory.
+        :return: A list of names of files and folders in the directory.
         """
         sub_path = '/ext/filebridge/listDirectory'
         params = {
@@ -77,7 +80,7 @@ class FileBridge:
 
         response_body: list[str] = response.json()
         path_length = len(f"bridge://{bridge_name}/")
-        return [urllib.parse.unquote(value[path_length:]) for value in response_body]
+        return [urllib.parse.unquote(value)[path_length:] for value in response_body]
 
     @staticmethod
     def create_directory(context: SapioWebhookContext | SapioUser, bridge_name: str, file_path: str) -> None:
@@ -85,7 +88,8 @@ class FileBridge:
         Create a new directory in FileBridge.
 
         :param context: The current webhook context or a user object to send requests from.
-        :param bridge_name: The name of the bridge to use.
+        :param bridge_name: The name of the bridge to use. This is the "connection name" in the
+            file bridge configurations.
         :param file_path: The path to create the directory at. If a directory already exists at the given path then an
             exception is raised.
         """
@@ -103,7 +107,8 @@ class FileBridge:
         Delete an existing file in FileBridge.
 
         :param context: The current webhook context or a user object to send requests from.
-        :param bridge_name: The name of the bridge to use.
+        :param bridge_name: The name of the bridge to use. This is the "connection name" in the
+            file bridge configurations.
         :param file_path: The path to the file to delete.
         """
         sub_path = '/ext/filebridge/deleteFile'
@@ -111,7 +116,7 @@ class FileBridge:
             'Filepath': f"bridge://{bridge_name}/{file_path}"
         }
         user: SapioUser = context if isinstance(context, SapioUser) else context.user
-        response = user.post(sub_path, params=params)
+        response = user.delete(sub_path, params=params)
         user.raise_for_status(response)
 
     @staticmethod
@@ -120,7 +125,8 @@ class FileBridge:
         Delete an existing directory in FileBridge.
 
         :param context: The current webhook context or a user object to send requests from.
-        :param bridge_name: The name of the bridge to use.
+        :param bridge_name: The name of the bridge to use. This is the "connection name" in the
+            file bridge configurations.
         :param file_path: The path to the directory to delete.
         """
         sub_path = '/ext/filebridge/deleteDirectory'
@@ -128,5 +134,5 @@ class FileBridge:
             'Filepath': f"bridge://{bridge_name}/{file_path}"
         }
         user: SapioUser = context if isinstance(context, SapioUser) else context.user
-        response = user.post(sub_path, params=params)
+        response = user.delete(sub_path, params=params)
         user.raise_for_status(response)