sapiopycommons 2024.8.15a304__py3-none-any.whl → 2024.8.20a306__py3-none-any.whl

sapiopycommons/files/file_bridge.py

@@ -4,13 +4,14 @@ import urllib.parse
 
 from requests import Response
 from sapiopylib.rest.User import SapioUser
-from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
+
+from sapiopycommons.general.aliases import UserIdentifier, AliasUtil
 
 
 # FR-46064 - Initial port of PyWebhookUtils to sapiopycommons.
 class FileBridge:
     @staticmethod
-    def read_file(context: SapioWebhookContext | SapioUser, bridge_name: str, file_path: str,
+    def read_file(context: UserIdentifier, bridge_name: str, file_path: str,
                   base64_decode: bool = True) -> bytes:
         """
         Read a file from FileBridge.
@@ -27,7 +28,7 @@ class FileBridge:
         params = {
             'Filepath': f"bridge://{bridge_name}/{file_path}"
         }
-        user: SapioUser = context if isinstance(context, SapioUser) else context.user
+        user: SapioUser = AliasUtil.to_sapio_user(context)
         response = user.get(sub_path, params)
         user.raise_for_status(response)
 
@@ -37,7 +38,7 @@ class FileBridge:
         return ret_val
 
     @staticmethod
-    def write_file(context: SapioWebhookContext | SapioUser, bridge_name: str, file_path: str,
+    def write_file(context: UserIdentifier, bridge_name: str, file_path: str,
                    file_data: bytes | str) -> None:
         """
         Write a file to FileBridge.
@@ -53,13 +54,13 @@ class FileBridge:
         params = {
             'Filepath': f"bridge://{bridge_name}/{file_path}"
         }
-        user: SapioUser = context if isinstance(context, SapioUser) else context.user
-        with io.StringIO(file_data) if isinstance(file_data, str) else io.BytesIO(file_data) as data_stream:
+        user: SapioUser = AliasUtil.to_sapio_user(context)
+        with io.BytesIO(file_data.encode() if isinstance(file_data, str) else file_data) as data_stream:
             response = user.post_data_stream(sub_path, params=params, data_stream=data_stream)
         user.raise_for_status(response)
 
     @staticmethod
-    def list_directory(context: SapioWebhookContext | SapioUser, bridge_name: str,
+    def list_directory(context: UserIdentifier, bridge_name: str,
                        file_path: str | None = "") -> list[str]:
         """
         List the contents of a FileBridge directory.
@@ -74,7 +75,7 @@ class FileBridge:
         params = {
             'Filepath': f"bridge://{bridge_name}/{file_path}"
         }
-        user: SapioUser = context if isinstance(context, SapioUser) else context.user
+        user: SapioUser = AliasUtil.to_sapio_user(context)
         response: Response = user.get(sub_path, params=params)
         user.raise_for_status(response)
 
@@ -83,7 +84,7 @@ class FileBridge:
         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:
+    def create_directory(context: UserIdentifier, bridge_name: str, file_path: str) -> None:
         """
         Create a new directory in FileBridge.
 
@@ -97,12 +98,12 @@ class FileBridge:
         params = {
             'Filepath': f"bridge://{bridge_name}/{file_path}"
         }
-        user: SapioUser = context if isinstance(context, SapioUser) else context.user
+        user: SapioUser = AliasUtil.to_sapio_user(context)
         response = user.post(sub_path, params=params)
         user.raise_for_status(response)
 
     @staticmethod
-    def delete_file(context: SapioWebhookContext | SapioUser, bridge_name: str, file_path: str) -> None:
+    def delete_file(context: UserIdentifier, bridge_name: str, file_path: str) -> None:
         """
         Delete an existing file in FileBridge.
 
@@ -115,12 +116,12 @@ class FileBridge:
         params = {
             'Filepath': f"bridge://{bridge_name}/{file_path}"
         }
-        user: SapioUser = context if isinstance(context, SapioUser) else context.user
+        user: SapioUser = AliasUtil.to_sapio_user(context)
         response = user.delete(sub_path, params=params)
         user.raise_for_status(response)
 
     @staticmethod
-    def delete_directory(context: SapioWebhookContext | SapioUser, bridge_name: str, file_path: str) -> None:
+    def delete_directory(context: UserIdentifier, bridge_name: str, file_path: str) -> None:
         """
         Delete an existing directory in FileBridge.
 
@@ -133,6 +134,6 @@ class FileBridge:
         params = {
             'Filepath': f"bridge://{bridge_name}/{file_path}"
         }
-        user: SapioUser = context if isinstance(context, SapioUser) else context.user
+        user: SapioUser = AliasUtil.to_sapio_user(context)
         response = user.delete(sub_path, params=params)
         user.raise_for_status(response)

sapiopycommons/files/file_bridge_handler.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
 from abc import abstractmethod, ABC
+from weakref import WeakValueDictionary
 
-from sapiopycommons.files.file_bridge import FileBridge
 from sapiopylib.rest.User import SapioUser
-from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
+
+from sapiopycommons.files.file_bridge import FileBridge
+from sapiopycommons.general.aliases import AliasUtil, UserIdentifier
 
 
 class FileBridgeHandler:
@@ -23,13 +25,33 @@ class FileBridgeHandler:
     __directories: dict[str, Directory]
     """A cache of directory file paths to Directory objects."""
 
-    def __init__(self, context: SapioWebhookContext | SapioUser, bridge_name: str):
+    __instances: WeakValueDictionary[str, FileBridgeHandler] = WeakValueDictionary()
+    __initialized: bool
+
+    def __new__(cls, context: UserIdentifier, bridge_name: str):
+        """
+        :param context: The current webhook context or a user object to send requests from.
+        """
+        user = AliasUtil.to_sapio_user(context)
+        key = f"{user.__hash__()}:{bridge_name}"
+        obj = cls.__instances.get(key)
+        if not obj:
+            obj = object.__new__(cls)
+            obj.__initialized = False
+            cls.__instances[key] = obj
+        return obj
+
+    def __init__(self, context: UserIdentifier, bridge_name: str):
         """
         :param context: The current webhook context or a user object to send requests from.
         :param bridge_name: The name of the bridge to communicate with. This is the "connection name" in the
             file bridge configurations.
         """
-        self.user = context if isinstance(context, SapioUser) else context.user
+        if self.__initialized:
+            return
+        self.__initialized = True
+
+        self.user = AliasUtil.to_sapio_user(context)
         self.__bridge = bridge_name
         self.__file_cache = {}
         self.__files = {}

sapiopycommons/files/file_data_handler.py

@@ -1,13 +1,10 @@
 import re
 from typing import Any, Callable, Iterable
 
-from sapiopycommons.general.exceptions import SapioException
-
-from sapiopycommons.recordmodel.record_handler import RecordHandler
-
 from sapiopycommons.general.aliases import SapioRecord
-
+from sapiopycommons.general.exceptions import SapioException
 from sapiopycommons.general.time_util import TimeUtil
+from sapiopycommons.recordmodel.record_handler import RecordHandler
 
 FilterList = Iterable[int] | range | Callable[[int, dict[str, Any]], bool] | None
 """A FilterList is an object used to determine if a row in the file data should be skipped over. This can take the

sapiopycommons/files/file_util.py

@@ -1,4 +1,6 @@
 import io
+import warnings
+import zipfile
 
 import pandas
 from numpy import dtype
@@ -21,7 +23,8 @@ class FileUtil:
     """
     @staticmethod
     def tokenize_csv(file_bytes: bytes, required_headers: list[str] | None = None, header_row_index: int | None = 0,
-                     seperator: str = ",", *, encoding: str | None = None) -> tuple[list[dict[str, str]], list[list[str]]]:
+                     seperator: str = ",", *, encoding: str | None = None, exception_on_empty: bool = True) \
+            -> tuple[list[dict[str, str]], list[list[str]]]:
         """
         Tokenize a CSV file. The provided file must be uniform. That is, if row 1 has 10 cells, all the rows in the file
         must have 10 cells. Otherwise, the Pandas parser throws a tokenizer exception.
@@ -37,6 +40,8 @@ class FileUtil:
         :param encoding: The encoding used to read the given file bytes. If not provided, uses utf-8. If your file
             contains a non-utf-8 character, then a UnicodeDecodeError will be thrown. If this happens, consider using
             ISO-8859-1 as the encoding.
+        :param exception_on_empty: Throw a user error exception if the provided file bytes result in an empty list in
+            the first element of the returned tuple.
         :return: The CSV parsed into a list of dicts where each dict is a row, mapping the headers to the cells for
             that row. Also returns a list of each row above the headers (the metadata), parsed into a list of each cell.
             If the header row index is 0 or None, this list will be empty.
@@ -49,11 +54,13 @@ class FileUtil:
         metadata: list[list[str]] = FileUtil.data_frame_to_lists(file_metadata)
         # Parse the data from the file body into a list of dicts.
         rows: list[dict[str, str]] = FileUtil.data_frame_to_dicts(file_body, required_headers, header_row_index)
+        if exception_on_empty and not rows:
+            raise SapioUserErrorException("The provided file contains no rows of information below the headers.")
         return rows, metadata
 
     @staticmethod
-    def tokenize_xlsx(file_bytes: bytes, required_headers: list[str] | None = None, header_row_index: int | None = 0) \
-            -> tuple[list[dict[str, str]], list[list[str]]]:
+    def tokenize_xlsx(file_bytes: bytes, required_headers: list[str] | None = None, header_row_index: int | None = 0,
+                      *, exception_on_empty: bool = True) -> tuple[list[dict[str, str]], list[list[str]]]:
         """
         Tokenize an XLSX file row by row.
 
@@ -64,6 +71,8 @@ class FileUtil:
             row is returned in the metadata list. If input is None, then no row is considered to be the header row,
             meaning that required headers are also ignored if any are provided. By default, the first row (0th index)
             is assumed to be the header row.
+        :param exception_on_empty: Throw a user error exception if the provided file bytes result in an empty list in
+            the first element of the returned tuple.
         :return: The XLSX parsed into a list of dicts where each dict is a row, mapping the headers to the cells for
             that row. Also returns a list of each row above the headers (the metadata), parsed into a list of each cell.
             If the header row index is 0 or None, this list will be empty.
@@ -75,6 +84,8 @@ class FileUtil:
         metadata: list[list[str]] = FileUtil.data_frame_to_lists(file_metadata)
         # Parse the data from the file body into a list of dicts.
         rows: list[dict[str, str]] = FileUtil.data_frame_to_dicts(file_body, required_headers, header_row_index)
+        if exception_on_empty and not rows:
+            raise SapioUserErrorException("The provided file contains no rows of information below the headers.")
         return rows, metadata
 
     @staticmethod
@@ -229,7 +240,7 @@ class FileUtil:
         :param file_data: The CSV file to be converted.
         :return: The bytes of the CSV file converted to an XLSX file.
         """
-        with (io.BytesIO(file_data) if isinstance(file_data, bytes) else io.StringIO(file_data)) as csv:
+        with (io.BytesIO(file_data.encode() if isinstance(file_data, str) else file_data)) as csv:
             # Setting header to false makes pandas read the CSV as-is.
             data_frame = pandas.read_csv(csv, sep=",", header=None)
 
@@ -273,6 +284,20 @@ class FileUtil:
             file_bytes: bytes = buffer.getvalue()
         return file_bytes
 
+    @staticmethod
+    def zip_files(files: dict[str, str | bytes]) -> bytes:
+        """
+        Create a zip file for a collection of files.
+
+        :param files: A dictionary of file name to file data as a string or bytes.
+        :return: The bytes for a zip file containing the input files.
+        """
+        zip_buffer: io.BytesIO = io.BytesIO()
+        with zipfile.ZipFile(zip_buffer, "w", zipfile.ZIP_DEFLATED) as zip_file:
+            for file_name, file_data in files.items():
+                zip_file.writestr(file_name, file_data)
+        return zip_buffer.getvalue()
+
     # Deprecated functions:
 
     # FR-46097 - Add write file request shorthand functions to FileUtil.
@@ -290,6 +315,8 @@ class FileUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the write request as its client callback request.
         """
+        warnings.warn("FileUtil.write_file is deprecated as of 24.5+. Use CallbackUtil.write_file instead.",
+                      DeprecationWarning)
         return SapioWebhookResult(True, client_callback_request=WriteFileRequest(file_bytes, file_name,
                                                                                  request_context))
 
@@ -306,6 +333,8 @@ class FileUtil:
         :param request_context: Context that will be returned to the webhook server in the client callback result.
         :return: A SapioWebhookResult with the write request as its client callback request.
         """
+        warnings.warn("FileUtil.write_files is deprecated as of 24.5+. Use CallbackUtil.write_file instead.",
+                      DeprecationWarning)
         return SapioWebhookResult(True, client_callback_request=MultiFileRequest(files, request_context))
 
     @staticmethod
@@ -333,6 +362,8 @@ class FileUtil:
             1 - The file name of the requested file if the user provided one.
             2 - The file bytes of the requested file if the user provided one.
         """
+        warnings.warn("FileUtil.request_file is deprecated as of 24.5+. Use CallbackUtil.request_file instead.",
+                      DeprecationWarning)
         client_callback = context.client_callback_result
         result_context: str | None = client_callback.callback_context_data if client_callback else None
         # If the user cancels, terminate the interaction.
@@ -385,6 +416,8 @@ class FileUtil:
             May also contain a result that will terminate the client interaction if the user canceled the prompt.
             1 - A dictionary that maps the file names to the file bytes for each provided file.
         """
+        warnings.warn("FileUtil.request_files is deprecated as of 24.5+. Use CallbackUtil.request_files instead.",
+                      DeprecationWarning)
         client_callback = context.client_callback_result
         result_context: str | None = client_callback.callback_context_data if client_callback else None
         # If the user cancels, terminate the interaction.
@@ -427,7 +460,7 @@ class FileUtil:
         if len(allowed_extensions) != 0:
             matches: bool = False
             for ext in allowed_extensions:
-                if file_path.endswith("." + ext):
+                if file_path.endswith("." + ext.lstrip(".")):
                     matches = True
                     break
             if matches is False:

sapiopycommons/files/file_validator.py

@@ -7,12 +7,12 @@ from sapiopylib.rest.User import SapioUser
 from sapiopylib.rest.pojo.CustomReport import RawReportTerm, RawTermOperation
 from sapiopylib.rest.pojo.datatype.FieldDefinition import VeloxIntegerFieldDefinition, VeloxStringFieldDefinition, \
     AbstractVeloxFieldDefinition
-from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
-from sapiopylib.rest.pojo.webhook.WebhookResult import SapioWebhookResult
 
 from sapiopycommons.callbacks.callback_util import CallbackUtil
 from sapiopycommons.files.file_data_handler import FileDataHandler, FilterList
+from sapiopycommons.general.aliases import UserIdentifier, AliasUtil
 from sapiopycommons.general.custom_report_util import CustomReportUtil
+from sapiopycommons.general.exceptions import SapioUserCancelledException
 from sapiopycommons.general.time_util import TimeUtil
 
 
@@ -80,10 +80,10 @@ class FileValidator:
 
         return failed_rows
 
-    def build_violation_report(self, context: SapioWebhookResult | SapioUser,
+    def build_violation_report(self, context: UserIdentifier,
                                rule_violations: dict[int, list[ValidationRule]]) -> None:
         """
-        Build a simple report of any rule violations in the file to display to the user as a table dialog.
+        Display a simple report of any rule violations in the file to the user as a table dialog.
 
         :param context: The current webhook context or a user object to send requests from.
         :param rule_violations: A dict of rule violations generated by a call to validate_file.
@@ -121,9 +121,24 @@ class FileValidator:
                         "Reason": violation.reason[:2000]
                     })
 
-        callback_util = CallbackUtil(context)
-        callback_util.table_dialog("Errors", "The following rule violations were encountered in the provided file.",
-                                   columns, rows)
+        callback = CallbackUtil(context)
+        callback.table_dialog("Errors", "The following rule violations were encountered in the provided file.",
+                              columns, rows)
+
+    def validate_and_report_errors(self, context: UserIdentifier) -> None:
+        """
+        Validate the file. If any rule violations are found, display a simple report of any rule violations in the file
+        to the user as a table dialog and throw a SapioUserCancelled exception after the user acknowledges the dialog
+        to end the webhook interaction.
+
+        Shorthand for calling validate_file() and then build_violation_report() if there are any errors.
+
+        :param context: The current webhook context or a user object to send requests from.
+        """
+        violations = self.validate_file()
+        if violations:
+            self.build_violation_report(context, violations)
+            raise SapioUserCancelledException()
 
 
 class ValidationRule:
@@ -494,7 +509,7 @@ class UniqueSystemValueRule(ColumnRule):
     data_type_name: str
     data_field_name: str
 
-    def __init__(self, context: SapioWebhookContext | SapioUser, header: str, data_type_name: str,
+    def __init__(self, context: UserIdentifier, header: str, data_type_name: str,
                  data_field_name: str):
         """
         :param context: The current webhook context or a user object to send requests from.
@@ -502,7 +517,7 @@ class UniqueSystemValueRule(ColumnRule):
         :param data_type_name: The data type name to search on.
         :param data_field_name: The data field name to search on. This is expected to be a string field.
         """
-        self.user = context.user if isinstance(context, SapioWebhookContext) else context
+        self.user = AliasUtil.to_sapio_user(context)
         self.data_type_name = data_type_name
         self.data_field_name = data_field_name
         super().__init__(header, f"This value already exists in the system.")
@@ -528,7 +543,7 @@ class ExistingSystemValueRule(ColumnRule):
     data_type_name: str
     data_field_name: str
 
-    def __init__(self, context: SapioWebhookContext | SapioUser, header: str, data_type_name: str,
+    def __init__(self, context: UserIdentifier, header: str, data_type_name: str,
                  data_field_name: str):
         """
         :param context: The current webhook context or a user object to send requests from.
@@ -536,7 +551,7 @@ class ExistingSystemValueRule(ColumnRule):
         :param data_type_name: The data type name to search on.
         :param data_field_name: The data field name to search on. This is expected to be a string field.
         """
-        self.user = context.user if isinstance(context, SapioWebhookContext) else context
+        self.user = AliasUtil.to_sapio_user(context)
         self.data_type_name = data_type_name
         self.data_field_name = data_field_name
         super().__init__(header, f"This value doesn't exist in the system.")

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: