sapiopycommons 2025.3.10a455__py3-none-any.whl → 2025.3.17a456__py3-none-any.whl

sapiopycommons/chem/Molecules.py

@@ -1,6 +1,5 @@
 # Author Yechen Qiao
 # Common Molecule Utilities for Molecule Transfers with Sapio
-from typing import cast
 
 from rdkit import Chem
 from rdkit.Chem import Crippen, MolToInchi
@@ -9,7 +8,6 @@ from rdkit.Chem import rdMolDescriptors
 from rdkit.Chem.EnumerateStereoisomers import StereoEnumerationOptions, EnumerateStereoisomers
 from rdkit.Chem.MolStandardize import rdMolStandardize
 from rdkit.Chem.SaltRemover import SaltRemover
-from rdkit.Chem.rdChemReactions import ChemicalReaction
 from rdkit.Chem.rdchem import Mol, RWMol, Bond
 
 from sapiopycommons.chem.IndigoMolecules import indigo, renderer, indigo_inchi

sapiopycommons/customreport/auto_pagers.py

@@ -0,0 +1,270 @@
+from abc import ABC
+from copy import copy
+from queue import Queue
+
+from sapiopylib.rest.CustomReportService import CustomReportManager
+from sapiopylib.rest.DataMgmtService import DataMgmtServer
+from sapiopylib.rest.pojo.CustomReport import CustomReportCriteria, CustomReport, RawReportTerm, ReportColumn
+from sapiopylib.rest.pojo.datatype.FieldDefinition import FieldType
+from sapiopylib.rest.utils.autopaging import SapioPyAutoPager, PagerResultCriteriaType, _default_report_page_size, \
+    _default_record_page_size
+from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedType
+
+from sapiopycommons.general.aliases import FieldValue, UserIdentifier, AliasUtil, RecordModel
+from sapiopycommons.general.custom_report_util import CustomReportUtil
+from sapiopycommons.general.exceptions import SapioException
+from sapiopycommons.recordmodel.record_handler import RecordHandler
+
+
+# FR-47389: Create auto pagers for running custom/system/quick reports that return dictionaries or records for each row.
+class _DictReportPagerBase(SapioPyAutoPager[CustomReportCriteria, dict[str, FieldValue]], ABC):
+    """
+    A base class for automatically paging through a report and returning the results as a list of dictionaries.
+    """
+    _columns: list[ReportColumn]
+    _report_man: CustomReportManager
+
+    def __init__(self, user: UserIdentifier, first_page_criteria: CustomReportCriteria):
+        self._columns = first_page_criteria.column_list
+        super().__init__(AliasUtil.to_sapio_user(user), first_page_criteria)
+        self._report_man = DataMgmtServer.get_custom_report_manager(self.user)
+
+    def get_all_at_once(self) -> list[dict[str, FieldValue]]:
+        """
+        Get the results of all pages. Be cautious of client memory usage.
+        """
+        if self.has_iterated:
+            raise BrokenPipeError("Cannot use this method if the iterator has already been used.")
+        return [x for x in self]
+
+    def default_first_page_criteria(self) -> PagerResultCriteriaType:
+        raise ValueError("Cannot generate a default first page criteria for custom reports.")
+
+    def get_next_page_result(self) -> tuple[CustomReportCriteria | None, Queue[dict[str, FieldValue]]]:
+        report: CustomReport = self._report_man.run_custom_report(self.next_page_criteria)
+        queue: Queue[dict[str, FieldValue]] = Queue()
+        for row in _process_results(report.result_table, self._columns):
+            queue.put(row)
+        if report.has_next_page:
+            next_page_criteria = copy(self.next_page_criteria)
+            next_page_criteria.page_number += 1
+            return next_page_criteria, queue
+        else:
+            return None, queue
+
+
+class CustomReportDictAutoPager(_DictReportPagerBase):
+    """
+    A class that automatically pages through a custom report and returns the results as a list of dictionaries.
+    """
+    def __init__(self, user: UserIdentifier, report_criteria: CustomReportCriteria,
+                 page_number: int = 0, page_size: int = _default_report_page_size):
+        """
+        :param user: The current webhook context or a user object to send requests from.
+        :param report_criteria: The custom report criteria to run.
+        :param page_number: The page number to start on. The first page is page 0.
+        :param page_size: The number of results to return per page.
+        """
+        first_page_criteria: CustomReportCriteria = copy(report_criteria)
+        first_page_criteria.page_number = page_number
+        first_page_criteria.page_size = page_size
+        super().__init__(user, first_page_criteria)
+
+
+class SystemReportDictAutoPager(_DictReportPagerBase):
+    """
+    A class that automatically pages through a system report and returns the results as a list of dictionaries.
+
+    System reports are also known as predefined searches in the system and must be defined in the data designer for
+    a specific data type. That is, saved searches created by users cannot be run using this function.
+    """
+    def __init__(self, user: UserIdentifier, report_name: str,
+                 page_number: int = 0, page_size: int = _default_report_page_size):
+        """
+        :param user: The current webhook context or a user object to send requests from.
+        :param report_name: The name of the system report to run.
+        :param page_number: The page number to start on. The first page is page 0.
+        :param page_size: The number of results to return per page.
+        """
+        first_page_criteria: CustomReportCriteria = CustomReportUtil.get_system_report_criteria(user, report_name)
+        first_page_criteria.page_number = page_number
+        first_page_criteria.page_size = page_size
+        super().__init__(user, first_page_criteria)
+
+
+class QuickReportDictAutoPager(_DictReportPagerBase):
+    """
+    A class that automatically pages through a quick report and returns the results as a list of dictionaries.
+    """
+    def __init__(self, user: UserIdentifier, report_term: RawReportTerm,
+                 page_number: int = 0, page_size: int = _default_report_page_size):
+        """
+        :param user: 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 page_number: The page number to start on. The first page is page 0.
+        :param page_size: The number of results to return per page.
+        """
+        first_page_criteria: CustomReportCriteria = CustomReportUtil.get_quick_report_criteria(user, report_term)
+        first_page_criteria.page_number = page_number
+        first_page_criteria.page_size = page_size
+        super().__init__(user, first_page_criteria)
+
+
+class _RecordReportPagerBase(SapioPyAutoPager[CustomReportCriteria, WrappedType], ABC):
+    """
+    A base class for automatically paging through a report and returning the results as a list of records.
+    """
+    _columns: list[ReportColumn]
+    _wrapper: type[WrappedType]
+    _data_type: str
+    _rec_handler: RecordHandler
+    _report_man: CustomReportManager
+
+    def __init__(self, user: UserIdentifier, first_page_criteria: CustomReportCriteria, wrapper_type: type[WrappedType]):
+        self._columns = first_page_criteria.column_list
+        self._wrapper = wrapper_type
+        self._data_type = wrapper_type.get_wrapper_data_type_name()
+        self._rec_handler = RecordHandler(user)
+        super().__init__(AliasUtil.to_sapio_user(user), first_page_criteria)
+        self._report_man = DataMgmtServer.get_custom_report_manager(self.user)
+
+    def get_all_at_once(self) -> list[RecordModel]:
+        """
+        Get the results of all pages. Be cautious of client memory usage.
+        """
+        if self.has_iterated:
+            raise BrokenPipeError("Cannot use this method if the iterator has already been used.")
+        return [x for x in self]
+
+    def default_first_page_criteria(self) -> PagerResultCriteriaType:
+        raise ValueError("Cannot generate a default first page criteria for custom reports.")
+
+    def get_next_page_result(self) -> tuple[CustomReportCriteria | None, Queue[WrappedType]]:
+        report: CustomReport = self._report_man.run_custom_report(self.next_page_criteria)
+        queue: Queue[WrappedType] = Queue()
+        id_index: int = -1
+        for i, column in enumerate(self._columns):
+            if column.data_type_name == self._data_type and column.data_field_name == "RecordId":
+                id_index = i
+                break
+        if id_index == -1:
+            raise SapioException(f"This report does not contain a Record ID column for the given record model type "
+                                 f"{self._data_type}.")
+        ids: list[int] = [row[id_index] for row in report.result_table]
+        for row in self._rec_handler.query_models_by_id(self._wrapper, ids, page_size=report.page_size):
+            queue.put(row)
+        if report.has_next_page:
+            next_page_criteria = copy(self.next_page_criteria)
+            next_page_criteria.page_number += 1
+            return next_page_criteria, queue
+        else:
+            return None, queue
+
+
+class CustomReportRecordAutoPager(_RecordReportPagerBase):
+    """
+    A class that automatically pages through a custom report and returns the results as a list of records.
+    """
+    def __init__(self, user: UserIdentifier, report_criteria: CustomReportCriteria, wrapper_type: type[WrappedType],
+                 page_number: int = 0, page_size: int = _default_record_page_size):
+        """
+        :param user: The current webhook context or a user object to send requests from.
+        :param report_criteria: The custom report criteria to run.
+        :param wrapper_type: The record model wrapper type to use for the records.
+        :param page_number: The page number to start on. The first page is page 0.
+        :param page_size: The number of results to return per page.
+        """
+        first_page_criteria: CustomReportCriteria = copy(report_criteria)
+        _add_record_id_column(first_page_criteria, wrapper_type)
+        first_page_criteria.page_number = page_number
+        first_page_criteria.page_size = page_size
+        super().__init__(user, first_page_criteria, wrapper_type)
+
+
+class SystemReportRecordAutoPager(_RecordReportPagerBase):
+    """
+    A class that automatically pages through a system report and returns the results as a list of records.
+
+    System reports are also known as predefined searches in the system and must be defined in the data designer for
+    a specific data type. That is, saved searches created by users cannot be run using this function.
+    """
+    def __init__(self, user: UserIdentifier, report_name: str, wrapper_type: type[WrappedType],
+                 page_number: int = 0, page_size: int = _default_record_page_size):
+        """
+        :param user: The current webhook context or a user object to send requests from.
+        :param report_name: The name of the system report to run.
+        :param wrapper_type: The record model wrapper type to use for the records.
+        :param page_number: The page number to start on. The first page is page 0.
+        :param page_size: The number of results to return per page.
+        """
+        first_page_criteria: CustomReportCriteria = CustomReportUtil.get_system_report_criteria(user, report_name)
+        _add_record_id_column(first_page_criteria, wrapper_type)
+        first_page_criteria.page_number = page_number
+        first_page_criteria.page_size = page_size
+        super().__init__(user, first_page_criteria, wrapper_type)
+
+
+class QuickReportRecordAutoPager(_RecordReportPagerBase):
+    """
+    A class that automatically pages through a quick report and returns the results as a list of records.
+    """
+    def __init__(self, user: UserIdentifier, report_term: RawReportTerm, wrapper_type: type[WrappedType],
+                 page_number: int = 0, page_size: int = _default_record_page_size):
+        """
+        :param user: 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 wrapper_type: The record model wrapper type to use for the records.
+        :param page_number: The page number to start on. The first page is page 0.
+        :param page_size: The number of results to return per page.
+        """
+        if report_term.data_type_name != wrapper_type.get_wrapper_data_type_name():
+            raise SapioException("The data type name of the report term must match the data type name of the wrapper type.")
+        first_page_criteria: CustomReportCriteria = CustomReportUtil.get_quick_report_criteria(user, report_term)
+        first_page_criteria.page_number = page_number
+        first_page_criteria.page_size = page_size
+        super().__init__(user, first_page_criteria, wrapper_type)
+
+
+def _add_record_id_column(report: CustomReportCriteria, wrapper_type: type[WrappedType]) -> None:
+    """
+    Given a custom report criteria, ensure that the report contains a Record ID column for the given record model's
+    data type. Add one if it is missing.
+    """
+    dt: str = wrapper_type.get_wrapper_data_type_name()
+    # Ensure that the root data type is the one we're looking for.
+    report.root_data_type = dt
+    # Enforce that the given custom report has a record ID column.
+    if not any([x.data_type_name == dt and x.data_field_name == "RecordId" for x in report.column_list]):
+        report.column_list.append(ReportColumn(dt, "RecordId", FieldType.LONG))
+
+
+def _process_results(rows: list[list[FieldValue]], columns: list[ReportColumn]) -> list[dict[str, FieldValue]]:
+    """
+    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.
+    """
+    # 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, FieldValue]] = []
+    for row in rows:
+        row_data: dict[str, FieldValue] = {}
+        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
+            row_data.update({header: value})
+        if filter_row is False:
+            ret.append(row_data)
+    return ret

sapiopycommons/datatype/data_fields.py

@@ -58,4 +58,4 @@ class ProcessWorkflowTrackingFields:
     WORKFLOW_PROCESS_TAT__FIELD = WrapperField("WorkflowProcessTAT", FieldType.DOUBLE)
     WORKFLOW_START_USER_ID__FIELD = WrapperField("WorkflowStartUserId", FieldType.STRING)
     WORKFLOW_TAT__FIELD = WrapperField("WorkflowTAT", FieldType.DOUBLE)
-    WORKFLOW_VERSION__FIELD = WrapperField("WorkflowVersion", FieldType.LONG)
+    WORKFLOW_VERSION__FIELD = WrapperField("WorkflowVersion", FieldType.LONG)

sapiopycommons/eln/experiment_handler.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import time
 from collections.abc import Mapping, Iterable
+from typing import TypeAlias
 from weakref import WeakValueDictionary
 
 from sapiopylib.rest.DataMgmtService import DataMgmtServer
@@ -28,7 +29,7 @@ from sapiopycommons.general.aliases import AliasUtil, SapioRecord, ExperimentIde
     DataTypeIdentifier, RecordModel
 from sapiopycommons.general.exceptions import SapioException
 
-Step = str | ElnEntryStep
+Step: TypeAlias = str | ElnEntryStep
 """An object representing an identifier to an ElnEntryStep. May be either the name of the step or the ElnEntryStep
 itself."""
 

sapiopycommons/eln/experiment_report_util.py

@@ -6,13 +6,13 @@ from sapiopylib.rest.pojo.eln.ElnExperiment import ElnExperiment, ElnExperimentQ
 from sapiopylib.rest.pojo.eln.SapioELNEnums import ElnExperimentStatus, ElnBaseDataType
 from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedType
 
+from sapiopycommons.customreport.auto_pagers import CustomReportDictAutoPager
 from sapiopycommons.customreport.custom_report_builder import CustomReportBuilder
 from sapiopycommons.customreport.term_builder import TermBuilder
 from sapiopycommons.datatype.pseudo_data_types import EnbEntryOptionsPseudoDef, NotebookExperimentOptionPseudoDef, \
     NotebookExperimentPseudoDef, ExperimentEntryRecordPseudoDef, EnbEntryPseudoDef
 from sapiopycommons.general.aliases import SapioRecord, UserIdentifier, AliasUtil, FieldValue, \
     ExperimentEntryIdentifier, ExperimentIdentifier
-from sapiopycommons.general.custom_report_util import CustomReportUtil
 from sapiopycommons.general.exceptions import SapioException
 from sapiopycommons.recordmodel.record_handler import RecordHandler
 
@@ -201,7 +201,7 @@ class ExperimentReportUtil:
         criteria = report_builder.build_report_criteria()
 
         ret_val: dict[SapioRecord, int] = {}
-        rows: list[dict[str, FieldValue]] = CustomReportUtil.run_custom_report(context, criteria)
+        rows: list[dict[str, FieldValue]] = CustomReportDictAutoPager(context, criteria).get_all_at_once()
         for row in rows:
             dt: str = row[EnbEntryPseudoDef.DATA_TYPE_NAME__FIELD_NAME.field_name]
             exp_id: int = row[EnbEntryPseudoDef.EXPERIMENT_ID__FIELD_NAME.field_name]
@@ -268,7 +268,7 @@ class ExperimentReportUtil:
 
         # Ensure that each experiment appears in the dictionary, even if it has no experiment options.
         options: dict[int, dict[str, str]] = {x: {} for x in exp_ids}
-        results: list[dict[str, FieldValue]] = CustomReportUtil.run_custom_report(context, report)
+        results: list[dict[str, FieldValue]] = CustomReportDictAutoPager(context, report).get_all_at_once()
         for row in results:
             exp_id: int = row[NotebookExperimentOptionPseudoDef.EXPERIMENT_ID__FIELD_NAME.field_name]
             key: str = row[NotebookExperimentOptionPseudoDef.OPTION_KEY__FIELD_NAME.field_name]
@@ -299,7 +299,7 @@ class ExperimentReportUtil:
 
         # Ensure that each entry appears in the dictionary, even if it has no entry options.
         options: dict[int, dict[str, str]] = {x: {} for x in entries}
-        results: list[dict[str, FieldValue]] = CustomReportUtil.run_custom_report(context, report)
+        results: list[dict[str, FieldValue]] = CustomReportDictAutoPager(context, report).get_all_at_once()
         for row in results:
             entry_id: int = row[EnbEntryOptionsPseudoDef.ENTRY_ID__FIELD_NAME.field_name]
             key: str = row[EnbEntryOptionsPseudoDef.ENTRY_OPTION_KEY__FIELD_NAME.field_name]
@@ -332,7 +332,7 @@ class ExperimentReportUtil:
         report = report_builder.build_report_criteria()
 
         ret_val: dict[int, str] = {}
-        results: list[dict[str, FieldValue]] = CustomReportUtil.run_custom_report(context, report)
+        results: list[dict[str, FieldValue]] = CustomReportDictAutoPager(context, report).get_all_at_once()
         for row in results:
             exp_id: int = row[NotebookExperimentPseudoDef.EXPERIMENT_ID__FIELD_NAME.field_name]
             name: str = row["TemplateExperimentName"]
@@ -581,7 +581,7 @@ class ExperimentReportUtil:
         """
         user = AliasUtil.to_sapio_user(context)
         exp_ids: list[int] = []
-        for row in CustomReportUtil.run_custom_report(user, report):
+        for row in CustomReportDictAutoPager(user, report):
             exp_ids.append(row[NotebookExperimentPseudoDef.EXPERIMENT_ID__FIELD_NAME.field_name])
         if not exp_ids:
             return []
@@ -646,4 +646,4 @@ class ExperimentReportUtil:
         report_builder.add_join(records_entry_join, ExperimentEntryRecordPseudoDef.DATA_TYPE_NAME)
         report_builder.add_join(experiment_entry_enb_entry_join, EnbEntryPseudoDef.DATA_TYPE_NAME)
         report_builder.add_join(enb_entry_experiment_join, NotebookExperimentPseudoDef.DATA_TYPE_NAME)
-        return CustomReportUtil.run_custom_report(user, report_builder.build_report_criteria())
+        return CustomReportDictAutoPager(user, report_builder.build_report_criteria()).get_all_at_once()

sapiopycommons/files/file_bridge.py

@@ -1,6 +1,7 @@
 import base64
 import io
 import urllib.parse
+from typing import Any
 
 from requests import Response
 from sapiopylib.rest.User import SapioUser
@@ -8,6 +9,36 @@ 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
@@ -137,3 +168,48 @@ class FileBridge:
         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]