sapiopycommons 2025.5.20a539__py3-none-any.whl → 2025.5.30a548__py3-none-any.whl

sapiopycommons/recordmodel/record_handler.py

@@ -39,6 +39,7 @@ _PropertySetter = AbstractRecordModelPropertySetter
 _PropertyType = RecordModelPropertyType
 
 # FR-46064 - Initial port of PyWebhookUtils to sapiopycommons.
+# FR-47575 - Reordered functions so that the Java and Python versions are as close to each other as possible.
 class RecordHandler:
     """
     A collection of shorthand methods for dealing with the various record managers.
@@ -113,6 +114,167 @@ class RecordHandler:
         """
         return [self.wrap_model(x, wrapper_type) for x in records]
 
+    def add_model(self, wrapper_type: type[WrappedType] | str) -> WrappedType | PyRecordModel:
+        """
+        Shorthand for using the instance manager to add a new record model of the given type.
+
+        :param wrapper_type: The record model wrapper to use, or the data type name of the record.
+        :return: The newly added record model. If a data type name was used instead of a model wrapper, then the
+            returned record will be a PyRecordModel instead of a WrappedRecordModel.
+        """
+        return self.add_models(wrapper_type, 1)[0]
+
+    def add_models(self, wrapper_type: type[WrappedType] | str, num: int) -> list[WrappedType] | list[PyRecordModel]:
+        """
+        Shorthand for using the instance manager to add new record models of the given type.
+
+        :param wrapper_type: The record model wrapper to use, or the data type name of the records.
+        :param num: The number of models to create.
+        :return: The newly added record models. If a data type name was used instead of a model wrapper, then the
+            returned records will be PyRecordModels instead of WrappedRecordModels.
+        """
+        if isinstance(wrapper_type, str):
+            return self.inst_man.add_new_records(wrapper_type, num)
+        return self.inst_man.add_new_records_of_type(num, wrapper_type)
+
+    def add_models_with_data(self, wrapper_type: type[WrappedType] | str, fields: list[FieldIdentifierMap]) \
+            -> list[WrappedType] | list[PyRecordModel]:
+        """
+        Shorthand for using the instance manager to add new models of the given type, and then initializing all those
+        models with the given fields.
+
+        :param wrapper_type: The record model wrapper to use, or the data type name of the records.
+        :param fields: A list of field maps to initialize the record models with.
+        :return: The newly added record models with the provided fields set. The records will be in the same order as
+            the fields in the fields list. If a data type name was used instead of a model wrapper, then the returned
+            records will be PyRecordModels instead of WrappedRecordModels.
+        """
+        fields: list[FieldMap] = AliasUtil.to_data_field_names_list_dict(fields)
+        models: list[WrappedType] = self.add_models(wrapper_type, len(fields))
+        for model, field_list in zip(models, fields):
+            model.set_field_values(field_list)
+        return models
+
+    def find_or_add_model(self, wrapper_type: type[WrappedType] | str, primary_identifier: FieldIdentifier,
+                          id_value: FieldValue, secondary_identifiers: FieldIdentifierMap | None = None) \
+            -> WrappedType | PyRecordModel:
+        """
+        Find a unique record that matches the given field values. If no such records exist, add a record model to the
+        cache with the identifying fields set to the desired values. This record will be created in the system when
+        you store and commit changes. If more than one record with the identifying values exists, throws an exception.
+
+        The record is searched for using the primary identifier field name and value. If multiple records are returned
+        by the query on this primary identifier, then the secondary identifiers are used to filter the results.
+
+        Makes a webservice call to query for the existing record.
+
+        :param wrapper_type: The record model wrapper to use, or the data type name of the record.
+        :param primary_identifier: The data field name of the field to search on.
+        :param id_value: The value of the identifying field to search for.
+        :param secondary_identifiers: Optional fields used to filter the records that are returned after searching on
+            the primary identifier.
+        :return: The record model with the identifying field value, either pulled from the system or newly created.
+            If a data type name was used instead of a model wrapper, then the returned record will be a PyRecordModel
+            instead of a WrappedRecordModel.
+        """
+        # PR-46335: Initialize the secondary identifiers parameter if None is provided to avoid an exception.
+        # If no secondary identifiers were provided, use an empty dictionary.
+        if secondary_identifiers is None:
+            secondary_identifiers = {}
+
+        primary_identifier: str = AliasUtil.to_data_field_name(primary_identifier)
+        secondary_identifiers: FieldMap = AliasUtil.to_data_field_names_dict(secondary_identifiers)
+        unique_record: WrappedType | None = self.__find_model(wrapper_type, primary_identifier, id_value,
+                                                              secondary_identifiers)
+        # If a unique record matched the identifiers, return it.
+        if unique_record is not None:
+            return unique_record
+
+        # If none of the results matched the identifiers, create a new record with all identifiers set.
+        # Put the primary identifier and value into the secondary identifiers list and use that as the fields map
+        # for this new record.
+        secondary_identifiers.update({primary_identifier: id_value})
+        return self.add_models_with_data(wrapper_type, [secondary_identifiers])[0]
+
+    def create_models(self, wrapper_type: type[WrappedType] | str, num: int) -> list[WrappedType] | list[PyRecordModel]:
+        """
+        Shorthand for creating new records via the data record manager and then returning them as wrapped
+        record models. Useful in cases where your record model needs to have a valid record ID.
+
+        Makes a webservice call to create the data records.
+
+        :param wrapper_type: The record model wrapper to use, or the data type name of the records.
+        :param num: The number of new records to create.
+        :return: The newly created record models. If a data type name was used instead of a model wrapper, then the
+            returned records will be PyRecordModels instead of WrappedRecordModels.
+        """
+        dt: str = AliasUtil.to_data_type_name(wrapper_type)
+        if isinstance(wrapper_type, str):
+            wrapper_type = None
+        return self.wrap_models(self.dr_man.add_data_records(dt, num), wrapper_type)
+
+    def create_models_with_data(self, wrapper_type: type[WrappedType] | str, fields: list[FieldIdentifierMap]) \
+            -> list[WrappedType] | list[PyRecordModel]:
+        """
+        Shorthand for creating new records via the data record manager with field data to initialize the records with
+        and then returning them as wrapped record models. Useful in cases where your record model needs to have a valid
+        record ID.
+
+        Makes a webservice call to create the data records.
+
+        :param wrapper_type: The record model wrapper to use, or the data type name of the records.
+        :param fields: The field map list to initialize the new data records with.
+        :return: The newly created record models. If a data type name was used instead of a model wrapper, then the
+            returned records will be PyRecordModels instead of WrappedRecordModels.
+        """
+        dt: str = AliasUtil.to_data_type_name(wrapper_type)
+        if isinstance(wrapper_type, str):
+            wrapper_type = None
+        fields: list[FieldMap] = AliasUtil.to_data_field_names_list_dict(fields)
+        return self.wrap_models(self.dr_man.add_data_records_with_data(dt, fields), wrapper_type)
+
+    def find_or_create_model(self, wrapper_type: type[WrappedType] | str, primary_identifier: FieldIdentifier,
+                             id_value: FieldValue, secondary_identifiers: FieldIdentifierMap | None = None) \
+            -> WrappedType | PyRecordModel:
+        """
+        Find a unique record that matches the given field values. If no such records exist, create one with the
+        identifying fields set to the desired values. If more than one record with the identifying values exists,
+        throws an exception.
+
+        The record is searched for using the primary identifier field name and value. If multiple records are returned
+        by the query on this primary identifier, then the secondary identifiers are used to filter the results.
+
+        Makes a webservice call to query for the existing record. Makes an additional webservice call if the record
+        needs to be created.
+
+        :param wrapper_type: The record model wrapper to use, or the data type name of the record.
+        :param primary_identifier: The data field name of the field to search on.
+        :param id_value: The value of the identifying field to search for.
+        :param secondary_identifiers: Optional fields used to filter the records that are returned after searching on
+            the primary identifier.
+        :return: The record model with the identifying field value, either pulled from the system or newly created.
+            If a data type name was used instead of a model wrapper, then the returned record will be a PyRecordModel
+            instead of a WrappedRecordModel.
+        """
+        # PR-46335: Initialize the secondary identifiers parameter if None is provided to avoid an exception.
+        # If no secondary identifiers were provided, use an empty dictionary.
+        if secondary_identifiers is None:
+            secondary_identifiers = {}
+
+        primary_identifier: str = AliasUtil.to_data_field_name(primary_identifier)
+        secondary_identifiers: FieldMap = AliasUtil.to_data_field_names_dict(secondary_identifiers)
+        unique_record: WrappedType | None = self.__find_model(wrapper_type, primary_identifier, id_value,
+                                                              secondary_identifiers)
+        # If a unique record matched the identifiers, return it.
+        if unique_record is not None:
+            return unique_record
+
+        # If none of the results matched the identifiers, create a new record with all identifiers set.
+        # Put the primary identifier and value into the secondary identifiers list and use that as the fields map
+        # for this new record.
+        secondary_identifiers.update({primary_identifier: id_value})
+        return self.create_models_with_data(wrapper_type, [secondary_identifiers])[0]
+
     # 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,
@@ -388,196 +550,161 @@ class RecordHandler:
         ids: list[int] = [row["RecordId"] for row in results]
         return self.query_models_by_id(wrapper_type, ids)
 
-    def add_model(self, wrapper_type: type[WrappedType] | str) -> WrappedType | PyRecordModel:
+    @staticmethod
+    def map_by_id(models: Iterable[SapioRecord]) -> dict[int, SapioRecord]:
         """
-        Shorthand for using the instance manager to add a new record model of the given type.
+        Map the given records their record IDs.
 
-        :param wrapper_type: The record model wrapper to use, or the data type name of the record.
-        :return: The newly added record model. If a data type name was used instead of a model wrapper, then the
-            returned record will be a PyRecordModel instead of a WrappedRecordModel.
+        :param models: The records to map.
+        :return: A dict mapping the record ID to each record.
         """
-        return self.add_models(wrapper_type, 1)[0]
+        ret_dict: dict[int, SapioRecord] = {}
+        for model in models:
+            ret_dict.update({model.record_id: model})
+        return ret_dict
 
-    def add_models(self, wrapper_type: type[WrappedType] | str, num: int) -> list[WrappedType] | list[PyRecordModel]:
+    @staticmethod
+    def map_by_field(models: Iterable[SapioRecord], field_name: FieldIdentifier) \
+            -> dict[FieldValue, list[SapioRecord]]:
         """
-        Shorthand for using the instance manager to add new record models of the given type.
+        Map the given records by one of their fields. If any two records share the same field value, they'll appear in
+        the same value list.
 
-        :param wrapper_type: The record model wrapper to use, or the data type name of the records.
-        :param num: The number of models to create.
-        :return: The newly added record models. If a data type name was used instead of a model wrapper, then the
-            returned records will be PyRecordModels instead of WrappedRecordModels.
+        :param models: The records to map.
+        :param field_name: The field name to map against.
+        :return: A dict mapping field values to the records with that value.
         """
-        if isinstance(wrapper_type, str):
-            return self.inst_man.add_new_records(wrapper_type, num)
-        return self.inst_man.add_new_records_of_type(num, wrapper_type)
+        field_name: str = AliasUtil.to_data_field_name(field_name)
+        ret_dict: dict[FieldValue, list[SapioRecord]] = {}
+        for model in models:
+            val: FieldValue = model.get_field_value(field_name)
+            ret_dict.setdefault(val, []).append(model)
+        return ret_dict
 
-    def add_models_with_data(self, wrapper_type: type[WrappedType] | str, fields: list[FieldIdentifierMap]) \
-            -> list[WrappedType] | list[PyRecordModel]:
+    @staticmethod
+    def map_by_unique_field(models: Iterable[SapioRecord], field_name: FieldIdentifier) \
+            -> dict[FieldValue, SapioRecord]:
         """
-        Shorthand for using the instance manager to add new models of the given type, and then initializing all those
-        models with the given fields.
+        Uniquely map the given records by one of their fields. If any two records share the same field value, throws
+        an exception.
 
-        :param wrapper_type: The record model wrapper to use, or the data type name of the records.
-        :param fields: A list of field maps to initialize the record models with.
-        :return: The newly added record models with the provided fields set. The records will be in the same order as
-            the fields in the fields list. If a data type name was used instead of a model wrapper, then the returned
-            records will be PyRecordModels instead of WrappedRecordModels.
+        :param models: The records to map.
+        :param field_name: The field name to map against.
+        :return: A dict mapping field values to the record with that value.
         """
-        fields: list[FieldMap] = AliasUtil.to_data_field_names_list_dict(fields)
-        models: list[WrappedType] = self.add_models(wrapper_type, len(fields))
-        for model, field_list in zip(models, fields):
-            model.set_field_values(field_list)
-        return models
+        field_name: str = AliasUtil.to_data_field_name(field_name)
+        ret_dict: dict[FieldValue, SapioRecord] = {}
+        for model in models:
+            val: FieldValue = model.get_field_value(field_name)
+            if val in ret_dict:
+                raise SapioException(f"Value {val} encountered more than once in models list.")
+            ret_dict.update({val: model})
+        return ret_dict
 
-    def find_or_add_model(self, wrapper_type: type[WrappedType] | str, primary_identifier: FieldIdentifier,
-                          id_value: FieldValue, secondary_identifiers: FieldIdentifierMap | None = None) \
-            -> WrappedType | PyRecordModel:
+    # FR-47525: Add functions for getting and setting record image bytes.
+    def get_record_image(self, record: SapioRecord) -> bytes:
         """
-        Find a unique record that matches the given field values. If no such records exist, add a record model to the
-        cache with the identifying fields set to the desired values. This record will be created in the system when
-        you store and commit changes. If more than one record with the identifying values exists, throws an exception.
-
-        The record is searched for using the primary identifier field name and value. If multiple records are returned
-        by the query on this primary identifier, then the secondary identifiers are used to filter the results.
-
-        Makes a webservice call to query for the existing record.
+        Retrieve the record image for a given record.
 
-        :param wrapper_type: The record model wrapper to use, or the data type name of the record.
-        :param primary_identifier: The data field name of the field to search on.
-        :param id_value: The value of the identifying field to search for.
-        :param secondary_identifiers: Optional fields used to filter the records that are returned after searching on
-            the primary identifier.
-        :return: The record model with the identifying field value, either pulled from the system or newly created.
-            If a data type name was used instead of a model wrapper, then the returned record will be a PyRecordModel
-            instead of a WrappedRecordModel.
+        :param record: The record model to retrieve the image of.
+        :return: The file bytes of the given record's image.
         """
-        # PR-46335: Initialize the secondary identifiers parameter if None is provided to avoid an exception.
-        # If no secondary identifiers were provided, use an empty dictionary.
-        if secondary_identifiers is None:
-            secondary_identifiers = {}
-
-        primary_identifier: str = AliasUtil.to_data_field_name(primary_identifier)
-        secondary_identifiers: FieldMap = AliasUtil.to_data_field_names_dict(secondary_identifiers)
-        unique_record: WrappedType | None = self.__find_model(wrapper_type, primary_identifier, id_value,
-                                                              secondary_identifiers)
-        # If a unique record matched the identifiers, return it.
-        if unique_record is not None:
-            return unique_record
+        record: DataRecord = AliasUtil.to_data_record(record)
+        with io.BytesIO() as data_sink:
+            def consume_data(chunk: bytes):
+                data_sink.write(chunk)
 
-        # If none of the results matched the identifiers, create a new record with all identifiers set.
-        # Put the primary identifier and value into the secondary identifiers list and use that as the fields map
-        # for this new record.
-        secondary_identifiers.update({primary_identifier: id_value})
-        return self.add_models_with_data(wrapper_type, [secondary_identifiers])[0]
+            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 create_models(self, wrapper_type: type[WrappedType] | str, num: int) -> list[WrappedType] | list[PyRecordModel]:
+    def set_record_image(self, record: SapioRecord, file_data: str | bytes) -> None:
         """
-        Shorthand for creating new records via the data record manager and then returning them as wrapped
-        record models. Useful in cases where your record model needs to have a valid record ID.
-
-        Makes a webservice call to create the data records.
+        Set the record image for a given record.
 
-        :param wrapper_type: The record model wrapper to use, or the data type name of the records.
-        :param num: The number of new records to create.
-        :return: The newly created record models. If a data type name was used instead of a model wrapper, then the
-            returned records will be PyRecordModels instead of WrappedRecordModels.
+        :param record: The record model to set the image of.
+        :param file_data: The file data of the image to set on the record.
         """
-        dt: str = AliasUtil.to_data_type_name(wrapper_type)
-        if isinstance(wrapper_type, str):
-            wrapper_type = None
-        return self.wrap_models(self.dr_man.add_data_records(dt, num), wrapper_type)
+        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)
 
-    def create_models_with_data(self, wrapper_type: type[WrappedType] | str, fields: list[FieldIdentifierMap]) \
-            -> list[WrappedType] | list[PyRecordModel]:
+    @staticmethod
+    def sum_of_field(models: Iterable[SapioRecord], field_name: FieldIdentifier) -> float:
         """
-        Shorthand for creating new records via the data record manager with field data to initialize the records with
-        and then returning them as wrapped record models. Useful in cases where your record model needs to have a valid
-        record ID.
-
-        Makes a webservice call to create the data records.
+        Sum up 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.
 
-        :param wrapper_type: The record model wrapper to use, or the data type name of the records.
-        :param fields: The field map list to initialize the new data records with.
-        :return: The newly created record models. If a data type name was used instead of a model wrapper, then the
-            returned records will be PyRecordModels instead of WrappedRecordModels.
+        :param models: The models to calculate the sum of.
+        :param field_name: The name of the numeric field to sum.
+        :return: The sum of the field values for the collection of models.
         """
-        dt: str = AliasUtil.to_data_type_name(wrapper_type)
-        if isinstance(wrapper_type, str):
-            wrapper_type = None
-        fields: list[FieldMap] = AliasUtil.to_data_field_names_list_dict(fields)
-        return self.wrap_models(self.dr_man.add_data_records_with_data(dt, fields), wrapper_type)
+        field_name: str = AliasUtil.to_data_field_name(field_name)
+        field_sum: float = 0
+        for model in models:
+            val = model.get_field_value(field_name)
+            if isinstance(val, (int, float)):
+                field_sum += float(model.get_field_value(field_name))
+        return field_sum
 
-    def find_or_create_model(self, wrapper_type: type[WrappedType] | str, primary_identifier: FieldIdentifier,
-                             id_value: FieldValue, secondary_identifiers: FieldIdentifierMap | None = None) \
-            -> WrappedType | PyRecordModel:
+    @staticmethod
+    def mean_of_field(models: Collection[SapioRecord], field_name: FieldIdentifier) -> float:
         """
-        Find a unique record that matches the given field values. If no such records exist, create one with the
-        identifying fields set to the desired values. If more than one record with the identifying values exists,
-        throws an exception.
-
-        The record is searched for using the primary identifier field name and value. If multiple records are returned
-        by the query on this primary identifier, then the secondary identifiers are used to filter the results.
+        Calculate the average (arithmetic 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.
 
-        Makes a webservice call to query for the existing record. Makes an additional webservice call if the record
-        needs to be created.
+        :param models: The models to calculate the mean of.
+        :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(models)
 
-        :param wrapper_type: The record model wrapper to use, or the data type name of the record.
-        :param primary_identifier: The data field name of the field to search on.
-        :param id_value: The value of the identifying field to search for.
-        :param secondary_identifiers: Optional fields used to filter the records that are returned after searching on
-            the primary identifier.
-        :return: The record model with the identifying field value, either pulled from the system or newly created.
-            If a data type name was used instead of a model wrapper, then the returned record will be a PyRecordModel
-            instead of a WrappedRecordModel.
+    @staticmethod
+    def get_newest_record(records: Iterable[SapioRecord]) -> SapioRecord:
         """
-        # PR-46335: Initialize the secondary identifiers parameter if None is provided to avoid an exception.
-        # If no secondary identifiers were provided, use an empty dictionary.
-        if secondary_identifiers is None:
-            secondary_identifiers = {}
+        Get the newest record from a list of records.
 
-        primary_identifier: str = AliasUtil.to_data_field_name(primary_identifier)
-        secondary_identifiers: FieldMap = AliasUtil.to_data_field_names_dict(secondary_identifiers)
-        unique_record: WrappedType | None = self.__find_model(wrapper_type, primary_identifier, id_value,
-                                                              secondary_identifiers)
-        # If a unique record matched the identifiers, return it.
-        if unique_record is not None:
-            return unique_record
+        :param records: The list of records.
+        :return: The input record with the highest record ID. None if the input list is empty.
+        """
+        return max(records, key=lambda x: x.record_id)
 
-        # If none of the results matched the identifiers, create a new record with all identifiers set.
-        # Put the primary identifier and value into the secondary identifiers list and use that as the fields map
-        # for this new record.
-        secondary_identifiers.update({primary_identifier: id_value})
-        return self.create_models_with_data(wrapper_type, [secondary_identifiers])[0]
+    # FR-46696: Add a function for getting the oldest record in a list, just like we have one for the newest record.
+    @staticmethod
+    def get_oldest_record(records: Iterable[SapioRecord]) -> SapioRecord:
+        """
+        Get the oldest record from a list of records.
 
-    # FR-47525: Add functions for getting and setting record image bytes.
-    def get_record_image(self, record: SapioRecord) -> bytes:
+        :param records: The list of records.
+        :return: The input record with the lowest record ID. None if the input list is empty.
         """
-        Retrieve the record image for a given record.
+        return min(records, key=lambda x: x.record_id)
 
-        :param record: The record model to retrieve the image of.
-        :return: The file bytes of the given record's image.
+    @staticmethod
+    def get_min_record(records: list[RecordModel], field: FieldIdentifier) -> RecordModel:
         """
-        record: DataRecord = AliasUtil.to_data_record(record)
-        with io.BytesIO() as data_sink:
-            def consume_data(chunk: bytes):
-                data_sink.write(chunk)
+        Get the record model with the minimum value of a given field from a list of record models.
 
-            self.dr_man.get_record_image(record, consume_data)
-            data_sink.flush()
-            data_sink.seek(0)
-            file_bytes = data_sink.read()
-        return file_bytes
+        :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))
 
-    def set_record_image(self, record: SapioRecord, file_data: str | bytes) -> None:
+    @staticmethod
+    def get_max_record(records: list[RecordModel], field: FieldIdentifier) -> RecordModel:
         """
-        Set the record image for a given record.
+        Get the record model with the maximum value of a given field from a list of record models.
 
-        :param record: The record model to set the image of.
-        :param file_data: The file data of the image to set on the record.
+        :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.
         """
-        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)
+        field: str = AliasUtil.to_data_field_name(field)
+        return max(records, key=lambda x: x.get_field_value(field))
 
     # FR-47522: Add RecordHandler functions that copy from the RecordModelUtil class in our Java utilities.
     @staticmethod
@@ -619,31 +746,34 @@ class RecordHandler:
             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:
+    def values_to_field_maps(field_name: FieldIdentifier, values: Iterable[FieldValue],
+                             existing_fields: list[FieldMap] | None = None) -> list[FieldMap]:
         """
-        Get the record model with the maximum value of a given field from a list of record models.
+        Add a list of values for a specific field to a list of dictionaries pairing each value to that field name.
 
-        :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.
+        :param field_name: The name of the field that the values are from.
+        :param values: A list of field values.
+        :param existing_fields: An optional existing fields map list to add the new values to. Values are added in the
+            list in the same order that they appear. If no existing fields are provided, returns a new fields map list.
+        :return: A fields map list that contains the given values mapped by the given field name.
         """
-        field: str = AliasUtil.to_data_field_name(field)
-        return max(records, key=lambda x: x.get_field_value(field))
+        # Update the existing fields map list if one is given.
+        field_name: str = AliasUtil.to_data_field_name(field_name)
+        existing_fields: list[FieldMap] = AliasUtil.to_data_field_names_list_dict(existing_fields)
+        if existing_fields:
+            values = list(values)
+            # The number of new values must match the length of the existing fields list.
+            if len(values) != len(existing_fields):
+                raise SapioException(f"Length of \"{field_name}\" values does not match the existing fields length.")
+            for field, value in zip(existing_fields, values):
+                field.update({field_name: value})
+            return existing_fields
+        # Otherwise, create a new fields map list.
+        return [{field_name: value} for value in values]
 
     @staticmethod
-    def get_from_all(records: Iterable[RecordModel], getter: _PropertyGetter[_PropertyType]) -> list[_PropertyType]:
+    def get_from_all(records: Iterable[RecordModel], getter: _PropertyGetter[_PropertyType]) \
+            -> list[RecordModelPropertyType]:
         """
         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
@@ -657,7 +787,8 @@ class RecordHandler:
         return [x.get(getter) for x in records]
 
     @staticmethod
-    def set_on_all(records: Iterable[RecordModel], setter: _PropertySetter[_PropertyType]) -> list[_PropertyType]:
+    def set_on_all(records: Iterable[RecordModel], setter: _PropertySetter[_PropertyType]) \
+            -> list[RecordModelPropertyType]:
         """
         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
@@ -671,7 +802,8 @@ class RecordHandler:
         return [x.set(setter) for x in records]
 
     @staticmethod
-    def add_to_all(records: Iterable[RecordModel], adder: _PropertyAdder[_PropertyType]) -> list[_PropertyType]:
+    def add_to_all(records: Iterable[RecordModel], adder: _PropertyAdder[_PropertyType]) \
+            -> list[RecordModelPropertyType]:
         """
         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.
@@ -684,7 +816,8 @@ class RecordHandler:
         return [x.add(adder) for x in records]
 
     @staticmethod
-    def remove_from_all(records: Iterable[RecordModel], remover: _PropertyRemover[_PropertyType]) -> list[_PropertyType]:
+    def remove_from_all(records: Iterable[RecordModel], remover: _PropertyRemover[_PropertyType]) \
+            -> list[RecordModelPropertyType]:
         """
         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.
@@ -989,76 +1122,56 @@ class RecordHandler:
         return return_dict
 
     @staticmethod
-    def map_by_forward_side_links(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
-                                  side_link_type: type[WrappedType]) -> dict[WrappedType, list[WrappedRecordModel]]:
+    def map_by_forward_side_link(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
+                                 side_link_type: type[WrappedType]) -> dict[WrappedType, WrappedRecordModel]:
         """
         Take a list of record models and map them by their forward side link. Essentially an inversion of
-        map_to_forward_side_link. Input models that share a forward side link will end up in the same list.
+        map_to_forward_side_link, but if two records share the same forward link, an exception is thrown.
         The forward side link must already be loaded.
 
         :param models: A list of record models.
         :param field_name: The field name on the record models where the side link is located.
         :param side_link_type: The record model wrapper of the forward side links.
-        :return: A dict[SideLink, list[ModelType]]. If an input model doesn't have a forward side link of the given type
+        :return: A dict[SideLink, ModelType]. If an input model doesn't have a forward side link of the given type
             pointing to it, then it will not be in the resulting dictionary.
         """
         field_name: str = AliasUtil.to_data_field_name(field_name)
         to_side_link: dict[WrappedRecordModel, WrappedType] = RecordHandler\
             .map_to_forward_side_link(models, field_name, side_link_type)
-        by_side_link: dict[WrappedType, list[WrappedRecordModel]] = {}
+        by_side_link: dict[WrappedType, WrappedRecordModel] = {}
         for record, side_link in to_side_link.items():
             if side_link is None:
                 continue
-            by_side_link.setdefault(side_link, []).append(record)
+            if side_link in by_side_link:
+                raise SapioException(f"Side link {side_link.data_type_name} {side_link.record_id} encountered more "
+                                     f"than once in models list.")
+            by_side_link[side_link] = record
         return by_side_link
 
     @staticmethod
-    def map_by_forward_side_link(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
-                                 side_link_type: type[WrappedType]) -> dict[WrappedType, WrappedRecordModel]:
+    def map_by_forward_side_links(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
+                                  side_link_type: type[WrappedType]) -> dict[WrappedType, list[WrappedRecordModel]]:
         """
         Take a list of record models and map them by their forward side link. Essentially an inversion of
-        map_to_forward_side_link, but if two records share the same forward link, an exception is thrown.
+        map_to_forward_side_link. Input models that share a forward side link will end up in the same list.
         The forward side link must already be loaded.
 
         :param models: A list of record models.
         :param field_name: The field name on the record models where the side link is located.
         :param side_link_type: The record model wrapper of the forward side links.
-        :return: A dict[SideLink, ModelType]. If an input model doesn't have a forward side link of the given type
+        :return: A dict[SideLink, list[ModelType]]. If an input model doesn't have a forward side link of the given type
             pointing to it, then it will not be in the resulting dictionary.
         """
         field_name: str = AliasUtil.to_data_field_name(field_name)
         to_side_link: dict[WrappedRecordModel, WrappedType] = RecordHandler\
             .map_to_forward_side_link(models, field_name, side_link_type)
-        by_side_link: dict[WrappedType, WrappedRecordModel] = {}
+        by_side_link: dict[WrappedType, list[WrappedRecordModel]] = {}
         for record, side_link in to_side_link.items():
             if side_link is None:
                 continue
-            if side_link in by_side_link:
-                raise SapioException(f"Side link {side_link.data_type_name} {side_link.record_id} encountered more "
-                                     f"than once in models list.")
-            by_side_link[side_link] = record
+            by_side_link.setdefault(side_link, []).append(record)
         return by_side_link
 
-    @staticmethod
-    def map_to_reverse_side_links(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
-                                  side_link_type: type[WrappedType]) -> dict[WrappedRecordModel, list[WrappedType]]:
-        """
-        Map a list of record models to a list reverse side links of a given type. The reverse side links must already
-        be loaded.
-
-        :param models: A list of record models.
-        :param field_name: The field name on the side linked model where the side link to the given record models is
-            located.
-        :param side_link_type: The record model wrapper of the reverse side links.
-        :return: A dict[ModelType, list[SideLink]]. If an input model doesn't have reverse side links of the given type,
-            then it will map to an empty list.
-        """
-        field_name: str = AliasUtil.to_data_field_name(field_name)
-        return_dict: dict[WrappedRecordModel, list[WrappedType]] = {}
-        for model in models:
-            return_dict[model] = model.get_reverse_side_link(field_name, side_link_type)
-        return return_dict
-
     @staticmethod
     def map_to_reverse_side_link(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
                                  side_link_type: type[WrappedType]) -> dict[WrappedRecordModel, WrappedType]:
@@ -1084,28 +1197,24 @@ class RecordHandler:
         return return_dict
 
     @staticmethod
-    def map_by_reverse_side_links(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
-                                  side_link_type: type[WrappedType]) -> dict[WrappedType, list[WrappedRecordModel]]:
+    def map_to_reverse_side_links(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
+                                  side_link_type: type[WrappedType]) -> dict[WrappedRecordModel, list[WrappedType]]:
         """
-        Take a list of record models and map them by their reverse side links. Essentially an inversion of
-        map_to_reverse_side_links. Input models that share a reverse side link will end up in the same list.
-        The reverse side links must already be loaded.
+        Map a list of record models to a list reverse side links of a given type. The reverse side links must already
+        be loaded.
 
         :param models: A list of record models.
         :param field_name: The field name on the side linked model where the side link to the given record models is
             located.
         :param side_link_type: The record model wrapper of the reverse side links.
-        :return: A dict[SideLink, list[ModelType]]. If an input model doesn't have reverse side links of the given type
-            pointing to it, then it will not be in the resulting dictionary.
+        :return: A dict[ModelType, list[SideLink]]. If an input model doesn't have reverse side links of the given type,
+            then it will map to an empty list.
         """
         field_name: str = AliasUtil.to_data_field_name(field_name)
-        to_side_links: dict[WrappedRecordModel, list[WrappedType]] = RecordHandler\
-            .map_to_reverse_side_links(models, field_name, side_link_type)
-        by_side_links: dict[WrappedType, list[WrappedRecordModel]] = {}
-        for record, side_links in to_side_links.items():
-            for side_link in side_links:
-                by_side_links.setdefault(side_link, []).append(record)
-        return by_side_links
+        return_dict: dict[WrappedRecordModel, list[WrappedType]] = {}
+        for model in models:
+            return_dict[model] = model.get_reverse_side_link(field_name, side_link_type)
+        return return_dict
 
     @staticmethod
     def map_by_reverse_side_link(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
@@ -1136,130 +1245,28 @@ class RecordHandler:
         return by_side_link
 
     @staticmethod
-    def map_by_id(models: Iterable[SapioRecord]) -> dict[int, SapioRecord]:
-        """
-        Map the given records their record IDs.
-
-        :param models: The records to map.
-        :return: A dict mapping the record ID to each record.
-        """
-        ret_dict: dict[int, SapioRecord] = {}
-        for model in models:
-            ret_dict.update({model.record_id: model})
-        return ret_dict
-
-    @staticmethod
-    def map_by_field(models: Iterable[SapioRecord], field_name: FieldIdentifier) \
-            -> dict[FieldValue, list[SapioRecord]]:
-        """
-        Map the given records by one of their fields. If any two records share the same field value, they'll appear in
-        the same value list.
-
-        :param models: The records to map.
-        :param field_name: The field name to map against.
-        :return: A dict mapping field values to the records with that value.
-        """
-        field_name: str = AliasUtil.to_data_field_name(field_name)
-        ret_dict: dict[FieldValue, list[SapioRecord]] = {}
-        for model in models:
-            val: FieldValue = model.get_field_value(field_name)
-            ret_dict.setdefault(val, []).append(model)
-        return ret_dict
-
-    @staticmethod
-    def map_by_unique_field(models: Iterable[SapioRecord], field_name: FieldIdentifier) \
-            -> dict[FieldValue, SapioRecord]:
-        """
-        Uniquely map the given records by one of their fields. If any two records share the same field value, throws
-        an exception.
-
-        :param models: The records to map.
-        :param field_name: The field name to map against.
-        :return: A dict mapping field values to the record with that value.
-        """
-        field_name: str = AliasUtil.to_data_field_name(field_name)
-        ret_dict: dict[FieldValue, SapioRecord] = {}
-        for model in models:
-            val: FieldValue = model.get_field_value(field_name)
-            if val in ret_dict:
-                raise SapioException(f"Value {val} encountered more than once in models list.")
-            ret_dict.update({val: model})
-        return ret_dict
-
-    @staticmethod
-    def sum_of_field(models: Iterable[SapioRecord], field_name: FieldIdentifier) -> float:
-        """
-        Sum up 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.
-
-        :param models: The models to calculate the sum of.
-        :param field_name: The name of the numeric field to sum.
-        :return: The sum of the field values for the collection of models.
-        """
-        field_name: str = AliasUtil.to_data_field_name(field_name)
-        field_sum: float = 0
-        for model in models:
-            field_sum += float(model.get_field_value(field_name))
-        return field_sum
-
-    @staticmethod
-    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.
-
-        :param models: The models to calculate the mean of.
-        :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(models)
-
-    @staticmethod
-    def get_newest_record(records: Iterable[SapioRecord]) -> SapioRecord:
-        """
-        Get the newest record from a list of records.
-
-        :param records: The list of records.
-        :return: The input record with the highest record ID. None if the input list is empty.
-        """
-        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
-    def get_oldest_record(records: Iterable[SapioRecord]) -> SapioRecord:
-        """
-        Get the oldest record from a list of records.
-
-        :param records: The list of records.
-        :return: The input record with the lowest record ID. None if the input list is empty.
-        """
-        return min(records, key=lambda x: x.record_id)
-
-    @staticmethod
-    def values_to_field_maps(field_name: FieldIdentifier, values: Iterable[FieldValue],
-                             existing_fields: list[FieldMap] | None = None) -> list[FieldMap]:
+    def map_by_reverse_side_links(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
+                                  side_link_type: type[WrappedType]) -> dict[WrappedType, list[WrappedRecordModel]]:
         """
-        Add a list of values for a specific field to a list of dictionaries pairing each value to that field name.
+        Take a list of record models and map them by their reverse side links. Essentially an inversion of
+        map_to_reverse_side_links. Input models that share a reverse side link will end up in the same list.
+        The reverse side links must already be loaded.
 
-        :param field_name: The name of the field that the values are from.
-        :param values: A list of field values.
-        :param existing_fields: An optional existing fields map list to add the new values to. Values are added in the
-            list in the same order that they appear. If no existing fields are provided, returns a new fields map list.
-        :return: A fields map list that contains the given values mapped by the given field name.
+        :param models: A list of record models.
+        :param field_name: The field name on the side linked model where the side link to the given record models is
+            located.
+        :param side_link_type: The record model wrapper of the reverse side links.
+        :return: A dict[SideLink, list[ModelType]]. If an input model doesn't have reverse side links of the given type
+            pointing to it, then it will not be in the resulting dictionary.
         """
-        # Update the existing fields map list if one is given.
         field_name: str = AliasUtil.to_data_field_name(field_name)
-        existing_fields: list[FieldMap] = AliasUtil.to_data_field_names_list_dict(existing_fields)
-        if existing_fields:
-            values = list(values)
-            # The number of new values must match the length of the existing fields list.
-            if len(values) != len(existing_fields):
-                raise SapioException(f"Length of \"{field_name}\" values does not match the existing fields length.")
-            for field, value in zip(existing_fields, values):
-                field.update({field_name: value})
-            return existing_fields
-        # Otherwise, create a new fields map list.
-        return [{field_name: value} for value in values]
+        to_side_links: dict[WrappedRecordModel, list[WrappedType]] = RecordHandler\
+            .map_to_reverse_side_links(models, field_name, side_link_type)
+        by_side_links: dict[WrappedType, list[WrappedRecordModel]] = {}
+        for record, side_links in to_side_links.items():
+            for side_link in side_links:
+                by_side_links.setdefault(side_link, []).append(record)
+        return by_side_links
 
     # FR-46155: Update relationship path traversing functions to be non-static and take in a wrapper type so that the
     # output can be wrapped instead of requiring the user to wrap the output.
@@ -1362,7 +1369,9 @@ class RecordHandler:
                     elif direction == RelationshipNodeType.DESCENDANT:
                         next_search.update(self.an_man.get_descendant_of_type(search, data_type))
                     elif direction == RelationshipNodeType.FORWARD_SIDE_LINK:
-                        next_search.add(search.get_forward_side_link(node.data_field_name))
+                        side_link: RecordModel | None = search.get_forward_side_link(node.data_field_name)
+                        if side_link:
+                            next_search.add(side_link)
                     elif direction == RelationshipNodeType.REVERSE_SIDE_LINK:
                         next_search.update(search.get_reverse_side_link(data_type, node.data_field_name))
                     else:
@@ -1412,7 +1421,8 @@ class RecordHandler:
                 elif direction == RelationshipNodeType.DESCENDANT:
                     current = list(self.an_man.get_descendant_of_type(current[0], data_type))
                 elif direction == RelationshipNodeType.FORWARD_SIDE_LINK:
-                    current = [current[0].get_forward_side_link(node.data_field_name)]
+                    side_link: RecordModel | None = current[0].get_forward_side_link(node.data_field_name)
+                    current = [side_link] if side_link else []
                 elif direction == RelationshipNodeType.REVERSE_SIDE_LINK:
                     current = current[0].get_reverse_side_link(data_type, node.data_field_name)
                 else: