sapiopycommons 2025.3.6a453__py3-none-any.whl → 2025.3.10a455__py3-none-any.whl

sapiopycommons/customreport/auto_pagers.py

@@ -1,278 +0,0 @@
-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.PyRecordModel import PyRecordModel
-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, RecordModel], ABC):
-    """
-    A base class for automatically paging through a report and returning the results as a list of records.
-    """
-    _columns: list[ReportColumn]
-    _query_type: type[WrappedType] | str
-    _data_type: str
-    _rec_handler: RecordHandler
-    _report_man: CustomReportManager
-
-    def __init__(self, user: UserIdentifier, first_page_criteria: CustomReportCriteria, wrapper_type: type[WrappedType] | str):
-        self._columns = first_page_criteria.column_list
-        self._query_type = wrapper_type
-        self._data_type = AliasUtil.to_data_type_name(wrapper_type)
-        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] | Queue[PyRecordModel]]:
-        report: CustomReport = self._report_man.run_custom_report(self.next_page_criteria)
-        queue = 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._query_type, 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] | str, 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 or data type name of the records being searched for.
-            If a data type name was used instead of a model wrapper, then the returned records will be PyRecordModels
-            instead of WrappedRecordModels.
-        :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] | str,
-                 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 or data type name of the records being searched for.
-            If a data type name was used instead of a model wrapper, then the returned records will be PyRecordModels
-            instead of WrappedRecordModels.
-        :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] | str,
-                 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 or data type name of the records being searched for.
-            If a data type name was used instead of a model wrapper, then the returned records will be PyRecordModels
-            instead of WrappedRecordModels.
-        :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] | str) -> 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 = AliasUtil.to_data_type_name(wrapper_type)
-    # 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/general/directive_util.py

@@ -1,86 +0,0 @@
-from typing import Iterable, cast
-
-from sapiopylib.rest.User import SapioUser
-from sapiopylib.rest.pojo.CustomReport import CustomReportCriteria, CustomReport
-from sapiopylib.rest.pojo.webhook.WebhookDirective import HomePageDirective, FormDirective, TableDirective, \
-    CustomReportDirective, ElnExperimentDirective, ExperimentEntryDirective
-
-from sapiopycommons.general.aliases import SapioRecord, AliasUtil, ExperimentIdentifier, ExperimentEntryIdentifier, \
-    UserIdentifier
-from sapiopycommons.general.custom_report_util import CustomReportUtil
-
-
-# FR-47392: Create a DirectiveUtil class to simplify the creation of directives.
-class DirectiveUtil:
-    """
-    DirectiveUtil is a class for creating webhook directives. The utility functions reduce the provided variables
-    down to the exact type that the directives require, removing the need for the caller to handle the conversion.
-    """
-    user: SapioUser
-
-    def __init__(self, context: UserIdentifier):
-        """
-        :param context: The current webhook context or a user object to send requests from.
-        """
-        self.user = AliasUtil.to_sapio_user(context)
-
-    @staticmethod
-    def homepage() -> HomePageDirective:
-        """
-        :return: A directive that sends the user back to their home page.
-        """
-        return HomePageDirective()
-
-    @staticmethod
-    def record_form(record: SapioRecord) -> FormDirective:
-        """
-        :param record: A record in the system.
-        :return: A directive that sends the user to a specific data record form.
-        """
-        return FormDirective(AliasUtil.to_data_record(record))
-
-    @staticmethod
-    def record_table(records: Iterable[SapioRecord]) -> TableDirective:
-        """
-        :param records: A list of records in the system.
-        :return: A directive that sends the user to a table of data records.
-        """
-        return TableDirective(AliasUtil.to_data_records(records))
-
-    @staticmethod
-    def record_adaptive(records: Iterable[SapioRecord]) -> TableDirective | FormDirective:
-        """
-        :param records: A list of records in the system.
-        :return: A directive that sends the user to a table of data records if there are multiple records,
-            or a directive that sends the user to a specific data record form if there is only one record.
-        """
-        records: list[SapioRecord] = list(records)
-        if len(records) == 1:
-            return DirectiveUtil.record_form(records[0])
-        return DirectiveUtil.record_table(records)
-
-    def custom_report(self, report: CustomReport | CustomReportCriteria | str) -> CustomReportDirective:
-        """
-        :param report: A custom report, the criteria for a custom report, or the name of a system report.
-        :return: A directive that sends the user to the results of the provided custom report.
-        """
-        if isinstance(report, str):
-            report: CustomReport = CustomReportUtil.get_system_report_criteria(self.user, report)
-        return CustomReportDirective(cast(CustomReport, report))
-
-    @staticmethod
-    def eln_experiment(experiment: ExperimentIdentifier) -> ElnExperimentDirective:
-        """
-        :param experiment: An identifier for an experiment.
-        :return: A directive that sends the user to the ELN experiment.
-        """
-        return ElnExperimentDirective(AliasUtil.to_notebook_id(experiment))
-
-    @staticmethod
-    def eln_entry(experiment: ExperimentIdentifier, entry: ExperimentEntryIdentifier) -> ExperimentEntryDirective:
-        """
-        :param experiment: An identifier for an experiment.
-        :param entry: An identifier for an entry in the experiment.
-        :return: A directive that sends the user to the provided experiment entry within its ELN experiment.
-        """
-        return ExperimentEntryDirective(AliasUtil.to_notebook_id(experiment), AliasUtil.to_entry_id(entry))