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

sapiopycommons/files/file_bridge_handler.py

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+from abc import abstractmethod, ABC
+
+from sapiopycommons.files.file_bridge import FileBridge
+from sapiopylib.rest.User import SapioUser
+from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
+
+
+class FileBridgeHandler:
+    """
+    The FileBridgeHandler provides caching of the results of file bridge endpoint calls while also containing quality
+    of life functions for common file bridge actions.
+    """
+    user: SapioUser
+    __bridge: str
+    __file_cache: dict[str, bytes]
+    """A cache of file paths to file bytes."""
+    __files: dict[str, File]
+    """A cache of file paths to File objects."""
+    __dir_cache: dict[str, list[str]]
+    """A cache of directory file paths to the names of the files or nested directories within it."""
+    __directories: dict[str, Directory]
+    """A cache of directory file paths to Directory objects."""
+
+    def __init__(self, context: SapioWebhookContext | SapioUser, 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
+        self.__bridge = bridge_name
+        self.__file_cache = {}
+        self.__files = {}
+        self.__dir_cache = {}
+        self.__directories = {}
+
+    @property
+    def connection_name(self) -> str:
+        return self.__bridge
+
+    def clear_caches(self) -> None:
+        """
+        Clear the file and directory caches of this handler.
+        """
+        self.__file_cache.clear()
+        self.__files.clear()
+        self.__dir_cache.clear()
+        self.__directories.clear()
+
+    def read_file(self, file_path: str, base64_decode: bool = True) -> bytes:
+        """
+        Read a file from FileBridge. The bytes of the given file will be cached so that any subsequent reads of this
+        file will not make an additional webservice call.
+
+        :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.
+        :return: The bytes of the file.
+        """
+        if file_path in self.__file_cache:
+            return self.__file_cache[file_path]
+        file_bytes: bytes = FileBridge.read_file(self.user, self.__bridge, file_path, base64_decode)
+        self.__file_cache[file_path] = file_bytes
+        return file_bytes
+
+    def write_file(self, file_path: str, file_data: bytes | str) -> None:
+        """
+        Write a file to FileBridge. The bytes of the given file will be cached so that any subsequent reads of this
+        file will not make an additional webservice call.
+
+        :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.
+        """
+        FileBridge.write_file(self.user, self.__bridge, file_path, file_data)
+        self.__file_cache[file_path] = file_data if isinstance(file_data, bytes) else file_data.encode()
+
+        # Find the directory path to this file and the name of the file. Add the file name to the cached list of
+        # files for the directory, assuming we have this directory cached and the file isn't already in it.
+        last_slash: int = file_path.rfind("/")
+        dir_path: str = file_path[:last_slash]
+        file_name: str = file_path[last_slash + 1:]
+        if dir_path in self.__dir_cache and file_path not in self.__dir_cache[dir_path]:
+            self.__dir_cache[dir_path].append(file_name)
+
+    def delete_file(self, file_path: str) -> None:
+        """
+        Delete an existing file in FileBridge. If this file is in the cache, it will also be deleted from the cache.
+
+        :param file_path: The path to the file to delete.
+        """
+        FileBridge.delete_file(self.user, self.__bridge, file_path)
+        if file_path in self.__file_cache:
+            self.__file_cache.pop(file_path)
+        if file_path in self.__files:
+            self.__files.pop(file_path)
+
+    def list_directory(self, file_path: str) -> list[str]:
+        """
+        List the contents of a FileBridge directory. The contents of this directory will be cached so that any
+        subsequent lists of this directory will not make an additional webservice call.
+
+        :param file_path: The path to read the directory from.
+        :return: A list of names of files and folders in the directory.
+        """
+        if file_path in self.__dir_cache:
+            return self.__dir_cache[file_path]
+        files: list[str] = FileBridge.list_directory(self.user, self.__bridge, file_path)
+        self.__dir_cache[file_path] = files
+        return files
+
+    def create_directory(self, file_path: str) -> None:
+        """
+        Create a new directory in FileBridge. This new directory will be added to the cache as empty so that listing
+        the same directory does not make an additional webservice call.
+
+        :param file_path: The path to create the directory at. If a directory already exists at the given path then an
+            exception is raised.
+        """
+        FileBridge.create_directory(self.user, self.__bridge, file_path)
+        # This directory was just created, so we know it's empty.
+        self.__dir_cache[file_path] = []
+
+    def delete_directory(self, file_path: str) -> None:
+        """
+        Delete an existing directory in FileBridge. If this directory is in the cache, it will also be deleted
+        from the cache.
+
+        :param file_path: The path to the directory to delete.
+        """
+        FileBridge.delete_directory(self.user, self.__bridge, file_path)
+        if file_path in self.__dir_cache:
+            self.__dir_cache.pop(file_path)
+        if file_path in self.__directories:
+            self.__directories.pop(file_path)
+
+    def is_file(self, file_path: str) -> bool:
+        """
+        Determine if the given file path points to a file or a directory. This is achieved by trying to call
+        list_directory on the given file path. If an exception is thrown, that's because the function was called
+        on a file. If no exception is thrown, then we know that this is a directory, and we have now also cached
+        the contents of that directory if it wasn't cached already.
+
+        :param file_path: A file path.
+        :return: True if the file path points to a file. False if it points to a directory.
+        """
+        try:
+            self.list_directory(file_path)
+            return False
+        except Exception:
+            return True
+
+    def move_file(self, move_from: str, move_to: str, old_name: str, new_name: str | None = None) -> None:
+        """
+        Move a file from one location to another within File Bridge. This is done be reading the file into memory,
+        writing a copy of the file in the new location, then deleting the original file.
+
+        :param move_from: The path to the current location of the file.
+        :param move_to: The path to move the file to.
+        :param old_name: The current name of the file.
+        :param new_name: The name that the file should have after it is moved. if this is not provided, then the new
+            name will be the same as the old name.
+        """
+        if not new_name:
+            new_name = old_name
+
+        # Read the file into memory.
+        file_bytes: bytes = self.read_file(move_from + "/" + old_name)
+        # Write the file into the new location.
+        self.write_file(move_to + "/" + new_name, file_bytes)
+        # Delete the file from the old location. We do this last in case the write call fails.
+        self.delete_file(move_from + "/" + old_name)
+
+    def get_file_object(self, file_path: str) -> File:
+        """
+        Get a File object from a file path. This object can be used to get the contents of the file at this path
+        and traverse up the file hierarchy to the directory that the file is contained within.
+
+        There is no guarantee that this file actually exists within the current file bridge connection when it is
+        constructed. If the file doesn't exist, then retrieving its contents will fail.
+
+        :param file_path: A file path.
+        :return: A File object constructed form the given file path.
+        """
+        if file_path in self.__files:
+            return self.__files[file_path]
+        file = File(self, file_path)
+        self.__files[file_path] = file
+        return file
+
+    def get_directory_object(self, file_path: str) -> Directory | None:
+        """
+        Get a Directory object from a file path. This object can be used to traverse up and down the file hierarchy
+        by going up to the parent directory that this directory is contained within or going down to the contents of
+        this directory.
+
+        There is no guarantee that this directory actually exists within the current file bridge connection when it is
+        constructed. If the directory doesn't exist, then retrieving its contents will fail.
+
+        :param file_path: A file path.
+        :return: A Directory object constructed form the given file path.
+        """
+        if file_path is None:
+            return None
+        if file_path in self.__directories:
+            return self.__directories[file_path]
+        directory = Directory(self, file_path)
+        self.__directories[file_path] = directory
+        return directory
+
+
+class FileBridgeObject(ABC):
+    """
+    A FileBridgeObject is either a file or a directory that is contained within file bridge. Every object has a
+    name and a parent directory that it is contained within (unless the object is located in the bridge root, in
+    which case the parent is None). From the name and the parent, a path can be constructed to that object.
+    """
+    _handler: FileBridgeHandler
+    name: str
+    parent: Directory | None
+
+    def __init__(self, handler: FileBridgeHandler, file_path: str):
+        self._handler = handler
+
+        name, root = split_path(file_path)
+        self.name = name
+        self.parent = handler.get_directory_object(root)
+
+    @abstractmethod
+    def is_file(self) -> bool:
+        """
+        :return: True if this object is a file. False if it is a directory.
+        """
+        pass
+
+    def get_path(self) -> str:
+        """
+        :return: The file path that leads to this object.
+        """
+        if self.parent is None:
+            return self.name
+        return self.parent.get_path() + "/" + self.name
+
+
+class File(FileBridgeObject):
+    def __init__(self, handler: FileBridgeHandler, file_path: str):
+        """
+        :param handler: A FileBridgeHandler for the connection that this file came from.
+        :param file_path: The path to this file.
+        """
+        super().__init__(handler, file_path)
+
+    @property
+    def contents(self) -> bytes:
+        """
+        :return: The bytes of this file.
+            This pulls from the cache of this object's related FileBridgeHandler.
+        """
+        return self._handler.read_file(self.get_path())
+
+    def is_file(self) -> bool:
+        return True
+
+
+class Directory(FileBridgeObject):
+    def __init__(self, handler: FileBridgeHandler, file_path: str):
+        """
+        :param handler: A FileBridgeHandler for the connection that this directory came from.
+        :param file_path: The path to this directory.
+        """
+        super().__init__(handler, file_path)
+
+    @property
+    def contents(self) -> dict[str, FileBridgeObject]:
+        """
+        :return: A dictionary of object names to the objects (Files or Directories) contained within this Directory.
+            This pulls from the cache of this object's related FileBridgeHandler.
+        """
+        contents: dict[str, FileBridgeObject] = {}
+        path: str = self.get_path()
+        for name in self._handler.list_directory(path):
+            file_path: str = path + "/" + name
+            if self._handler.is_file(file_path):
+                contents[name] = self._handler.get_file_object(file_path)
+            else:
+                contents[name] = self._handler.get_directory_object(file_path)
+        return contents
+
+    def is_file(self) -> bool:
+        return False
+
+    def get_files(self) -> dict[str, File]:
+        """
+        :return: A mapping of file name to File for every file in this Directory.
+            This pulls from the cache of this object's related FileBridgeHandler.
+        """
+        return {x: y for x, y in self.contents.items() if y.is_file()}
+
+    def get_directories(self) -> dict[str, Directory]:
+        """
+        :return: A mapping of directory name to Directory for every directory in this Directory.
+            This pulls from the cache of this object's related FileBridgeHandler.
+        """
+        return {x: y for x, y in self.contents.items() if not y.is_file()}
+
+
+def split_path(file_path: str) -> (str, str):
+    """
+    :param file_path: A file path where directories are separated the "/" characters.
+    :return: A tuple of two strings that splits the path on its last slash. The first string is the name of the
+        file/directory at the given file path and the second string is the location to that file.
+    """
+    last_slash: int = file_path.rfind("/")
+    if last_slash == -1:
+        return file_path, None
+    return file_path[last_slash + 1:], file_path[:last_slash]

sapiopycommons/general/custom_report_util.py

@@ -3,7 +3,7 @@ from typing import Any
 
 from sapiopylib.rest.DataMgmtService import DataMgmtServer
 from sapiopylib.rest.User import SapioUser
-from sapiopylib.rest.pojo.CustomReport import ReportColumn, CustomReport
+from sapiopylib.rest.pojo.CustomReport import ReportColumn, CustomReport, CustomReportCriteria, RawReportTerm
 from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
 
 
@@ -13,7 +13,9 @@ class CustomReportUtil:
     def run_system_report(context: SapioWebhookContext | SapioUser,
                           report_name: str,
                           filters: dict[str, Iterable[Any]] | None = None,
-                          page_limit: int | None = None) -> list[dict[str, Any]]:
+                          page_limit: int | None = None,
+                          page_size: int | None = None,
+                          page_number: int | None = None) -> list[dict[str, Any]]:
         """
         Run a system report and return the results of that report as a list of dictionaries for the values of each
         column in each row.
@@ -27,26 +29,94 @@ class CustomReportUtil:
             filter on. Only those headers that both the filters and the custom report share will take effect. That is,
             any filters that have a header name that isn't in the custom report will be ignored.
         :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages.
+        :param page_size: The size of each page of results in the search. If None, the page size is set by the server.
+        :param page_number: The page number to start the search from, If None, starts on the first page.
         :return: The results of the report listed row by row, mapping each cell to the header it is under. The header
             values in the dicts are the data field names of the columns.
+            If two columns in the search have the same data field name but differing data type names, then the
+            dictionary key to the value in the column will be "DataTypeName.DataFieldName". For example, if you
+            had a Sample column with a data field name of Identifier and a Request column with the same data field name,
+            then the dictionary keys for these columns would be Sample.Identifier and Request.Identifier respectively.
         """
-        results = CustomReportUtil.__exhaust_system_report(context, report_name, page_limit)
+        results: tuple = CustomReportUtil.__exhaust_system_report(context, report_name, page_limit,
+                                                                  page_size, page_number)
         columns: list[ReportColumn] = results[0]
         rows: list[list[Any]] = results[1]
+        return CustomReportUtil.__process_results(rows, columns, filters)
 
-        ret: list[dict[str, Any]] = []
-        for row in rows:
-            row_data: dict[str, Any] = {}
-            filter_row: bool = False
-            for value, column in zip(row, columns):
-                header: str = column.data_field_name
-                if filters is not None and header in filters and value not in filters.get(header):
-                    filter_row = True
-                    break
-                row_data.update({header: value})
-            if filter_row is False:
-                ret.append(row_data)
-        return ret
+    @staticmethod
+    def run_custom_report(context: SapioWebhookContext | SapioUser,
+                          report_criteria: CustomReportCriteria,
+                          filters: dict[str, Iterable[Any]] | None = None,
+                          page_limit: int | None = None,
+                          page_size: int | None = None,
+                          page_number: int | None = None) -> list[dict[str, Any]]:
+        """
+        Run a custom report and return the results of that report as a list of dictionaries for the values of each
+        column in each row.
+
+        Custom reports are constructed by the caller, specifying the report terms and the columns that will be in the
+        results. They are like advanced or predefined searches from the system, except they are constructed from
+        within the webhook instead of from within the system.
+
+        :param context: The current webhook context or a user object to send requests from.
+        :param report_criteria: The custom report criteria to run.
+        :param filters: If provided, filter the results of the report using the given mapping of headers to values to
+            filter on. Only those headers that both the filters and the custom report share will take effect. That is,
+            any filters that have a header name that isn't in the custom report will be ignored.
+            Note that this parameter is only provided for parity with the other run report functions. If you need to
+            filter the results of a search, it would likely be more beneficial to have just added a new term to the
+            input report criteria that corresponds to the filter.
+        :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages.
+        :param page_size: The size of each page of results in the search. If None, uses the value from the given report
+            criteria. If not None, overwrites the value from the given report criteria.
+        :param page_number: The page number to start the search from, If None, uses the value from the given report
+            criteria. If not None, overwrites the value from the given report criteria.
+        :return: The results of the report listed row by row, mapping each cell to the header it is under. The header
+            values in the dicts are the data field names of the columns.
+            If two columns in the search have the same data field name but differing data type names, then the
+            dictionary key to the value in the column will be "DataTypeName.DataFieldName". For example, if you
+            had a Sample column with a data field name of Identifier and a Request column with the same data field name,
+            then the dictionary keys for these columns would be Sample.Identifier and Request.Identifier respectively.
+        """
+        results: tuple = CustomReportUtil.__exhaust_custom_report(context, report_criteria, page_limit,
+                                                                  page_size, page_number)
+        columns: list[ReportColumn] = results[0]
+        rows: list[list[Any]] = results[1]
+        return CustomReportUtil.__process_results(rows, columns, filters)
+
+    @staticmethod
+    def run_quick_report(context: SapioWebhookContext | SapioUser,
+                         report_term: RawReportTerm,
+                         filters: dict[str, Iterable[Any]] | None = None,
+                         page_limit: int | None = None,
+                         page_size: int | None = None,
+                         page_number: int | None = None) -> list[dict[str, Any]]:
+        """
+        Run a quick report and return the results of that report as a list of dictionaries for the values of each
+        column in each row.
+
+        Quick reports are helpful for cases where you need to query record field values in a more complex manner than
+        the data record manager allows, but still simpler than a full-blown custom report. The columns that are returned
+        in a quick search are every visible field from the data type that corresponds to the given report term. (Fields
+        which are not marked as visible in the data designer will be excluded.)
+
+        :param context: The current webhook context or a user object to send requests from.
+        :param report_term: The raw report term to use for the quick report.
+        :param filters: If provided, filter the results of the report using the given mapping of headers to values to
+            filter on. Only those headers that both the filters and the custom report share will take effect. That is,
+            any filters that have a header name that isn't in the custom report will be ignored.
+        :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages.
+        :param page_size: The size of each page of results in the search. If None, the page size is set by the server.
+        :param page_number: The page number to start the search from, If None, starts on the first page.
+        :return: The results of the report listed row by row, mapping each cell to the header it is under. The header
+            values in the dicts are the data field names of the columns.
+        """
+        results: tuple = CustomReportUtil.__exhaust_quick_report(context, report_term, page_limit,
+                                                                 page_size, page_number)
+        columns: list[ReportColumn] = results[0]
+        rows: list[list[Any]] = results[1]
+        return CustomReportUtil.__process_results(rows, columns, filters)
 
     @staticmethod
     def get_system_report_criteria(context: SapioWebhookContext | SapioUser, report_name: str) -> CustomReport:
@@ -69,22 +139,124 @@ class CustomReportUtil:
         return report_man.run_system_report_by_name(report_name, 1, 1)
 
     @staticmethod
-    def __exhaust_system_report(context: SapioWebhookContext | SapioUser, report_name: str, page_limit: int | None = None) \
+    def __exhaust_system_report(context: SapioWebhookContext | SapioUser,
+                                report_name: str,
+                                page_limit: int | None,
+                                page_size: int | None,
+                                page_number: int | None) \
+            -> tuple[list[ReportColumn], list[list[Any]]]:
+        """
+        Given a system report, iterate over every page of the report and collect the results
+        until there are no remaining pages.
+        """
+        user: SapioUser = context if isinstance(context, SapioUser) else context.user
+        report_man = DataMgmtServer.get_custom_report_manager(user)
+
+        result = None
+        has_next_page: bool = True
+        rows: list[list[Any]] = []
+        cur_page: int = 1
+        while has_next_page and (not page_limit or cur_page < page_limit):
+            result = report_man.run_system_report_by_name(report_name, page_size, page_number)
+            page_size = result.page_size
+            page_number = result.page_number
+            has_next_page = result.has_next_page
+            rows.extend(result.result_table)
+            cur_page += 1
+        return result.column_list, rows
+
+    @staticmethod
+    def __exhaust_custom_report(context: SapioWebhookContext | SapioUser,
+                                report: CustomReportCriteria,
+                                page_limit: int | None,
+                                page_size: int | None,
+                                page_number: int | None) \
+            -> tuple[list[ReportColumn], list[list[Any]]]:
+        """
+        Given a custom report, iterate over every page of the report and collect the results
+        until there are no remaining pages.
+        """
+        user: SapioUser = context if isinstance(context, SapioUser) else context.user
+        report_man = DataMgmtServer.get_custom_report_manager(user)
+
+        result = None
+        if page_size is not None:
+            report.page_size = page_size
+        if page_number is not None:
+            report.page_number = page_number
+        has_next_page: bool = True
+        rows: list[list[Any]] = []
+        cur_page: int = 1
+        while has_next_page and (not page_limit or cur_page < page_limit):
+            result = report_man.run_custom_report(report)
+            report.page_size = result.page_size
+            report.page_number = result.page_number
+            has_next_page = result.has_next_page
+            rows.extend(result.result_table)
+            cur_page += 1
+        return result.column_list, rows
+
+    @staticmethod
+    def __exhaust_quick_report(context: SapioWebhookContext | SapioUser,
+                               report_term: RawReportTerm,
+                               page_limit: int | None,
+                               page_size: int | None,
+                               page_number: int | None) \
             -> tuple[list[ReportColumn], list[list[Any]]]:
+        """
+        Given a quick report, iterate over every page of the report and collect the results
+        until there are no remaining pages.
+        """
         user: SapioUser = context if isinstance(context, SapioUser) else context.user
         report_man = DataMgmtServer.get_custom_report_manager(user)
 
-        report = None
-        page_size: int | None = None
-        page_number: int | None = None
+        result = None
         has_next_page: bool = True
         rows: list[list[Any]] = []
         cur_page: int = 1
         while has_next_page and (not page_limit or cur_page < page_limit):
-            report = report_man.run_system_report_by_name(report_name, page_size, page_number)
-            page_size = report.page_size
-            page_number = report.page_number
-            has_next_page = report.has_next_page
-            rows.extend(report.result_table)
+            result = report_man.run_quick_report(report_term, page_size, page_number)
+            page_size = result.page_size
+            page_number = result.page_number
+            has_next_page = result.has_next_page
+            rows.extend(result.result_table)
             cur_page += 1
-        return report.column_list, rows
+        return result.column_list, rows
+
+    @staticmethod
+    def __process_results(rows: list[list[Any]], columns: list[ReportColumn],
+                          filters: dict[str, Iterable[Any]] | None) -> list[dict[str, Any]]:
+        """
+        Given the results of a report as a list of row values and the report's columns, combine these lists to
+        result in a singular list of dictionaries for each row in the results.
+
+        If any filter criteria has been provided, also use that to filter the row.
+        """
+        # It may be the case that two columns have the same data field name but differing data type names.
+        # If this occurs, then we need to be able to differentiate these columns in the resulting dictionary.
+        prepend_dt: set[str] = set()
+        encountered_names: list[str] = []
+        for column in columns:
+            field_name: str = column.data_field_name
+            if field_name in encountered_names:
+                prepend_dt.add(field_name)
+            else:
+                encountered_names.append(field_name)
+
+        ret: list[dict[str, Any]] = []
+        for row in rows:
+            row_data: dict[str, Any] = {}
+            filter_row: bool = False
+            for value, column in zip(row, columns):
+                header: str = column.data_field_name
+                # If two columns share the same data field name, prepend the data type name of the column to the
+                # data field name.
+                if header in prepend_dt:
+                    header = column.data_type_name + "." + header
+                if filters is not None and header in filters and value not in filters.get(header):
+                    filter_row = True
+                    break
+                row_data.update({header: value})
+            if filter_row is False:
+                ret.append(row_data)
+        return ret