sapiopycommons 2025.5.6a512__py3-none-any.whl → 2025.5.7a514__py3-none-any.whl

sapiopycommons/recordmodel/record_handler.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
+import io
 import warnings
 from collections.abc import Iterable
+from typing import Collection
 from weakref import WeakValueDictionary
 
 from sapiopylib.rest.DataRecordManagerService import DataRecordManager
@@ -13,19 +15,28 @@ from sapiopylib.rest.pojo.datatype.FieldDefinition import FieldType
 from sapiopylib.rest.pojo.eln.SapioELNEnums import ElnBaseDataType
 from sapiopylib.rest.utils.autopaging import QueryDataRecordsAutoPager, QueryDataRecordByIdListAutoPager, \
     QueryAllRecordsOfTypeAutoPager
-from sapiopylib.rest.utils.recordmodel.PyRecordModel import PyRecordModel
+from sapiopylib.rest.utils.recordmodel.PyRecordModel import PyRecordModel, AbstractRecordModelPropertyGetter, \
+    RecordModelPropertyType, AbstractRecordModelPropertyAdder, AbstractRecordModelPropertySetter, \
+    AbstractRecordModelPropertyRemover
 from sapiopylib.rest.utils.recordmodel.RecordModelManager import RecordModelManager, RecordModelInstanceManager, \
     RecordModelRelationshipManager
 from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedType, WrappedRecordModel
 from sapiopylib.rest.utils.recordmodel.RelationshipPath import RelationshipPath, RelationshipNode, \
     RelationshipNodeType
 from sapiopylib.rest.utils.recordmodel.ancestry import RecordModelAncestorManager
+from sapiopylib.rest.utils.recordmodel.properties import Parents, Parent, Children, Child, ForwardSideLink
 
 from sapiopycommons.general.aliases import RecordModel, SapioRecord, FieldMap, FieldIdentifier, AliasUtil, \
-    FieldIdentifierMap, FieldValue, UserIdentifier, FieldIdentifierKey
+    FieldIdentifierMap, FieldValue, UserIdentifier, FieldIdentifierKey, DataTypeIdentifier
 from sapiopycommons.general.custom_report_util import CustomReportUtil
 from sapiopycommons.general.exceptions import SapioException
 
+# Aliases for longer name.
+_PropertyGetter = AbstractRecordModelPropertyGetter
+_PropertyAdder = AbstractRecordModelPropertyAdder
+_PropertyRemover = AbstractRecordModelPropertyRemover
+_PropertySetter = AbstractRecordModelPropertySetter
+_PropertyType = RecordModelPropertyType
 
 # FR-46064 - Initial port of PyWebhookUtils to sapiopycommons.
 class RecordHandler:
@@ -58,12 +69,11 @@ class RecordHandler:
         """
         :param context: The current webhook context or a user object to send requests from.
         """
-        self.user = AliasUtil.to_sapio_user(context)
         if self.__initialized:
             return
         self.__initialized = True
 
-        self.user = context if isinstance(context, SapioUser) else context.user
+        self.user = AliasUtil.to_sapio_user(context)
         self.dr_man = DataRecordManager(self.user)
         self.rec_man = RecordModelManager(self.user)
         self.inst_man = self.rec_man.instance_manager
@@ -104,8 +114,10 @@ class RecordHandler:
         return [self.wrap_model(x, wrapper_type) for x in records]
 
     # CR-47491: Support providing a data type name string to receive PyRecordModels instead of requiring a WrapperType.
+    # CR-47523: Support a singular field value being provided for the value_list parameter.
     def query_models(self, wrapper_type: type[WrappedType] | str, field: FieldIdentifier,
-                     value_list: Iterable[FieldValue], page_limit: int | None = None, page_size: int | None = None) \
+                     value_list: Iterable[FieldValue] | FieldValue,
+                     page_limit: int | None = None, page_size: int | None = None) \
             -> list[WrappedType] | list[PyRecordModel]:
         """
         Shorthand for using the data record manager to query for a list of data records by field value
@@ -113,7 +125,9 @@ class RecordHandler:
 
         :param wrapper_type: The record model wrapper to use, or the data type name of the records.
         :param field: The field to query on.
-        :param value_list: The values of the field to query on.
+        :param value_list: The values of the field to query on, or a singular field value that will be automatically
+            converted to a singleton list. Note that field values of None are not supported by this method and will be
+            ignored. If you need to query for records with a null field value, use a custom report.
         :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages. This parameter
             only functions if you set a page size or the platform enforces a page size.
         :param page_size: The size of the pages to query. If None, the page size may be limited by the platform.
@@ -126,8 +140,10 @@ class RecordHandler:
         return self.query_models_with_criteria(wrapper_type, field, value_list, criteria, page_limit)[0]
 
     def query_and_map_models(self, wrapper_type: type[WrappedType] | str, field: FieldIdentifier,
-                             value_list: Iterable[FieldValue], page_limit: int | None = None,
-                             page_size: int | None = None, *, mapping_field: FieldIdentifier | None = None) \
+                             value_list: Iterable[FieldValue] | FieldValue,
+                             page_limit: int | None = None, page_size: int | None = None,
+                             *,
+                             mapping_field: FieldIdentifier | None = None) \
             -> dict[FieldValue, list[WrappedType] | list[PyRecordModel]]:
         """
         Shorthand for using query_models to search for records given values on a specific field and then using
@@ -135,7 +151,9 @@ class RecordHandler:
 
         :param wrapper_type: The record model wrapper to use, or the data type name of the records.
         :param field: The field to query and map on.
-        :param value_list: The values of the field to query on.
+        :param value_list: The values of the field to query on, or a singular field value that will be automatically
+            converted to a singleton list. Note that field values of None are not supported by this method and will be
+            ignored. If you need to query for records with a null field value, use a custom report.
         :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages. This parameter
             only functions if you set a page size or the platform enforces a page size.
         :param page_size: The size of the pages to query. If None, the page size may be limited by the platform.
@@ -150,8 +168,10 @@ class RecordHandler:
                                  mapping_field)
 
     def query_and_unique_map_models(self, wrapper_type: type[WrappedType] | str, field: FieldIdentifier,
-                                    value_list: Iterable[FieldValue], page_limit: int | None = None,
-                                    page_size: int | None = None, *, mapping_field: FieldIdentifier | None = None) \
+                                    value_list: Iterable[FieldValue] | FieldValue,
+                                    page_limit: int | None = None, page_size: int | None = None,
+                                    *,
+                                    mapping_field: FieldIdentifier | None = None) \
             -> dict[FieldValue, WrappedType | PyRecordModel]:
         """
         Shorthand for using query_models to search for records given values on a specific field and then using
@@ -160,7 +180,9 @@ class RecordHandler:
 
         :param wrapper_type: The record model wrapper to use, or the data type name of the records.
         :param field: The field to query and map on.
-        :param value_list: The values of the field to query on.
+        :param value_list: The values of the field to query on, or a singular field value that will be automatically
+            converted to a singleton list. Note that field values of None are not supported by this method and will be
+            ignored. If you need to query for records with a null field value, use a custom report.
         :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages. This parameter
             only functions if you set a page size or the platform enforces a page size.
         :param page_size: The size of the pages to query. If None, the page size may be limited by the platform.
@@ -175,7 +197,7 @@ class RecordHandler:
                                         mapping_field)
 
     def query_models_with_criteria(self, wrapper_type: type[WrappedType] | str, field: FieldIdentifier,
-                                   value_list: Iterable[FieldValue],
+                                   value_list: Iterable[FieldValue] | FieldValue,
                                    paging_criteria: DataRecordPojoPageCriteria | None = None,
                                    page_limit: int | None = None) \
             -> tuple[list[WrappedType] | list[PyRecordModel], DataRecordPojoPageCriteria]:
@@ -185,7 +207,9 @@ class RecordHandler:
 
         :param wrapper_type: The record model wrapper to use, or the data type name of the records.
         :param field: The field to query on.
-        :param value_list: The values of the field to query on.
+        :param value_list: The values of the field to query on, or a singular field value that will be automatically
+            converted to a singleton list. Note that field values of None are not supported by this method and will be
+            ignored. If you need to query for records with a null field value, use a custom report.
         :param paging_criteria: The paging criteria to start the query with.
         :param page_limit: The maximum number of pages to query from the starting criteria. If None, exhausts all
             possible pages. This parameter only functions if you set a page size in the paging criteria or the platform
@@ -197,6 +221,8 @@ class RecordHandler:
         if isinstance(wrapper_type, str):
             wrapper_type = None
         field: str = AliasUtil.to_data_field_name(field)
+        if isinstance(value_list, FieldValue):
+            value_list: list[FieldValue] = [value_list]
         pager = QueryDataRecordsAutoPager(dt, field, list(value_list), self.user, paging_criteria)
         pager.max_page = page_limit
         return self.wrap_models(pager.get_all_at_once(), wrapper_type), pager.next_page_criteria
@@ -357,7 +383,7 @@ class RecordHandler:
             raise SapioException("Unrecognized report object.")
 
         # Using the bracket accessor because we want to throw an exception if RecordId doesn't exist in the report.
-        # This should only possibly be the case with system reports, as quick reports will include the record ID and
+        # This should only possibly be the case with system reports, as quick reports will include the record ID, and
         # we forced any given custom report to have a record ID column.
         ids: list[int] = [row["RecordId"] for row in results]
         return self.query_models_by_id(wrapper_type, ids)
@@ -523,6 +549,279 @@ class RecordHandler:
         secondary_identifiers.update({primary_identifier: id_value})
         return self.create_models_with_data(wrapper_type, [secondary_identifiers])[0]
 
+    # FR-47525: Add functions for getting and setting record image bytes.
+    def get_record_image(self, record: SapioRecord) -> bytes:
+        """
+        Retrieve the record image for a given record.
+
+        :param record: The record model to retrieve the image of.
+        :return: The file bytes of the given record's image.
+        """
+        record: DataRecord = AliasUtil.to_data_record(record)
+        with io.BytesIO() as data_sink:
+            def consume_data(chunk: bytes):
+                data_sink.write(chunk)
+
+            self.dr_man.get_record_image(record, consume_data)
+            data_sink.flush()
+            data_sink.seek(0)
+            file_bytes = data_sink.read()
+        return file_bytes
+
+    def set_record_image(self, record: SapioRecord, file_data: str | bytes) -> None:
+        """
+        Set the record image for a given record.
+
+        :param record: The record model to set the image of.
+        :param file_data: The file data of the image to set on the record.
+        """
+        record: DataRecord = AliasUtil.to_data_record(record)
+        with io.BytesIO(file_data.encode() if isinstance(file_data, str) else file_data) as stream:
+            self.dr_man.set_record_image(record, stream)
+
+    # FR-47522: Add RecordHandler functions that copy from the RecordModelUtil class in our Java utilities.
+    @staticmethod
+    def get_values_list(records: list[RecordModel], field: FieldIdentifier) -> list[FieldValue]:
+        """
+        Get a list of field values from a list of record models.
+
+        :param records: The list of record models to get the field values from.
+        :param field: The field to get the values of.
+        :return: A list of field values from the input record models. The values are in the same order as the input
+            record models.
+        """
+        field: str = AliasUtil.to_data_field_name(field)
+        return [x.get_field_value(field) for x in records]
+
+    @staticmethod
+    def get_values_set(records: list[RecordModel], field: FieldIdentifier) -> set[FieldValue]:
+        """
+        Get a set of field values from a list of record models.
+
+        :param records: The list of record models to get the field values from.
+        :param field: The field to get the values of.
+        :return: A set of field values from the input record models.
+        """
+        field: str = AliasUtil.to_data_field_name(field)
+        return {x.get_field_value(field) for x in records}
+
+    @staticmethod
+    def set_values(records: list[RecordModel], field: FieldIdentifier, value: FieldValue) -> None:
+        """
+        Set the value of a field on a list of record models.
+
+        :param records: The list of record models to set the field value on.
+        :param field: The field to set the value of.
+        :param value: The value to set the field to for all input records.
+        """
+        field: str = AliasUtil.to_data_field_name(field)
+        for record in records:
+            record.set_field_value(field, value)
+
+    @staticmethod
+    def get_min_record(records: list[RecordModel], field: FieldIdentifier) -> RecordModel:
+        """
+        Get the record model with the minimum value of a given field from a list of record models.
+
+        :param records: The list of record models to search through.
+        :param field: The field to find the minimum value of.
+        :return: The record model with the minimum value of the given field.
+        """
+        field: str = AliasUtil.to_data_field_name(field)
+        return min(records, key=lambda x: x.get_field_value(field))
+
+    @staticmethod
+    def get_max_record(records: list[RecordModel], field: FieldIdentifier) -> RecordModel:
+        """
+        Get the record model with the maximum value of a given field from a list of record models.
+
+        :param records: The list of record models to search through.
+        :param field: The field to find the maximum value of.
+        :return: The record model with the maximum value of the given field.
+        """
+        field: str = AliasUtil.to_data_field_name(field)
+        return max(records, key=lambda x: x.get_field_value(field))
+
+    @staticmethod
+    def get_from_all(records: Iterable[RecordModel], getter: _PropertyGetter[_PropertyType]) -> list[_PropertyType]:
+        """
+        Use a getter property on all records in a list of record models. For example, you can iterate over a list of
+        record models using a getter of Ancestors.of_type(SampleModel) to get all the SampleModel ancestors from each
+        record.
+
+        :param records: The list of record models to get the property from.
+        :param getter: The getter to use to get the property from each record.
+        :return: A list of the property values from the input record models. The value at the matching index of the
+            input records is the results of using the getter on that record.
+        """
+        return [x.get(getter) for x in records]
+
+    @staticmethod
+    def set_on_all(records: Iterable[RecordModel], setter: _PropertySetter[_PropertyType]) -> list[_PropertyType]:
+        """
+        Use a setter property on all records in a list of record models. For example, you can iterate over a list of
+        record models user a setter of ForwardSideLink.ref(field_name, record) to set a forward side link on each
+        record.
+
+        :param records: The list of record models to set the property on.
+        :param setter: The setter to use to set the property on each record.
+        :return: A list of the property values that were set on the input record models. The value at the matching index
+            of the input records is the results of using the setter on that record.
+        """
+        return [x.set(setter) for x in records]
+
+    @staticmethod
+    def add_to_all(records: Iterable[RecordModel], adder: _PropertyAdder[_PropertyType]) -> list[_PropertyType]:
+        """
+        Use an adder property on all records in a list of record models. For example, you can iterate over a list of
+        record models using an adder of Child.create(SampleModel) to create a new SampleModel child on each record.
+
+        :param records: The list of record models to add the property to.
+        :param adder: The adder to use to add the property to each record.
+        :return: A list of the property values that were added to the input record models. The value at the matching
+            index of the input records is the results of using the adder on that record.
+        """
+        return [x.add(adder) for x in records]
+
+    @staticmethod
+    def remove_from_all(records: Iterable[RecordModel], remover: _PropertyRemover[_PropertyType]) -> list[_PropertyType]:
+        """
+        Use a remover property on all records in a list of record models. For example, you can iterate over a list of
+        record models using a remover of Parents.ref(records) to remove a list of parents from each record.
+
+        :param records: The list of record models to remove the property from.
+        :param remover: The remover to use to remove the property from each record.
+        :return: A list of the property values that were removed from the input record models. The value at the matching
+            index of the input records is the results of using the remover on that record.
+        """
+        return [x.remove(remover) for x in records]
+
+    # FR-47527: Created functions for manipulating relationships between records,
+    def get_extension(self, model: RecordModel, wrapper_type: type[WrappedType] | str) \
+            -> WrappedType | PyRecordModel | None:
+        """
+        Given a record with an extension record related to it, return the extension record as a record model.
+        This will retrieve an extension record without doing a webservice request to the server. The input record and
+        extension record will be considered related to one another if you later use load_child or load_parent on the
+        input record or extension record respectively.
+
+        :param model: The record model to get the extension for.
+        :param wrapper_type: The record model wrapper to use, or the data type name of the extension record. If a data
+            type name is provided, the returned record will be a PyRecordModel instead of a WrappedRecordModel.
+        :return: The extension record model for the input record model, or None if no extension record exists.
+        """
+        ext_dt: str = AliasUtil.to_data_type_name(wrapper_type)
+        ext_fields: FieldMap = {}
+        for field, value in AliasUtil.to_field_map(model).items():
+            if field.startswith(ext_dt + "."):
+                ext_fields[field.removeprefix(ext_dt + ".")] = value
+        if not ext_fields or ext_fields.get("RecordId") is None:
+            return None
+        ext_rec: DataRecord = DataRecord(ext_dt, ext_fields.get("RecordId"), ext_fields)
+        ext_model: WrappedType | PyRecordModel = self.wrap_model(ext_rec, wrapper_type)
+        self._spoof_child_load(model, ext_model)
+        self._spoof_parent_load(ext_model, model)
+        return ext_model
+
+    def get_or_add_parent(self, record: RecordModel, parent_type: type[WrappedType] | str) \
+            -> WrappedType | PyRecordModel:
+        """
+        Given a record model, retrieve the singular parent record model of a given type. If a parent of the given type
+        does not exist, a new one will be created. The parents of the given data type must already be loaded.
+
+        :param record: The record model to get the parent of.
+        :param parent_type: The record model wrapper of the parent, or the data type name of the parent. If a data type
+            name is provided, the returned record will be a PyRecordModel instead of a WrappedRecordModel.
+        :return: The parent record model of the given type.
+        """
+        parent_dt: str = AliasUtil.to_data_type_name(parent_type)
+        wrapper: type[WrappedType] | None = parent_type if isinstance(parent_type, type) else None
+        record: PyRecordModel = RecordModelInstanceManager.unwrap(record)
+        parent: PyRecordModel | None = record.get_parent_of_type(parent_dt)
+        if parent is not None:
+            return self.wrap_model(parent, wrapper) if wrapper else parent
+        return record.add(Parent.create(wrapper)) if wrapper else record.add(Parent.create_by_name(parent_dt))
+
+    def get_or_add_child(self, record: RecordModel, child_type: type[WrappedType] | str) -> WrappedType | PyRecordModel:
+        """
+        Given a record model, retrieve the singular child record model of a given type. If a child of the given type
+        does not exist, a new one will be created. The children of the given data type must already be loaded.
+
+        :param record: The record model to get the child of.
+        :param child_type: The record model wrapper of the child, or the data type name of the child. If a data type
+            name is provided, the returned record will be a PyRecordModel instead of a WrappedRecordModel.
+        :return: The child record model of the given type.
+        """
+        child_dt: str = AliasUtil.to_data_type_name(child_type)
+        wrapper: type[WrappedType] | None = child_type if isinstance(child_type, type) else None
+        record: PyRecordModel = RecordModelInstanceManager.unwrap(record)
+        child: PyRecordModel | None = record.get_child_of_type(child_dt)
+        if child is not None:
+            return self.wrap_model(child, wrapper) if wrapper else child
+        return record.add(Child.create(wrapper)) if wrapper else record.add(Child.create_by_name(child_dt))
+
+    def get_or_add_side_link(self, record: RecordModel, side_link_field: FieldIdentifier,
+                             side_link_type: type[WrappedType] | str) -> WrappedType | PyRecordModel:
+        """
+        Given a record model, retrieve the singular side link record model of a given type. If a side link of the given
+        type does not exist, a new one will be created. The side links of the given data type must already be loaded.
+
+        :param record: The record model to get the side link of.
+        :param side_link_field: The field name of the side link to get.
+        :param side_link_type: The record model wrapper of the side link, or the data type name of the side link. If a
+            data type name is provided, the returned record will be a PyRecordModel instead of a WrappedRecordModel.
+        :return: The side link record model of the given type.
+        """
+        side_link_field: str = AliasUtil.to_data_field_name(side_link_field)
+        wrapper: type[WrappedType] | None = side_link_type if isinstance(side_link_type, type) else None
+        record: PyRecordModel = RecordModelInstanceManager.unwrap(record)
+        side_link: PyRecordModel | None = record.get_forward_side_link(side_link_field)
+        if side_link is not None:
+            return self.wrap_model(side_link, wrapper) if wrapper else side_link
+        side_link: WrappedType | PyRecordModel = self.add_model(side_link_type)
+        record.set(ForwardSideLink.ref(side_link_field, side_link))
+        return side_link
+
+    @staticmethod
+    def set_parents(record: RecordModel, parents: Iterable[RecordModel], parent_type: DataTypeIdentifier) -> None:
+        """
+        Set the parents of a record model to a list of parent record models of a given type. The parents of the given
+        data type must already be loaded. This method will add the parents to the record model if they are not already
+        parents, and remove any existing parents that are not in the input list.
+
+        :param record: The record model to set the parents of.
+        :param parents: The list of parent record models to set as the parents of the input record model.
+        :param parent_type: The data type identifier of the parent record models.
+        """
+        parent_dt: str = AliasUtil.to_data_type_name(parent_type)
+        existing_parents: list[PyRecordModel] = record.get(Parents.of_type_name(parent_dt))
+        for parent in parents:
+            if parent not in existing_parents:
+                record.add(Parent.ref(parent))
+        for parent in existing_parents:
+            if parent not in parents:
+                record.remove(Parent.ref(parent))
+
+    @staticmethod
+    def set_children(record: RecordModel, children: Iterable[RecordModel], child_type: DataTypeIdentifier) -> None:
+        """
+        Set the children of a record model to a list of child record models of a given type. The children of the given
+        data type must already be loaded. This method will add the children to the record model if they are not already
+        children, and remove any existing children that are not in the input list.
+
+        :param record: The record model to set the children of.
+        :param children: The list of child record models to set as the children of the input record model.
+        :param child_type: The data type identifier of the child record models.
+        """
+        child_dt: str = AliasUtil.to_data_type_name(child_type)
+        existing_children: list[PyRecordModel] = record.get(Children.of_type_name(child_dt))
+        for child in children:
+            if child not in existing_children:
+                record.add(Child.ref(child))
+        for child in existing_children:
+            if child not in children:
+                record.remove(Child.ref(child))
+
     @staticmethod
     def map_to_parent(models: Iterable[WrappedRecordModel], parent_type: type[WrappedType])\
             -> dict[WrappedRecordModel, WrappedType]:
@@ -904,7 +1203,7 @@ class RecordHandler:
         return field_sum
 
     @staticmethod
-    def mean_of_field(models: Iterable[SapioRecord], field_name: FieldIdentifier) -> float:
+    def mean_of_field(models: Collection[SapioRecord], field_name: FieldIdentifier) -> float:
         """
         Calculate the mean of the numeric value of a given field across all input models. Excepts that all given models
         have a value. If the field is an integer field, the value will be converted to a float.
@@ -913,7 +1212,7 @@ class RecordHandler:
         :param field_name: The name of the numeric field to mean.
         :return: The mean of the field values for the collection of models.
         """
-        return RecordHandler.sum_of_field(models, field_name) / len(list(models))
+        return RecordHandler.sum_of_field(models, field_name) / len(models)
 
     @staticmethod
     def get_newest_record(records: Iterable[SapioRecord]) -> SapioRecord:
@@ -923,11 +1222,7 @@ class RecordHandler:
         :param records: The list of records.
         :return: The input record with the highest record ID. None if the input list is empty.
         """
-        newest: SapioRecord | None = None
-        for record in records:
-            if newest is None or record.record_id > newest.record_id:
-                newest = record
-        return newest
+        return max(records, key=lambda x: x.record_id)
 
     # FR-46696: Add a function for getting the oldest record in a list, just like we have one for the newest record.
     @staticmethod
@@ -938,11 +1233,7 @@ class RecordHandler:
         :param records: The list of records.
         :return: The input record with the lowest record ID. None if the input list is empty.
         """
-        oldest: SapioRecord | None = None
-        for record in records:
-            if oldest is None or record.record_id < oldest.record_id:
-                oldest = record
-        return oldest
+        return min(records, key=lambda x: x.record_id)
 
     @staticmethod
     def values_to_field_maps(field_name: FieldIdentifier, values: Iterable[FieldValue],
@@ -1169,3 +1460,42 @@ class RecordHandler:
         if record_type != model_type:
             raise SapioException(f"Data record of type {record_type} cannot be wrapped by the record model wrapper "
                                  f"of type {model_type}")
+
+    @staticmethod
+    def _spoof_child_load(model: RecordModel, child: RecordModel) -> None:
+        """
+        Spoof the loading of a child record on a record model. This is useful for when you have records that you know
+        are related but didn't use the relationship manager to load the relationship, which would make a webservice
+        call.
+        """
+        RecordHandler._spoof_children_load(model, [child])
+
+    @staticmethod
+    def _spoof_children_load(model: RecordModel, children: list[RecordModel]) -> None:
+        """
+        Spoof the loading of child records on a record model. This is useful for when you have records that you know
+        are related but didn't use the relationship manager to load the relationship, which would make a webservice
+        """
+        model: PyRecordModel = RecordModelInstanceManager.unwrap(model)
+        child_dt: str = AliasUtil.to_singular_data_type_name(children)
+        # noinspection PyProtectedMember
+        model._mark_children_loaded(child_dt, RecordModelInstanceManager.unwrap_list(children))
+
+    @staticmethod
+    def _spoof_parent_load(model: RecordModel, parent: RecordModel) -> None:
+        """
+        Spoof the loading of a parent record on a record model. This is useful for when you have records that you know
+        are related but didn't use the relationship manager to load the relationship, which would make a webservice
+        """
+        RecordHandler._spoof_parents_load(model, [parent])
+
+    @staticmethod
+    def _spoof_parents_load(model: RecordModel, parents: list[RecordModel]) -> None:
+        """
+        Spoof the loading of parent records on a record model. This is useful for when you have records that you know
+        are related but didn't use the relationship manager to load the relationship, which would make a webservice
+        """
+        model: PyRecordModel = RecordModelInstanceManager.unwrap(model)
+        parent_dt: str = AliasUtil.to_singular_data_type_name(parents)
+        # noinspection PyProtectedMember
+        model._mark_children_loaded(parent_dt, RecordModelInstanceManager.unwrap_list(parents))

sapiopycommons/rules/eln_rule_handler.py

@@ -126,12 +126,16 @@ class ElnRuleHandler:
         """
         return list(self._entry_to_field_maps.keys())
 
+    # CR-47529: Add info about HVDT behavior to the docstring of these functions.
     def get_records(self, data_type: DataTypeIdentifier, entry: str | None = None) -> list[DataRecord]:
         """
         Get records from the cached context with the given data type. Capable of being filtered to searching within
         the context of an entry name. If the given data type or entry does not exist in the context,
         returns an empty list.
 
+        Note that if you are attempting to retrieve record that are high volume data types and are receiving nothing,
+        the HVDTs may have been sent as field maps. Consider using the get_field_maps function if this occurs.
+
         :param data_type: The data type of the records to return.
         :param entry: The name of the entry to grab the records from. If None, returns the records that match the data
             type from every entry. If an entry is provided, but it does not exist in the context, returns an empty list.
@@ -150,7 +154,7 @@ class ElnRuleHandler:
 
         Field maps will only exist in the context if the data record that the fields are from is no longer accessible
         to the user. This can occur because the data record was deleted, or because the user does not have access to the
-        record due to ACL.
+        record due to ACL. This can also occur under certain circumstances if the records are HVDTs.
 
         :param data_type: The data type of the field maps to return.
         :param entry: The name of the entry to grab the field maps from. If None, returns the field maps that match the
@@ -170,6 +174,9 @@ class ElnRuleHandler:
         within the context of an entry name. If the given data type or entry does not exist in the context,
         returns an empty list.
 
+        Note that if you are attempting to retrieve record that are high volume data types and are receiving nothing,
+        the HVDTs may have been sent as field maps. Consider using the get_field_maps function if this occurs.
+
         :param wrapper_type: The record model wrapper or data type name of the record to get from the context.
         :param entry: The name of the entry to grab the records from. If None, returns the records that match the data
             type from every entry. If an entry is provided, but it does not exist in the context, returns an empty list.

sapiopycommons/rules/on_save_rule_handler.py

@@ -122,12 +122,16 @@ class OnSaveRuleHandler:
         """
         return list(self._base_id_to_field_maps.keys())
 
+    # CR-47529: Add info about HVDT behavior to the docstring of these functions.
     def get_records(self, data_type: DataTypeIdentifier, record_id: int | None = None) -> list[DataRecord]:
         """
         Get records from the cached context with the given data type. Capable of being filtered to searching within
         the context of a record ID. If the given data type or record ID does not exist in the context,
         returns an empty list.
 
+        Note that if you are attempting to retrieve record that are high volume data types and are receiving nothing,
+        the HVDTs may have been sent as field maps. Consider using the get_field_maps function if this occurs.
+
         :param data_type: The data type of the records to return.
         :param record_id: The record ID of the base record to search from. If None, returns the records that match the
             data type from every ID. If an ID is provided, but it does not exist in the context, returns an empty list.
@@ -146,7 +150,7 @@ class OnSaveRuleHandler:
 
         Field maps will only exist in the context if the data record that the fields are from is no longer accessible
         to the user. This can occur because the data record was deleted, or because the user does not have access to the
-        record due to ACL.
+        record due to ACL. This can also occur under certain circumstances if the records are HVDTs.
 
         :param data_type: The data type of the field maps to return.
         :param record_id: The record ID of the base record to search from. If None, returns the field maps that match
@@ -166,6 +170,9 @@ class OnSaveRuleHandler:
         the context of a record ID. If the given data type or record ID does not exist in the context,
         returns an empty list.
 
+        Note that if you are attempting to retrieve record that are high volume data types and are receiving nothing,
+        the HVDTs may have been sent as field maps. Consider using the get_field_maps function if this occurs.
+
         :param wrapper_type: The record model wrapper or data type name of the record to get from the context.
         :param record_id: The record ID of the base record to search from. If None, returns the records that match the
             data type from ID. If an ID is provided, but it does not exist in the context, returns an empty list.

sapiopycommons/webhook/webhook_handlers.py

@@ -220,6 +220,9 @@ class CommonsWebhookHandler(AbstractWebhookHandler):
         else:
             self.custom_context = None
 
+        # CR-47526: Set the dialog timeout to 1 hour by default. This can be overridden by the webhook.
+        self.callback.set_dialog_timeout(3600)
+
         # Set the default display types, titles, and messages for each type of exception that can display a message.
         self.default_user_error_display_type = MessageDisplayType.TOASTER_WARNING
         self.default_critical_error_display_type = MessageDisplayType.DISPLAY_ERROR

sapiopycommons/webhook/webservice_handlers.py

@@ -3,7 +3,7 @@ import traceback
 from abc import abstractmethod, ABC
 from base64 import b64decode
 from logging import Logger
-from typing import Any
+from typing import Any, Mapping
 
 from flask import request, Response, Request
 from sapiopylib.rest.DataRecordManagerService import DataRecordManager
@@ -122,7 +122,7 @@ class AbstractWebserviceHandler(AbstractWebhookHandler):
         """
         pass
 
-    def authenticate_user(self, headers: dict[str, str]) -> SapioUser:
+    def authenticate_user(self, headers: Mapping[str, str]) -> SapioUser:
         """
         Authenticate a user for making requests to a Sapio server using the provided headers. If no user can be
         authenticated, then an exception will be thrown.

{sapiopycommons-2025.5.6a512.dist-info → sapiopycommons-2025.5.7a514.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sapiopycommons
-Version: 2025.5.6a512
+Version: 2025.5.7a514
 Summary: Official Sapio Python API Utilities Package
 Project-URL: Homepage, https://github.com/sapiosciences
 Author-email: Jonathan Steck <jsteck@sapiosciences.com>, Yechen Qiao <yqiao@sapiosciences.com>
@@ -17,7 +17,7 @@ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: databind>=4.5
-Requires-Dist: sapiopylib>=2024.5.24.210
+Requires-Dist: sapiopylib>=2025.4.17.264
 Description-Content-Type: text/markdown