sapiopycommons 2024.3.18a156__py3-none-any.whl → 2025.1.17a402__py3-none-any.whl

sapiopycommons/general/storage_util.py

@@ -0,0 +1,148 @@
+class StorageUtil:
+    """
+    A collection of utilities intended for converting to and from various forms of representing positions on a storage
+    unit, such as character + integer (e.g. A1), two integers (e.g. (0, 0)), or a single integer index (e.g. 1).
+    Integers are also sometimes zero-indexed and sometimes one-indexed, so both are supported.
+    """
+    @staticmethod
+    def map_index_to_coordinate(index: int, size: int, fill_by_row: bool = True, zero_indexed_input: bool = False,
+                                zero_indexed_output: bool = False, char_row_output: bool = True) \
+            -> tuple[int | str, int]:
+        """
+        Convert an index representing a position on a plate/storage unit to a coordinate pair on that plate/storage
+        unit, able to be used in row/column storage fields on records. This will output a value for any input index;
+        it is up to the caller to determine if the output will actually fit on the plate/storage unit.
+        (The index should be within the range [1 < index < rows * columns] for one-indexed values.)
+
+        By default, expects the input to be a one-indexed integer filled row-by-row with the output being a
+        character, integer pair where the output integer is one-indexed.
+
+        :param index: The index to map to a coordinate position.
+        :param size: The number of columns or rows in the plate/storage unit, depending on whether you are filling by
+            row or by column.
+        :param fill_by_row: If true, map positions row-by-row (A1, A2, A3... B1, B2...) and use the above size as the
+            number of columns in the plate/storage unit. If false, map positions column-by-column (A1, B1, C1... A2,
+            B2...) and use the above size as the number of rows.
+        :param zero_indexed_input: If true, the input index is zero-indexed. If false, then they are one-indexed.
+            This does not influence the output, only the function's understanding of the input.
+        :param zero_indexed_output: If true, the output index is zero-indexed. If false, then it is one-indexed.
+            Has no effect on the column output if the column is set to output as a character.
+        :param char_row_output: If true, the output row value is converted to a character where 0 = A, 1 = B, 25 = Z,
+            26 = AA, 27 = AB, etc. If false, then it is returned as an integer.
+        :return: A tuple representing a coordinate pair (row value, column value). The row value may be either an
+            integer or a string, while the column value is always an integer, influenced by the input parameters.
+        """
+        # If the given index isn't zero-indexed, then make it zero-indexed by subtracting one.
+        if not zero_indexed_input:
+            index -= 1
+
+        row: int = index // size
+        col: int = index % size
+
+        # If fill by row is false, then the above calculations are flipped,
+        # meaning the row is actually the column and vice versa.
+        if not fill_by_row:
+            temp = row
+            row = col
+            col = temp
+        # The column and row are zero-indexed by default. If it should be one-indexed, add one.
+        if not zero_indexed_output:
+            col += 1
+            # Only add one to the row if it won't be converted to a character.
+            if not char_row_output:
+                row += 1
+        return StorageUtil.map_index_to_char(row, True) if char_row_output else row, col
+
+    @staticmethod
+    def map_coordinate_to_index(row: int | str, col: int | str, size: int, fill_by_row: bool = True,
+                                zero_indexed_input: bool = False, zero_indexed_output: bool = False) -> int:
+        """
+        Map row and column coordinates on a plate/storage unit to the index of that position.
+
+        By default, expects the input to be provided as a character, integer pair and outputs a single row-by-row
+        one-indexed integer.
+
+        :param row: The row coordinate of the position as a string of characters from A-Z or a zero-indexed integer.
+        :param col: The column coordinate of the position as an integer which may be zero-indexed or one-indexed.
+            (This integer may be in string form, such as is the case with column fields on storable records.)
+        :param size: The number of columns or rows in the plate/storage unit, depending on whether you are filling by
+            row or by column.
+        :param fill_by_row: If true, map positions row-by-row (A1, A2, A3... B1, B2...) and use the above size as the
+            number of columns in the plate/storage unit. If false, map positions column-by-column (A1, B1, C1... A2,
+            B2...) and use the above size as the number of rows.
+        :param zero_indexed_input: If true, the input coordinates for the row and column is zero-indexed. If false,
+            then they are one-indexed. This does not influence the output, only the function's understanding of the
+            input. This also has no effect if the input row is a string.
+        :param zero_indexed_output: If true, the output index is zero-indexed. If false, then it is one-indexed.
+        :return: The index of the storage position at the input row and column.
+        """
+        # If the column was provided as a string, cast it to an int.
+        if isinstance(col, str):
+            col: int = int(col)
+        # If the input isn't zero-indexed, then make it zero-indexed.
+        if not zero_indexed_input:
+            col -= 1
+            # Only subtract from the row if it's already in integer form.
+            # If it's a string, it'll be converted to a zero-indexed integer.
+            if isinstance(row, int):
+                row -= 1
+        # If the input row is a string, convert it to a zero-indexed integer.
+        if isinstance(row, str):
+            row: int = StorageUtil.map_char_to_index(row, True)
+
+        # Convert the row and column indices to a singular index across the entire storage unit.
+        index: int = row * size + col if fill_by_row else col * size + row
+
+        # The index is zero-indexed by default. If it should be one-indexed, add one.
+        if not zero_indexed_output:
+            index += 1
+        return index
+
+    @staticmethod
+    def map_index_to_char(index: int, zero_indexed_input: bool = False) -> str:
+        """
+        Map a given base-10 integer to a base-26 value where 0 = A, 1 = B, 25 = Z, 26 = AA, 27 = AB, etc.
+        Useful for mapping the index of a row to the character(s) representing that row in a storage unit.
+        May also be used for mapping the index to an Excel sheet's columns.
+
+        By default, expects the input as a one-indexed value.
+
+        :param index: The index to map to a character.
+        :param zero_indexed_input: If true, the input index is zero-indexed. If false, then they are one-indexed.
+            This does not influence the output, only the function's understanding of the input.
+        :return: The input integer mapped to a string representing that integer's position.
+        """
+        # If the given index isn't zero-indexed, then make it zero-indexed by subtracting one.
+        if not zero_indexed_input:
+            index -= 1
+        chars: str = ""
+        while index >= 0:
+            # Add new characters to the front of the string.
+            chars = chr(ord("A") + index % 26) + chars
+            # Reduce the index by the amount accounted for by the character that was just added.
+            index = index // 26 - 1
+        return chars
+
+    @staticmethod
+    def map_char_to_index(chars: str, zero_indexed_output: bool = False) -> int:
+        """
+        Map a given base-26 value of characters to a base-10 integer where A = 0, B = 1, Z = 25, AA = 26, AB = 27, etc.
+        Useful for mapping the character(s) representing a row in a storage unit to that row's index.
+        May also be used for mapping the index of an Excel sheet's columns.
+
+        By default, provides the output as a one-indexed value.
+
+        :param chars: A string of characters to be converted to an index. Characters are expected to be uppercase
+            characters in the range A to Z.
+        :param zero_indexed_output: If true, the output index is zero-indexed. If false, then it is one-indexed.
+        :return: The input character(s) converted to an index.
+        """
+        # Reverse iterate over the characters of the string and determine the value of each individual character.
+        # The value is multiplied by the base of the character given its digit position (26^0, 26^1, etc.)
+        value: int = 0
+        for i, c in enumerate(reversed(chars)):
+            value += (ord(c) - ord("A") + 1) * (26 ** i)
+        # The character value is one-indexed by default. If it should be zero-indexed, subtract one.
+        if zero_indexed_output:
+            value -= 1
+        return value

sapiopycommons/general/time_util.py

@@ -1,8 +1,13 @@
+from __future__ import annotations
+
 import time
 from datetime import datetime
+from typing import Any
 
 import pytz
 
+from sapiopycommons.general.exceptions import SapioException
+
 __timezone = None
 """The default timezone. Use TimeUtil.set_default_timezone in a global context before making use of TimeUtil."""
 
@@ -24,7 +29,7 @@ class TimeUtil:
     with static date fields, use "UTC" as your input timezone.
     """
     @staticmethod
-    def get_default_timezone():
+    def get_default_timezone() -> Any:
         """
         Returns the timezone that TimeUtil is currently using as its default.
         """
@@ -35,6 +40,7 @@ class TimeUtil:
     def set_default_timezone(new_timezone: str | int) -> None:
         """
         Set the timezone used by TimeUtil to something new.
+
         :param new_timezone: The timezone to set the default to. A list of valid timezones can be found at
             https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. May also accept a UTC offset in seconds.
         """
@@ -42,7 +48,7 @@ class TimeUtil:
         __timezone = TimeUtil.__to_tz(new_timezone)
 
     @staticmethod
-    def __to_tz(timezone: str | int = None):
+    def __to_tz(timezone: str | int = None) -> Any:
         """
         :param timezone: Either the name of a timezone, a UTC offset in seconds, or None if the default should be used.
         :return: The timezone object to use for the given input. If the input is None, uses the default timezone.
@@ -52,16 +58,34 @@ class TimeUtil:
             # because pytz may return timezones from strings in Local Mean Time instead of a timezone with a UTC offset.
             # LMT may be a few minutes off of the actual time in that timezone right now.
             # https://stackoverflow.com/questions/35462876
-            offset: int = int(datetime.now(pytz.timezone(timezone)).utcoffset().total_seconds() / 60)
-            return pytz.FixedOffset(offset)
+            offset: int = TimeUtil.__get_timezone_offset(timezone)
+            # This function takes an offset in minutes, so divide the provided offset seconds by 60.
+            return pytz.FixedOffset(offset // 60)
         if isinstance(timezone, int):
             return pytz.FixedOffset(timezone // 60)
-        return TimeUtil.get_default_timezone()
+        if timezone is None:
+            return TimeUtil.get_default_timezone()
+        raise SapioException(f"Unhandled timezone object of type {type(timezone)}: {timezone}")
+
+    @staticmethod
+    def __get_timezone_offset(timezone: str | int | None) -> int:
+        """
+        :param timezone: Either the name of a timezone, a UTC offset in seconds, or None if the default should be used.
+        :return: The UTC offset in seconds of the provided timezone.
+        """
+        if isinstance(timezone, int):
+            return timezone
+        if isinstance(timezone, str):
+            timezone = pytz.timezone(timezone)
+        if timezone is None:
+            timezone = TimeUtil.get_default_timezone()
+        return int(datetime.now(timezone).utcoffset().total_seconds())
 
     @staticmethod
     def current_time(timezone: str | int = None) -> datetime:
         """
         The current time as a datetime object.
+
         :param timezone: The timezone to initialize the current time with. If no timezone is provided, uses the global
             timezone variable set by the TimeUtil. A list of valid timezones can be found at
             https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. May also accept a UTC offset in seconds.
@@ -80,6 +104,7 @@ class TimeUtil:
     def now_in_format(time_format: str, timezone: str | int = None) -> str:
         """
         The current time in some date format.
+
         :param time_format: The format to display the current time in. Documentation for how the time formatting works
             can be found at https://docs.python.org/3.10/library/datetime.html#strftime-and-strptime-behavior
         :param timezone: The timezone to initialize the current time with. If no timezone is provided, uses the global
@@ -89,9 +114,11 @@ class TimeUtil:
         return TimeUtil.current_time(timezone).strftime(time_format)
 
     @staticmethod
-    def millis_to_format(millis: int, time_format: str, timezone: str | int = None) -> str:
+    def millis_to_format(millis: int, time_format: str, timezone: str | int = None) -> str | None:
         """
-        Convert the input time in milliseconds to the provided format.
+        Convert the input time in milliseconds to the provided format. If None is passed to the millis parameter,
+        None will be returned
+
         :param millis: The time in milliseconds to convert from.
         :param time_format: The format to display the input time in. Documentation for how the time formatting works
             can be found at https://docs.python.org/3.10/library/datetime.html#strftime-and-strptime-behavior
@@ -99,6 +126,9 @@ class TimeUtil:
             timezone variable set by the TimeUtil. A list of valid timezones can be found at
             https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. May also accept a UTC offset in seconds.
         """
+        if millis is None:
+            return None
+
         tz = TimeUtil.__to_tz(timezone)
         return datetime.fromtimestamp(millis / 1000, tz).strftime(time_format)
 
@@ -106,6 +136,7 @@ class TimeUtil:
     def format_to_millis(time_point: str, time_format: str, timezone: str | int = None) -> int:
         """
         Convert the input time from the provided format to milliseconds.
+
         :param time_point: The time in some date/time format to convert from.
         :param time_format: The format that the time_point is in. Documentation for how the time formatting works
             can be found at https://docs.python.org/3.10/library/datetime.html#strftime-and-strptime-behavior
@@ -116,11 +147,70 @@ class TimeUtil:
         tz = TimeUtil.__to_tz(timezone)
         return int(datetime.strptime(time_point, time_format).replace(tzinfo=tz).timestamp() * 1000)
 
+    # FR-47296: Provide functions for shifting between timezones.
+    @staticmethod
+    def shift_now(to_timezone: str = "UTC", from_timezone: str | None = None) -> int:
+        """
+        Take the current time in from_timezone and output the epoch timestamp that would display that same time in
+        to_timezone. A use case for this is when dealing with static date fields to convert a provided timestamp to the
+        value necessary to display that timestamp in the same way when viewed in the static date field.
+
+        :param to_timezone: The timezone to shift to. If not provided, uses UTC.
+        :param from_timezone: The timezone to shift from. If no timezone is provided, uses the global
+            timezone variable set by the TimeUtil. A list of valid timezones can be found at
+            https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. May also accept a UTC offset in seconds.
+        :return: The epoch timestamp that would display as the same time in to_timezone as the current time in
+            from_timezone.
+        """
+        millis: int = TimeUtil.now_in_millis()
+        return TimeUtil.shift_millis(millis, to_timezone, from_timezone)
+
+    @staticmethod
+    def shift_millis(millis: int, to_timezone: str = "UTC", from_timezone: str | None = None) -> int:
+        """
+        Take a number of milliseconds for a time in from_timezone and output the epoch timestamp that would display that
+        same time in to_timezone. A use case for this is when dealing with static date fields to convert a provided
+        timestamp to the value necessary to display that timestamp in the same way when viewed in the static date field.
+
+        :param millis: The time in milliseconds to convert from.
+        :param to_timezone: The timezone to shift to. If not provided, uses UTC.
+        :param from_timezone: The timezone to shift from. If no timezone is provided, uses the global
+            timezone variable set by the TimeUtil. A list of valid timezones can be found at
+            https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. May also accept a UTC offset in seconds.
+        :return: The epoch timestamp that would display as the same time in to_timezone as the given time in
+            from_timezone.
+        """
+        to_offset: int = TimeUtil.__get_timezone_offset(to_timezone) * 1000
+        from_offset: int = TimeUtil.__get_timezone_offset(from_timezone) * 1000
+        return millis + from_offset - to_offset
+
+    @staticmethod
+    def shift_format(time_point: str, time_format: str, to_timezone: str = "UTC", from_timezone: str | None = None) \
+            -> int:
+        """
+        Take a timestamp for a time in from_timezone and output the epoch timestamp that would display that same time
+        in to_timezone. A use case for this is when dealing with static date fields to convert a provided timestamp to
+        the value necessary to display that timestamp in the same way when viewed in the static date field.
+
+        :param time_point: The time in some date/time format to convert from.
+        :param time_format: The format that the time_point is in. Documentation for how the time formatting works
+            can be found at https://docs.python.org/3.10/library/datetime.html#strftime-and-strptime-behavior
+        :param to_timezone: The timezone to shift to. If not provided, uses UTC.
+        :param from_timezone: The timezone to shift from. If no timezone is provided, uses the global
+            timezone variable set by the TimeUtil. A list of valid timezones can be found at
+            https://en.wikipedia.org/wiki/List_of_tz_database_time_zones. May also accept a UTC offset in seconds.
+        :return: The epoch timestamp that would display as the same time in to_timezone as the given time in
+            from_timezone.
+        """
+        millis: int = TimeUtil.format_to_millis(time_point, time_format, from_timezone)
+        return TimeUtil.shift_millis(millis, to_timezone, from_timezone)
+
     # FR-46154: Create a function that determines if a string matches a time format.
     @staticmethod
     def str_matches_format(time_point: str, time_format: str) -> bool:
         """
         Determine if the given string is recognized as a valid time in the given format.
+
         :param time_point: The time in some date/time format to check.
         :param time_format: The format that the time_point should be in. Documentation for how the time formatting works
             can be found at https://docs.python.org/3.10/library/datetime.html#strftime-and-strptime-behavior

sapiopycommons/multimodal/multimodal.py

@@ -0,0 +1,146 @@
+# Multimodal registration client
+from __future__ import annotations
+
+import io
+from weakref import WeakValueDictionary
+
+from databind.json import dumps, loads
+from sapiopylib.rest.User import SapioUser
+
+from sapiopycommons.general.exceptions import SapioException
+from sapiopycommons.multimodal.multimodal_data import *
+
+
+class MultiModalManager:
+    _user: SapioUser
+
+    __instances: WeakValueDictionary[SapioUser, MultiModalManager] = WeakValueDictionary()
+    __initialized: bool
+
+    def __new__(cls, user: SapioUser):
+        """
+        Observes singleton pattern per record model manager object.
+
+        :param user: The user that will make the webservice request to the application.
+        """
+        obj = cls.__instances.get(user)
+        if not obj:
+            obj = object.__new__(cls)
+            obj.__initialized = False
+            cls.__instances[user] = obj
+        return obj
+
+    def __init__(self, user:SapioUser):
+        if self.__initialized:
+            return
+        self._user = user
+        self.__initialized = True
+
+    def load_image_data(self, request: ImageDataRequestPojo) -> list[str]:
+        """
+        Loading of image data of a compound or a reaction in Sapio's unified drawing format.
+        :param request:
+        :return:
+        """
+        payload = dumps(request, ImageDataRequestPojo)
+        response = self._user.plugin_post("chemistry/request_image_data",
+                                          payload=payload, is_payload_plain_text=True)
+        self._user.raise_for_status(response)
+        return response.json()
+
+    def load_compounds(self, request: CompoundLoadRequestPojo):
+        """
+        Load compounds from the provided data here.
+        The compounds will not be registered but returned to you "the script".
+        To complete registration, you need to call register_compounds method after obtaining result.
+        """
+        payload = dumps(request, CompoundLoadRequestPojo)
+        response = self._user.plugin_post("chemistry/load",
+                                          payload=payload, is_payload_plain_text=True)
+        self._user.raise_for_status(response)
+        return loads(response.text, PyMoleculeLoaderResult)
+
+    def register_compounds(self, request: ChemRegisterRequestPojo) -> ChemCompleteImportPojo:
+        """
+        Register the filled compounds that are previously loaded via load_compounds operation.
+        """
+        payload = dumps(request, ChemRegisterRequestPojo)
+        response = self._user.plugin_post("chemistry/register",
+                                          payload=payload, is_payload_plain_text=True)
+        self._user.raise_for_status(response)
+        return loads(response.text, ChemCompleteImportPojo)
+
+    def load_reactions(self, reaction_str: str) -> PyIndigoReactionPojo:
+        """
+        Load a reaction and return the loaded reaction result.
+        :param reaction_str: A reaction string, in format of mrv, rxn, or smiles.
+        """
+        response = self._user.plugin_post("chemistry/reaction/load",
+                                          payload=reaction_str, is_payload_plain_text=True)
+        self._user.raise_for_status(response)
+        return loads(response.text, PyIndigoReactionPojo)
+
+    def register_reactions(self, reaction_str: str) -> DataRecord:
+        """
+        Register a single reaction provided.
+        Note: if the rxn has already specified a 2D coordinate, it may not be recomputed when generating record image.
+        :param reaction_str: The rxn of a reaction.
+        :return: The registered data record. This can be a record that already exists or new.
+        """
+        response = self._user.plugin_post("chemistry/reaction/register",
+                                          payload=reaction_str, is_payload_plain_text=True)
+        self._user.raise_for_status(response)
+        return loads(response.text, DataRecord)
+
+    def search_structures(self, request: ChemSearchRequestPojo) -> ChemSearchResponsePojo:
+        """
+        Perform structure search against the Sapio registries.
+        An error can be thrown as exception if search is structurally invalid.
+        :param request: The request object containing the detailed context of this search.
+        :return: The response object of the result.
+        """
+        payload = dumps(request, ChemSearchRequestPojo)
+        response = self._user.plugin_post("chemistry/search",
+                                          payload=payload, is_payload_plain_text=True)
+        self._user.raise_for_status(response)
+        return loads(response.text, ChemSearchResponsePojo)
+
+    def run_multi_sequence_alignment(self, request: MultiSequenceAlignmentRequestPojo) -> list[MultiSequenceAlignmentSeqPojo]:
+        """
+        Run a multi-sequence alignment using the specified tool and strategy.
+        :param request: The request object containing the sequences and alignment parameters. The parameters inside it can be the pojo dict of one of the options.
+        :return: The result of the multi-sequence alignment.
+        """
+        payload = dumps(request, MultiSequenceAlignmentRequestPojo)
+        response = self._user.plugin_post("bio/multisequencealignment",
+                                          payload=payload, is_payload_plain_text=True)
+        self._user.raise_for_status(response)
+        return loads(response.text, list[MultiSequenceAlignmentSeqPojo])
+
+    def register_bio(self, request: BioFileRegistrationRequest) -> BioFileRegistrationResponse:
+        """
+        Register to bioregistry of a file.
+        """
+        payload = dumps(request, BioFileRegistrationRequest)
+        response = self._user.plugin_post("bio/register/file", payload=payload, is_payload_plain_text=True)
+        self._user.raise_for_status(response)
+        return loads(response.text, BioFileRegistrationResponse)
+
+    def export_to_sdf(self, request: ChemExportSDFRequest) -> str:
+        """
+        Export the SDF files
+        :param request: The request for exporting SDF file.
+        :return: the SDF plain text data.
+        """
+        payload = dumps(request, ChemExportSDFRequest)
+        response = self._user.plugin_post("chemistry/export_sdf", payload=payload, is_payload_plain_text=True)
+        self._user.raise_for_status(response)
+        gzip_base64: str = response.text
+        if not gzip_base64:
+            raise SapioException("Returning data from server is blank for export SDF.")
+        decoded_bytes = base64.b64decode(gzip_base64)
+        with io.BytesIO(decoded_bytes) as bytes_io:
+            import gzip
+            with gzip.GzipFile(fileobj=bytes_io, mode='rb') as f:
+                ret: str = f.read().decode()
+                return ret