sapiopycommons 2024.3.19a157__py3-none-any.whl → 2025.1.17a402__py3-none-any.whl

sapiopycommons/eln/plate_designer.py

@@ -0,0 +1,152 @@
+from sapiopylib.rest.utils.Protocols import ElnEntryStep
+from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedType
+
+from sapiopycommons.eln.experiment_handler import ExperimentHandler
+from sapiopycommons.general.aliases import SapioRecord, RecordIdentifier, AliasUtil
+from sapiopycommons.general.exceptions import SapioException
+from sapiopycommons.recordmodel.record_handler import RecordHandler
+
+PLATE_IDS_TAG: str = "MultiLayerPlating_Plate_RecordIdList"
+
+
+class PlateDesignerEntry:
+    """
+    A wrapper for 3D plate designer entries in experiments, providing functions for common actions when dealing with
+    such entries.
+    """
+    step: ElnEntryStep
+    __exp_handler: ExperimentHandler
+    __rec_handler: RecordHandler
+    __plates: list[SapioRecord] | None
+    __aliquots: list[SapioRecord] | None
+    __sources: list[SapioRecord] | None
+    __designer_elements: list[SapioRecord] | None
+    __plate_ids: list[int] | None
+
+    def __init__(self, step: ElnEntryStep, exp_handler: ExperimentHandler):
+        """
+        :param step: The ElnEntryStep that is the 3D plate designer entry.
+        :param exp_handler: An ExperimentHandler for the experiment that this entry comes from.
+        """
+        self.step = step
+        self.__exp_handler = exp_handler
+        self.__rec_handler = RecordHandler(exp_handler.context)
+        self.__plates = None
+        self.__aliquots = None
+        self.__sources = None
+        self.__designer_elements = None
+        self.__plate_ids = None
+
+    def get_plates(self, wrapper_type: type[WrappedType]) -> list[WrappedType]:
+        """
+        Get the plates that are in the designer entry.
+
+        Makes a webservice query to get the plates from the entry and caches the result for future calls. This cache
+        will be invalidated if a set_plates or add_plates call is made, requiring a new webservice call the next time
+        this function is called.
+
+        :param wrapper_type: The record model wrapper to use.
+        :return: A list of the plates in the designer entry.
+        """
+        if self.__plates is not None:
+            return self.__plates
+        self.__plates = self.__rec_handler.query_models_by_id(wrapper_type, self.__get_plate_ids())
+        return self.__plates
+
+    def set_plates(self, plates: list[RecordIdentifier]) -> None:
+        """
+        Set the plates that are in the plate designer entry. This removes any existing plates that are in the entry
+        but not in the given list.
+
+        Makes a webservice call to update the plate designer entry's entry options.
+
+        :param plates: The plates to set the plate designer entry with.
+        """
+        record_ids: list[int] = AliasUtil.to_record_ids(plates)
+        self.__set_plate_ids(record_ids)
+
+    def add_plates(self, plates: list[RecordIdentifier]) -> None:
+        """
+        Add the given plates to the plate designer entry. This preserves any existing plates that are in the entry.
+
+        Makes a webservice call to update the plate designer entry's entry options.
+
+        :param plates: The plates to add to the plate designer entry.
+        """
+        record_ids: list[int] = AliasUtil.to_record_ids(plates)
+        self.__set_plate_ids(self.__get_plate_ids() + record_ids)
+
+    def get_sources(self, wrapper_type: type[WrappedType]) -> list[WrappedType]:
+        """
+        Get the source records that were used to populate the plate designer entry's sample table. This looks for the
+        entries that the plate designer entry is dependent upon and gets their records if they match the data type name
+        of the given wrapper.
+
+        Makes a webservice call to retrieve the dependent entries if the experiment handler had not already cached it.
+        Makes another webservice call to get the records from the dependent entry and caches them for future calls.
+
+        :param wrapper_type: The record model wrapper to use.
+        :return: A list of the source records that populate the plate designer entry's sample table.
+        """
+        if self.__sources is not None:
+            return self.__sources
+
+        records: list[WrappedType] = []
+        dependent_ids: list[int] = self.step.eln_entry.dependency_set
+        for step in self.__exp_handler.get_all_steps(wrapper_type):
+            if step.get_id() in dependent_ids:
+                records.extend(self.__exp_handler.get_step_models(step, wrapper_type))
+
+        self.__sources = records
+        return self.__sources
+
+    def get_aliquots(self, wrapper_type: type[WrappedType]) -> list[WrappedType]:
+        """
+        Get the aliquots that were created from this plate designer entry upon its submission.
+
+        Makes a webservice call to retrieve the aliquots from the plate designer entry and caches them for future calls.
+
+        :param wrapper_type: The record model wrapper to use.
+        :return: A list of the aliquots created by the plate designer entry.
+        """
+        if not self.__exp_handler.step_is_submitted(self.step):
+            raise SapioException("The plate designer entry must be submitted before its aliquots can be retrieved.")
+        if self.__aliquots is not None:
+            return self.__aliquots
+        self.__aliquots = self.__exp_handler.get_step_models(self.step, wrapper_type)
+        return self.__aliquots
+
+    def get_plate_designer_well_elements(self, wrapper_type: type[WrappedType]) -> list[WrappedType]:
+        """
+        Get the plate designer well elements for the plates in the plate designer entry. These are the records in the
+        system that determine how wells are displayed on each plate in the entry.
+
+        Makes a webservice call to get the plate designer well elements of the entry and caches them for future calls.
+        This cache will be invalidated if a set_plates or add_plates call is made, requiring a new webservice call the
+        next time this function is called.
+
+        :param wrapper_type: The record model wrapper to use.
+        :return: A list of the plate designer well elements in the designer entry.
+        """
+        if self.__designer_elements is not None:
+            return self.__designer_elements
+        self.__designer_elements = self.__rec_handler.query_models(wrapper_type, "PlateRecordId",
+                                                                   self.__get_plate_ids())
+        return self.__designer_elements
+
+    def __get_plate_ids(self) -> list[int]:
+        if self.__plate_ids is not None:
+            return self.__plate_ids
+        id_tag: str = self.__exp_handler.get_step_option(self.step, PLATE_IDS_TAG)
+        if not id_tag:
+            raise SapioException("No plates in the plate designer entry")
+        self.__plate_ids = [int(x) for x in id_tag.split(",")]
+        return self.__plate_ids
+
+    def __set_plate_ids(self, record_ids: list[int]) -> None:
+        record_ids.sort()
+        self.__exp_handler.add_step_options(self.step, {PLATE_IDS_TAG: ",".join([str(x) for x in record_ids])})
+        self.__plate_ids = record_ids
+        # The plates and designer elements caches have been invalidated.
+        self.__plates = None
+        self.__designer_elements = None

sapiopycommons/files/complex_data_loader.py

@@ -0,0 +1,31 @@
+import io
+
+from sapiopylib.rest.User import SapioUser
+
+from sapiopycommons.general.aliases import UserIdentifier, AliasUtil
+
+
+class CDL:
+    @staticmethod
+    def load_cdl(context: UserIdentifier, config_name: str, file_name: str, file_data: bytes | str) \
+            -> list[int]:
+        """
+        Create data records from a file using one of the complex data loader (CDL) configurations in the system.
+
+        :param context: The current webhook context or a user object to send requests from.
+        :param config_name: The name of the CDL configuration to run.
+        :param file_name: The name of the file being read by the CDL.
+        :param file_data: A string or bytes of the file to be read by the CDL.
+        :return: A list of the record IDs of the data records created by the CDL.
+        """
+        sub_path = "/ext/cdl/load"
+        params = {
+            "configName": config_name,
+            "fileName": file_name
+        }
+        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)
+        # The response content is returned as bytes for a comma separated string of record IDs.
+        return [int(x) for x in bytes.decode(response.content).split(",")]

sapiopycommons/files/file_bridge.py

@@ -1,20 +1,55 @@
 import base64
 import io
 import urllib.parse
+from typing import Any
 
 from requests import Response
-from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
+from sapiopylib.rest.User import SapioUser
+
+from sapiopycommons.general.aliases import UserIdentifier, AliasUtil
+
+
+# FR-47387: Add support for the metadata endpoints in FileBridge.
+class FileBridgeMetadata:
+    """
+    Metadata for a file or directory in FileBridge.
+    """
+    file_name: str
+    """The name of the file or directory."""
+    is_file: bool
+    """True if the metadata is for a file, False if it is for a directory."""
+    is_directory: bool
+    """True if the metadata is for a directory, False if it is for a file."""
+    size: int
+    """The size of the file in bytes. For directories, this value will always be zero."""
+    creation_time: int
+    """The time the file or directory was created, in milliseconds since the epoch."""
+    last_accessed_time: int
+    """The time the file or directory was last accessed, in milliseconds since the epoch."""
+    last_modified_time: int
+    """The time the file or directory was last modified, in milliseconds since the epoch."""
+
+    def __init__(self, json_dict: dict[str, Any]):
+        self.file_name = json_dict['fileName']
+        self.is_file = json_dict['isFile']
+        self.is_directory = json_dict['isDirectory']
+        self.size = json_dict['size']
+        self.creation_time = json_dict['creationTime']
+        self.last_accessed_time = json_dict['lastAccessTime']
+        self.last_modified_time = json_dict['lastModifiedTime']
 
 
 # FR-46064 - Initial port of PyWebhookUtils to sapiopycommons.
 class FileBridge:
     @staticmethod
-    def read_file(context: SapioWebhookContext, bridge_name: str, file_path: str, base64_decode: bool = True) -> bytes:
+    def read_file(context: UserIdentifier, bridge_name: str, file_path: str,
+                  base64_decode: bool = True) -> bytes:
         """
         Read a file from FileBridge.
 
-        :param context: The current webhook context.
-        :param bridge_name: The name of the bridge to use.
+        :param context: The current webhook context or a user object to send requests from.
+        :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.
@@ -24,8 +59,9 @@ class FileBridge:
         params = {
             'Filepath': f"bridge://{bridge_name}/{file_path}"
         }
-        response = context.user.get(sub_path, params)
-        context.user.raise_for_status(response)
+        user: SapioUser = AliasUtil.to_sapio_user(context)
+        response = user.get(sub_path, params)
+        user.raise_for_status(response)
 
         ret_val = response.content
         if base64_decode:
@@ -33,12 +69,14 @@ class FileBridge:
         return ret_val
 
     @staticmethod
-    def write_file(context: SapioWebhookContext, bridge_name: str, file_path: str, file_data: bytes | str) -> None:
+    def write_file(context: UserIdentifier, bridge_name: str, file_path: str,
+                   file_data: bytes | str) -> None:
         """
         Write a file to FileBridge.
 
-        :param context: The current webhook context.
-        :param bridge_name: The name of the bridge to use.
+        :param context: The current webhook context or a user object to send requests from.
+        :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.
@@ -47,39 +85,43 @@ class FileBridge:
         params = {
             'Filepath': f"bridge://{bridge_name}/{file_path}"
         }
-        with io.StringIO(file_data) if isinstance(file_data, str) else io.BytesIO(file_data) as data_stream:
-            # noinspection PyTypeChecker
-            response = context.user.post_data_stream(sub_path, params=params, data_stream=data_stream)
-        context.user.raise_for_status(response)
+        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, bridge_name: str, file_path: str | None = "") -> list[str]:
+    def list_directory(context: UserIdentifier, bridge_name: str,
+                       file_path: str | None = "") -> list[str]:
         """
         List the contents of a FileBridge directory.
 
-        :param context: The current webhook context.
-        :param bridge_name: The name of the bridge to use.
+        :param context: The current webhook context or a user object to send requests from.
+        :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 = {
             'Filepath': f"bridge://{bridge_name}/{file_path}"
         }
-        response: Response = context.user.get(sub_path, params=params)
-        context.user.raise_for_status(response)
+        user: SapioUser = AliasUtil.to_sapio_user(context)
+        response: Response = user.get(sub_path, params=params)
+        user.raise_for_status(response)
 
         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, 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.
 
-        :param context: The current webhook context.
-        :param bridge_name: The name of the bridge to use.
+        :param context: The current webhook context or a user object to send requests from.
+        :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.
         """
@@ -87,5 +129,87 @@ class FileBridge:
         params = {
             'Filepath': f"bridge://{bridge_name}/{file_path}"
         }
-        response = context.user.post(sub_path, params=params)
-        context.user.raise_for_status(response)
+        user: SapioUser = AliasUtil.to_sapio_user(context)
+        response = user.post(sub_path, params=params)
+        user.raise_for_status(response)
+
+    @staticmethod
+    def delete_file(context: UserIdentifier, bridge_name: str, file_path: str) -> None:
+        """
+        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. 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'
+        params = {
+            'Filepath': f"bridge://{bridge_name}/{file_path}"
+        }
+        user: SapioUser = AliasUtil.to_sapio_user(context)
+        response = user.delete(sub_path, params=params)
+        user.raise_for_status(response)
+
+    @staticmethod
+    def delete_directory(context: UserIdentifier, bridge_name: str, file_path: str) -> None:
+        """
+        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. 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'
+        params = {
+            'Filepath': f"bridge://{bridge_name}/{file_path}"
+        }
+        user: SapioUser = AliasUtil.to_sapio_user(context)
+        response = user.delete(sub_path, params=params)
+        user.raise_for_status(response)
+
+    @staticmethod
+    def file_metadata(context: UserIdentifier, bridge_name: str, file_path: str) -> FileBridgeMetadata:
+        """
+        Get metadata for a file or directory in FileBridge.
+
+        The file path may be to a directory, in which case only the metadata for that directory will be returned. If you
+        want the metadata for the contents of a directory, then use the directory_metadata function.
+
+        :param context: The current webhook context or a user object to send requests from.
+        :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 retrieve the metadata from.
+        :return: The metadata for the file.
+        """
+        sub_path = '/ext/filebridge/file/metadata'
+        params = {
+            'Filepath': f"bridge://{bridge_name}/{file_path}"
+        }
+        user: SapioUser = AliasUtil.to_sapio_user(context)
+        response = user.get(sub_path, params=params)
+        user.raise_for_status(response)
+        response_body: dict[str, Any] = response.json()
+        return FileBridgeMetadata(response_body)
+
+    @staticmethod
+    def directory_metadata(context: UserIdentifier, bridge_name: str, file_path: str) -> list[FileBridgeMetadata]:
+        """
+        Get metadata for every file or nested directory in a 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. This is the "connection name" in the
+            file bridge configurations.
+        :param file_path: The path to the directory to retrieve the metadata of the contents.
+        :return: A list of the metadata for the contents of the directory.
+        """
+        sub_path = '/ext/filebridge/directory/metadata'
+        params = {
+            'Filepath': f"bridge://{bridge_name}/{file_path}"
+        }
+        user: SapioUser = AliasUtil.to_sapio_user(context)
+        response = user.get(sub_path, params=params)
+        user.raise_for_status(response)
+        response_body: list[dict[str, Any]] = response.json()
+        return [FileBridgeMetadata(x) for x in response_body]