sapiopycommons 2025.6.19a564__py3-none-any.whl → 2026.1.22a847__py3-none-any.whl

sapiopycommons/files/temp_files.py

@@ -0,0 +1,82 @@
+import os
+import shutil
+import tempfile
+from typing import Callable, Any
+
+
+# FR-47422: Created class.
+class TempFileHandler:
+    """
+    A utility class to manage temporary files and directories.
+    """
+    directories: list[str]
+    files: list[str]
+
+    def __init__(self):
+        self.directories = []
+        self.files = []
+
+    def create_temp_directory(self) -> str:
+        """
+        Create a temporary directory.
+
+        :return: The path to a newly created temporary directory.
+        """
+        directory: str = tempfile.mkdtemp()
+        self.directories.append(directory)
+        return directory
+
+    def create_temp_file(self, data: str | bytes, suffix: str = "") -> str:
+        """
+        Create a temporary file with the specified data and optional suffix.
+
+        :param data: The data to write to the temporary file.
+        :param suffix: An optional suffix for the temporary file.
+        :return: The path to a newly created temporary file containing the provided data.
+        """
+        mode: str = 'w' if isinstance(data, str) else 'wb'
+        with tempfile.NamedTemporaryFile(mode=mode, suffix=suffix, delete=False) as tmp_file:
+            tmp_file.write(data)
+            file_path: str = tmp_file.name
+            self.files.append(file_path)
+        return file_path
+
+    def create_temp_file_from_func(self, func: Callable, params: dict[str, Any], suffix: str = "",
+                                   is_binary: bool = True) -> str:
+        """
+        Create a temporary file and populate it using the provided function. The function should accept parameters as
+        specified in the `params` dictionary.
+
+        :param func: The function to call with the temporary file path that will populate the file.
+        :param params: Keyword arguments to pass to the function. If "<NEW_FILE>" is used as a value, it will be
+            replaced with the temporary file object. If "<NEW_FILE_PATH>" is used as a value, it will be replaced with
+            the temporary file path.
+        :param suffix: An optional suffix for the temporary file.
+        :param is_binary: Whether to open the temporary file in binary mode.
+        :return: The path to the newly created temporary file.
+        """
+        mode: str = 'wb' if is_binary else 'w'
+        with tempfile.NamedTemporaryFile(mode, suffix=suffix, delete=False) as tmp_file:
+            for key, value in params.items():
+                if value == "<NEW_FILE>":
+                    params[key] = tmp_file
+                elif value == "<NEW_FILE_PATH>":
+                    params[key] = tmp_file.name
+            func(**params)
+            file_path: str = tmp_file.name
+            self.files.append(file_path)
+        return file_path
+
+    def cleanup(self) -> None:
+        """
+        Delete all temporary files and directories created by this handler.
+        """
+        for directory in self.directories:
+            if os.path.exists(directory):
+                shutil.rmtree(directory)
+        self.directories.clear()
+
+        for file_path in self.files:
+            if os.path.exists(file_path):
+                os.remove(file_path)
+        self.files.clear()

sapiopycommons/flowcyto/flow_cyto.py

@@ -4,38 +4,16 @@ from weakref import WeakValueDictionary
 
 from databind.json import dumps
 from sapiopylib.rest.User import SapioUser
+from sapiopylib.rest.utils.singletons import SapioContextManager
 
 from sapiopycommons.flowcyto.flowcyto_data import FlowJoWorkspaceInputJson, UploadFCSInputJson, \
     ComputeFlowStatisticsInputJson
 
 
-class FlowCytoManager:
+class FlowCytoManager(SapioContextManager):
     """
     This manager includes flow cytometry analysis tools that would require FlowCyto license to use.
     """
-    _user: SapioUser
-
-    __instances: WeakValueDictionary[SapioUser, FlowCytoManager] = 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 create_flowjo_workspace(self, workspace_input: FlowJoWorkspaceInputJson) -> int:
         """

sapiopycommons/general/accession_service.py

@@ -5,6 +5,7 @@ from typing import Any
 from weakref import WeakValueDictionary
 
 from sapiopylib.rest.User import SapioUser
+from sapiopylib.rest.utils.singletons import SapioContextManager
 
 _STR_JAVA_TYPE = "java.lang.String"
 _INT_JAVA_TYPE = "java.lang.Integer"
@@ -274,37 +275,10 @@ class AccessionServiceDescriptor:
         }
 
 
-class AccessionService:
+class AccessionService(SapioContextManager):
     """
     Provides Sapio Foundations Accession Service functionalities.
     """
-    _user: SapioUser
-
-    __instances: WeakValueDictionary[SapioUser, AccessionService] = WeakValueDictionary()
-    __initialized: bool
-
-    @property
-    def user(self) -> SapioUser:
-        return self._user
-
-    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 accession_with_config(self, data_type_name: str, data_field_name: str, num_ids: int) -> list[str]:
         """

sapiopycommons/general/aliases.py

@@ -223,9 +223,12 @@ class AliasUtil:
             # macros get translated to valid field values.
             fields: FieldMap = {f: record.fields.get(f) for f in record.fields}
         # PR-47457: Only include the record ID if the caller requests it, since including the record ID can break
-        # callbacks in certain circumstances if the record ID is negative.
+        # callbacks in certain circumstances.
+        # PR-47894: Also remove the RecordId key if it exists and the caller doesn't want it included.
         if include_record_id:
             fields["RecordId"] = AliasUtil.to_record_id(record)
+        elif "RecordId" in fields:
+            del fields["RecordId"]
         return fields
 
     @staticmethod

sapiopycommons/general/macros.py

@@ -0,0 +1,172 @@
+
+import re
+from datetime import datetime, timedelta, timezone
+
+from sapiopycommons.general.exceptions import SapioException
+
+date_macro_pattern: str = (
+    r"@(?:today|yesterday|thisweek|"
+    r"nextmonth|thismonth|lastmonth|"
+    r"nextyear|thisyear|lastyear|"
+    r"month(?:january|february|march|april|may|june|july|august|september|october|november|december)|"
+    r"last\d+days|next\d+days)"
+)
+"""A regular expression that can be used to determine whether a given value matches one of the supported date macros."""
+
+date_macro_values: list[str] = [
+    "@today", "@yesterday", "@thisweek",
+    "@nextmonth", "@thismonth", "@lastmonth",
+    "@nextyear", "@thisyear", "@lastyear",
+    "@monthjanuary", "@monthfebruary", "@monthmarch", "@monthapril", "@monthmay", "@monthjune", "@monthjuly",
+    "@monthaugust", "@monthseptember", "@monthoctober", "@monthnovember", "@monthdecember",
+    "@next_days", "@last_days"
+]
+"""A list of the supported date macros. For @next_days and @last_days, the underscore is expected to be replaced with
+an integer."""
+
+
+class MacroParser:
+    """
+    A utility class for parsing macros used in the Sapio platform.
+    """
+    _reg_month = re.compile(r"@\w*month\w*")
+    _reg_digits = re.compile(r"@\w*(\d+)\w*")
+    _reg_last_days = re.compile(r"@last(\d+)days")
+    _reg_next_days = re.compile(r"@next(\d+)days")
+
+    @staticmethod
+    def _now() -> datetime:
+        """
+        :return: A datetime object for the current time in UTC.
+        """
+        return datetime.now(timezone.utc)
+
+    @staticmethod
+    def _dates_to_timestamps(a: datetime, b: datetime) -> tuple[int, int]:
+        """
+        Convert the given datetimes to epoch-millisecond timestamps on the start of the first date
+        and the end of the second date.
+
+        :param a: A datetime object.
+        :param b: A datetime object.
+        :return: A tuple containing the start and end timestamps in milliseconds since the epoch.
+        """
+        # The start of the date on the first datetime.
+        a = a.replace(hour=0, minute=0, second=0, microsecond=0)
+        # The end of the date on the second datetime.
+        b = b.replace(hour=23, minute=59, second=59, microsecond=999000)
+        return int(a.timestamp() * 1000), int(b.timestamp() * 1000)
+
+    @classmethod
+    def parse_date_macro(cls, macro: str) -> tuple[int, int]:
+        """
+        Convert a date macro string into a range of epoch millisecond timestamps.
+        All macros are considered from the current time in UTC.
+
+        :param macro: A valid date macro string. If an invalid macro is provided, an exception will be raised.
+        :return: A tuple containing the start and end timestamps in milliseconds since the epoch for the given macro.
+            The returned range is inclusive; the first value is the first millisecond of the starting date
+            (00:00:00.000) and the last value is the final millisecond of the ending date (23:59:59.999).
+        """
+        if macro is None or not macro.strip():
+            raise SapioException(f"Invalid macro. None or empty/blank string provided.")
+        macro = macro.strip().lower()
+
+        now: datetime = cls._now()
+
+        # --- @today: 00:00:00.000 to 23:59:59.999 today ---
+        if macro == "@today":
+            return cls._dates_to_timestamps(now, now)
+
+        # --- @yesterday: 00:00:00.000 to 23:59:59.999 yesterday ---
+        if macro == "@yesterday":
+            yesterday: datetime = now - timedelta(days=1)
+            return cls._dates_to_timestamps(yesterday, yesterday)
+
+        # --- @thisweek: Sunday -> Saturday (inclusive) ---
+        if macro == "@thisweek":
+            weekday: int = now.weekday()  # Monday=0 ... Sunday=6
+            # TODO: Some way to control what the first day of the week is considered?
+            #  +2 = Saturday
+            #  +1 = Sunday
+            #  +0 = Monday
+            days_since_sunday: int = (weekday + 1) % 7
+            sunday: datetime = now - timedelta(days=days_since_sunday)
+            saturday: datetime = sunday + timedelta(days=6)
+            return cls._dates_to_timestamps(sunday, saturday)
+
+        # --- last/next N days ---
+        if cls._reg_digits.fullmatch(macro):
+            # --- @lastNdays ---
+            if m := cls._reg_last_days.fullmatch(macro):
+                days = int(m.group(1))
+                return cls._dates_to_timestamps(now - timedelta(days=days), now)
+
+            # --- @nextNdays ---
+            if m := cls._reg_next_days.fullmatch(macro):
+                days = int(m.group(1))
+                return cls._dates_to_timestamps(now, now + timedelta(days=days))
+
+            raise SapioException(f"Invalid macro: {macro}")
+
+        # --- Month macros ---
+        if cls._reg_month.fullmatch(macro):
+            year: int = now.year
+            month: int = now.month
+
+            if macro == "@lastmonth":
+                month -= 1
+                if month == 0:
+                    year -= 1
+                    month = 12
+            elif macro == "@nextmonth":
+                month += 1
+                if month == 13:
+                    year += 1
+                    month = 1
+            # @thismonth uses the current month and year, so no replacement needed.
+            elif macro != "@thismonth":
+                month_map: dict[str, int] = {
+                    "@monthjanuary": 1,
+                    "@monthfebruary": 2,
+                    "@monthmarch": 3,
+                    "@monthapril": 4,
+                    "@monthmay": 5,
+                    "@monthjune": 6,
+                    "@monthjuly": 7,
+                    "@monthaugust": 8,
+                    "@monthseptember": 9,
+                    "@monthoctober": 10,
+                    "@monthnovember": 11,
+                    "@monthdecember": 12,
+                }
+                if macro in month_map:
+                    month = month_map[macro]
+                else:
+                    raise SapioException(f"Invalid macro: {macro}")
+
+            month_start: datetime = now.replace(year=year, month=month, day=1)
+            # Find the first day of next month.
+            if month == 12:
+                next_month = datetime(year + 1, 1, 1, tzinfo=timezone.utc)
+            else:
+                next_month = datetime(year, month + 1, 1, tzinfo=timezone.utc)
+            # Then subtract one day to find the last day of the start month.
+            month_end: datetime = next_month - timedelta(days=1)
+
+            return cls._dates_to_timestamps(month_start, month_end)
+
+        # --- Year macros ---
+        if macro in ("@thisyear", "@lastyear", "@nextyear"):
+            year: int = now.year
+            if macro == "@lastyear":
+                year -= 1
+            elif macro == "@nextyear":
+                year += 1
+            # No change in year needed for @thisyear.
+
+            year_start: datetime = now.replace(year=year, month=1, day=1)
+            year_end: datetime = year_start.replace(year=year_start.year + 1) - timedelta(days=1)
+            return cls._dates_to_timestamps(year_start, year_end)
+
+        raise SapioException(f"Invalid macro: {macro}")

sapiopycommons/general/time_util.py

@@ -133,9 +133,10 @@ class TimeUtil:
         return datetime.fromtimestamp(millis / 1000, tz).strftime(time_format)
 
     @staticmethod
-    def format_to_millis(time_point: str, time_format: str, timezone: str | int = None) -> int:
+    def format_to_millis(time_point: str, time_format: str, timezone: str | int = None) -> int | None:
         """
-        Convert the input time from the provided format to milliseconds.
+        Convert the input time from the provided format to milliseconds. If None is passed to the time_point parameter,
+        None will be returned.
 
         :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
@@ -144,6 +145,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 time_point is None:
+            return None
+
         tz = TimeUtil.__to_tz(timezone)
         return int(datetime.strptime(time_point, time_format).replace(tzinfo=tz).timestamp() * 1000)
 
@@ -166,11 +170,12 @@ class TimeUtil:
         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:
+    def shift_millis(millis: int, to_timezone: str = "UTC", from_timezone: str | None = None) -> int | None:
         """
         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.
+        If None is passed to the millis parameter, None will be returned.
 
         :param millis: The time in milliseconds to convert from.
         :param to_timezone: The timezone to shift to. If not provided, uses UTC.
@@ -180,17 +185,21 @@ class TimeUtil:
         :return: The epoch timestamp that would display as the same time in to_timezone as the given time in
             from_timezone.
         """
+        if millis is None:
+            return None
+
         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:
+            -> int | None:
         """
         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.
+        If None is passed to the time_point parameter, None will be returned.
 
         :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
@@ -202,6 +211,9 @@ class TimeUtil:
         :return: The epoch timestamp that would display as the same time in to_timezone as the given time in
             from_timezone.
         """
+        if time_point is None:
+            return None
+
         millis: int = TimeUtil.format_to_millis(time_point, time_format, from_timezone)
         return TimeUtil.shift_millis(millis, to_timezone, from_timezone)
 
@@ -215,9 +227,192 @@ class TimeUtil:
         :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
         """
+        if time_point is None:
+            return False
         try:
             # If this function successfully runs, then the time_point matches the time_format.
             TimeUtil.format_to_millis(time_point, time_format, "UTC")
             return True
         except Exception:
             return False
+
+
+MILLISECONDS_IN_A_SECOND: int = 1000
+MILLISECONDS_IN_A_MINUTE: int = 60 * MILLISECONDS_IN_A_SECOND
+MILLISECONDS_IN_AN_HOUR: int = 60 * MILLISECONDS_IN_A_MINUTE
+MILLISECONDS_IN_A_DAY: int = 24 * MILLISECONDS_IN_AN_HOUR
+
+class ElapsedTime:
+    _start: int
+    _end: int
+
+    _total_days: float
+    _total_hours: float
+    _total_minutes: float
+    _total_seconds: float
+    _total_milliseconds: int
+
+    _days: int
+    _hours: int
+    _minutes: int
+    _seconds: int
+    _milliseconds: int
+
+    def __init__(self, start: int | float, end: int | float | None = None):
+        """
+        :param start: The start timestamp in milliseconds (int) or seconds (float).
+        :param end: The end timestamp in milliseconds (int) or seconds (float). If None, uses the current epoch time in
+            milliseconds.
+        """
+        if isinstance(start, float):
+            start = int(start * 1000)
+
+        if end is None:
+            end = TimeUtil.now_in_millis()
+        elif isinstance(end, float):
+            end = int(end * 1000)
+
+        self._start = start
+        self._end = end
+
+        self._total_milliseconds = end - start
+        self._total_seconds = self._total_milliseconds / MILLISECONDS_IN_A_SECOND
+        self._total_minutes = self._total_milliseconds / MILLISECONDS_IN_A_MINUTE
+        self._total_hours = self._total_milliseconds / MILLISECONDS_IN_AN_HOUR
+        self._total_days = self._total_milliseconds / MILLISECONDS_IN_A_DAY
+
+        elapsed: int = end - start
+        self._days: int = elapsed // MILLISECONDS_IN_A_DAY
+        elapsed -= self._days * MILLISECONDS_IN_A_DAY
+        self._hours: int = elapsed // MILLISECONDS_IN_AN_HOUR
+        elapsed -= self._hours * MILLISECONDS_IN_AN_HOUR
+        self._minutes: int = elapsed // MILLISECONDS_IN_A_MINUTE
+        elapsed -= self._minutes * MILLISECONDS_IN_A_MINUTE
+        self._seconds: int = elapsed // MILLISECONDS_IN_A_SECOND
+        elapsed -= self._seconds * MILLISECONDS_IN_A_SECOND
+        self._milliseconds = elapsed
+
+    @staticmethod
+    def as_eta(total: int, progress: int, start: int | float, now: int | float | None = None) -> ElapsedTime:
+        """
+        Calculate the estimated time remaining for a task based on how much time has passed so far and how many items
+        have been completed. The estimated time remaining is calculated by determining the average time per item
+        completed so far and multiplying that by the number of items remaining.
+
+        :param total: The total number of items that need to be completed for the task.
+        :param progress: The number of items that have been completed so far.
+        :param start: The start time of a task in milliseconds (int) or seconds (float).
+        :param now: The amount of time that has passed so far while performing the task in milliseconds (int)
+            or seconds (float). If None, uses the current epoch time in milliseconds.
+        :return: An ElapsedTime object representing the estimated time remaining.
+        """
+        if now is None:
+            now = TimeUtil.now_in_millis()
+        is_int: bool = isinstance(start, int) and isinstance(now, int)
+        # How much time has elapsed so far.
+        elapsed: int | float = now - start
+        # The average time it has taken to complete each record so far.
+        per_record: int | float = (elapsed // progress) if is_int else (elapsed / progress)
+        # The estimated time remaining based on the average time per record.
+        remaining: int | float = (total - progress) * per_record
+        return ElapsedTime(now, now + remaining)
+
+    def __str__(self) -> str:
+        time_str: str = f"{self._hours:02d}:{self._minutes:02d}:{self._seconds:02d}.{self._milliseconds:03d}"
+        if self._days:
+            return f"{self._days}d {time_str}"
+        return time_str
+
+    @property
+    def start(self) -> int:
+        """
+        The start timestamp in milliseconds.
+        """
+        return self._start
+
+    @property
+    def end(self) -> int:
+        """
+        The end timestamp in milliseconds.
+        """
+        return self._end
+
+    @property
+    def total_days(self) -> float:
+        """
+        The total number of days in the elapsed time. For example, an elapsed time of 1.5 days would
+        return 1.5.
+        """
+        return self._total_days
+
+    @property
+    def total_hours(self) -> float:
+        """
+        The total number of hours in the elapsed time. For example, an elapsed time of 1.5 days would
+        return 36.0.
+        """
+        return self._total_hours
+
+    @property
+    def total_minutes(self) -> float:
+        """
+        The total number of minutes in the elapsed time. For example, an elapsed time of 1.5 days would
+        return 2,160.0.
+        """
+        return self._total_minutes
+
+    @property
+    def total_seconds(self) -> float:
+        """
+        The total number of seconds in the elapsed time. For example, an elapsed time of 1.5 days would
+        return 129,600.0.
+        """
+        return self._total_seconds
+
+    @property
+    def total_milliseconds(self) -> int:
+        """
+        The total number of milliseconds in the elapsed time. For example, an elapsed time of 1.5 days would
+        return 129,600,000.
+        """
+        return self._total_milliseconds
+
+    @property
+    def days(self) -> int:
+        """
+        The number of full days in the elapsed time. For example, an elapsed time of 1.5 days would
+        return 1.
+        """
+        return self._days
+
+    @property
+    def hours(self) -> int:
+        """
+        The number of full hours in the elapsed time, not counting full days. For example, an elapsed time of 1.5 days
+        would return 12.
+        """
+        return self._hours
+
+    @property
+    def minutes(self) -> int:
+        """
+        The number of full minutes in the elapsed time, not counting full hours. For example, an elapsed time of
+        1.5 hours would return 30.
+        """
+        return self._minutes
+
+    @property
+    def seconds(self) -> int:
+        """
+        The number of full seconds in the elapsed time, not counting full minutes. For example, an elapsed time of 1
+        minute and 45 seconds would return 45.
+        """
+        return self._seconds
+
+    @property
+    def milliseconds(self) -> int:
+        """
+        The number of milliseconds in the elapsed time, not counting full seconds. For example, an elapsed time of
+        1.25 seconds would return 250.
+        """
+        return self._milliseconds

sapiopycommons/multimodal/multimodal.py

@@ -7,35 +7,13 @@ from weakref import WeakValueDictionary
 from databind.json import dumps, loads
 from sapiopylib.rest.User import SapioUser
 from sapiopylib.rest.pojo.DataRecord import DataRecord
+from sapiopylib.rest.utils.singletons import SapioContextManager
 
 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
+class MultiModalManager(SapioContextManager):
 
     def load_image_data(self, request: ImageDataRequestPojo) -> list[str]:
         """