sapiopycommons 2025.7.8a581__py3-none-any.whl → 2025.7.9a583__py3-none-any.whl

sapiopycommons/callbacks/callback_util.py

@@ -780,7 +780,7 @@ class CallbackUtil:
         # FR-47690: Set default values for fields that aren't present.
         for row in values:
             for field in fields:
-                if field.data_field_name not in values:
+                if field.data_field_name not in row:
                     row[field.data_field_name] = field.default_value
 
         # Convert the group_by parameter to a field name.

sapiopycommons/chem/IndigoMolecules.py

@@ -6,8 +6,6 @@ indigo = Indigo()
 renderer = IndigoRenderer(indigo)
 indigo.setOption("render-output-format", "svg")
 indigo.setOption("ignore-stereochemistry-errors", True)
-# Ignore only if loading as non-query object. That is the meaning of this flag. Does nothing if it's query molecule.
-indigo.setOption("ignore-noncritical-query-features", True)
 indigo.setOption("render-stereo-style", "ext")
 indigo.setOption("aromaticity-model", "generic")
 indigo.setOption("render-coloring", True)

sapiopycommons/recordmodel/record_handler.py

@@ -3,9 +3,13 @@ from __future__ import annotations
 import io
 import warnings
 from collections.abc import Iterable
-from typing import Collection
+from typing import Collection, TypeVar, TypeAlias
 from weakref import WeakValueDictionary
 
+from sapiopycommons.general.aliases import RecordModel, SapioRecord, FieldMap, FieldIdentifier, AliasUtil, \
+    FieldIdentifierMap, FieldValue, UserIdentifier, FieldIdentifierKey, DataTypeIdentifier
+from sapiopycommons.general.custom_report_util import CustomReportUtil
+from sapiopycommons.general.exceptions import SapioException
 from sapiopylib.rest.DataRecordManagerService import DataRecordManager
 from sapiopylib.rest.User import SapioUser
 from sapiopylib.rest.pojo.CustomReport import CustomReportCriteria, RawReportTerm, ReportColumn
@@ -24,19 +28,23 @@ from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedType, Wr
 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, DataTypeIdentifier
-from sapiopycommons.general.custom_report_util import CustomReportUtil
-from sapiopycommons.general.exceptions import SapioException
+from sapiopylib.rest.utils.recordmodel.properties import Parents, Parent, Children, Child, ForwardSideLink, \
+    ReverseSideLink
 
 # Aliases for longer name.
-_PropertyGetter = AbstractRecordModelPropertyGetter
-_PropertyAdder = AbstractRecordModelPropertyAdder
-_PropertyRemover = AbstractRecordModelPropertyRemover
-_PropertySetter = AbstractRecordModelPropertySetter
-_PropertyType = RecordModelPropertyType
+_PropertyGetter: TypeAlias = AbstractRecordModelPropertyGetter
+_PropertyAdder: TypeAlias = AbstractRecordModelPropertyAdder
+_PropertyRemover: TypeAlias = AbstractRecordModelPropertyRemover
+_PropertySetter: TypeAlias = AbstractRecordModelPropertySetter
+_PropertyType: TypeAlias = RecordModelPropertyType
+
+# CR-47717: Use TypeVars in the type hints of certain functions to prevent PyCharm from erroneously flagging certain
+# return type hints as incorrect.
+IsRecordModel = TypeVar('IsRecordModel', bound=RecordModel)
+"""A PyRecordModel or AbstractRecordModel."""
+IsSapioRecord = TypeVar('IsSapioRecord', bound=SapioRecord)
+"""A DataRecord, PyRecordModel, or AbstractRecordModel."""
+
 
 # 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.
@@ -524,9 +532,11 @@ class RecordHandler:
         """
         warnings.warn("Deprecated in favor of the [System/Custom/Quick]ReportRecordAutoPager classes.", DeprecationWarning)
         if isinstance(report_name, str):
+            # noinspection PyDeprecation
             results: list[dict[str, FieldValue]] = CustomReportUtil.run_system_report(self.user, report_name, filters,
                                                                                       page_limit, page_size, page_number)
         elif isinstance(report_name, RawReportTerm):
+            # noinspection PyDeprecation
             results: list[dict[str, FieldValue]] = CustomReportUtil.run_quick_report(self.user, report_name, filters,
                                                                                      page_limit, page_size, page_number)
         elif isinstance(report_name, CustomReportCriteria):
@@ -539,6 +549,7 @@ class RecordHandler:
             # 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_name.column_list]):
                 report_name.column_list.append(ReportColumn(dt, "RecordId", FieldType.LONG))
+            # noinspection PyDeprecation
             results: list[dict[str, FieldValue]] = CustomReportUtil.run_custom_report(self.user, report_name, filters,
                                                                                       page_limit, page_size, page_number)
         else:
@@ -551,7 +562,7 @@ class RecordHandler:
         return self.query_models_by_id(wrapper_type, ids)
 
     @staticmethod
-    def map_by_id(models: Iterable[SapioRecord]) -> dict[int, SapioRecord]:
+    def map_by_id(models: Iterable[IsSapioRecord]) -> dict[int, IsSapioRecord]:
         """
         Map the given records their record IDs.
 
@@ -560,12 +571,12 @@ class RecordHandler:
         """
         ret_dict: dict[int, SapioRecord] = {}
         for model in models:
-            ret_dict.update({model.record_id: model})
+            ret_dict.update({AliasUtil.to_record_id(model): model})
         return ret_dict
 
     @staticmethod
-    def map_by_field(models: Iterable[SapioRecord], field_name: FieldIdentifier) \
-            -> dict[FieldValue, list[SapioRecord]]:
+    def map_by_field(models: Iterable[IsSapioRecord], field_name: FieldIdentifier) \
+            -> dict[FieldValue, list[IsSapioRecord]]:
         """
         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.
@@ -582,8 +593,8 @@ class RecordHandler:
         return ret_dict
 
     @staticmethod
-    def map_by_unique_field(models: Iterable[SapioRecord], field_name: FieldIdentifier) \
-            -> dict[FieldValue, SapioRecord]:
+    def map_by_unique_field(models: Iterable[IsSapioRecord], field_name: FieldIdentifier) \
+            -> dict[FieldValue, IsSapioRecord]:
         """
         Uniquely map the given records by one of their fields. If any two records share the same field value, throws
         an exception.
@@ -662,7 +673,7 @@ class RecordHandler:
         return RecordHandler.sum_of_field(models, field_name) / len(models)
 
     @staticmethod
-    def get_newest_record(records: Iterable[SapioRecord]) -> SapioRecord:
+    def get_newest_record(records: Iterable[IsSapioRecord]) -> IsSapioRecord:
         """
         Get the newest record from a list of records.
 
@@ -673,7 +684,7 @@ class RecordHandler:
 
     # 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:
+    def get_oldest_record(records: Iterable[IsSapioRecord]) -> IsSapioRecord:
         """
         Get the oldest record from a list of records.
 
@@ -683,7 +694,7 @@ class RecordHandler:
         return min(records, key=lambda x: x.record_id)
 
     @staticmethod
-    def get_min_record(records: list[RecordModel], field: FieldIdentifier) -> RecordModel:
+    def get_min_record(records: list[IsSapioRecord], field: FieldIdentifier) -> IsSapioRecord:
         """
         Get the record model with the minimum value of a given field from a list of record models.
 
@@ -695,7 +706,7 @@ class RecordHandler:
         return min(records, key=lambda x: x.get_field_value(field))
 
     @staticmethod
-    def get_max_record(records: list[RecordModel], field: FieldIdentifier) -> RecordModel:
+    def get_max_record(records: list[IsSapioRecord], field: FieldIdentifier) -> IsSapioRecord:
         """
         Get the record model with the maximum value of a given field from a list of record models.
 
@@ -870,7 +881,7 @@ class RecordHandler:
         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)
+        parent: PyRecordModel | None = record.get(Parent.of_type_name(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))
@@ -888,7 +899,7 @@ class RecordHandler:
         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)
+        child: PyRecordModel | None = record.get(Child.of_type_name(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))
@@ -908,7 +919,7 @@ class RecordHandler:
         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)
+        side_link: PyRecordModel | None = record.get(ForwardSideLink.of(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)
@@ -955,52 +966,63 @@ class RecordHandler:
             if child not in children:
                 record.remove(Child.ref(child))
 
+    # CR-47717: Update the map_[to/by]_[relationship] functions to allow PyRecordModels to be provided and returned
+    # instead of only using WrappedRecordModels and wrapper types.
     @staticmethod
-    def map_to_parent(models: Iterable[WrappedRecordModel], parent_type: type[WrappedType])\
-            -> dict[WrappedRecordModel, WrappedType]:
+    def map_to_parent(models: Iterable[IsRecordModel], parent_type: type[WrappedType] | str) \
+            -> dict[IsRecordModel, WrappedType | PyRecordModel]:
         """
         Map a list of record models to a single parent of a given type. The parents must already be loaded.
 
         :param models: A list of record models.
-        :param parent_type: The record model wrapper of the parent.
+        :param parent_type: The record model wrapper or data type name of the parents. If a data type name is
+            provided, the returned records will be PyRecordModels instead of WrappedRecordModels.
         :return: A dict[ModelType, ParentType]. If an input model doesn't have a parent of the given parent type, then
             it will map to None.
         """
-        return_dict: dict[WrappedRecordModel, WrappedType] = {}
+        return_dict: dict[RecordModel, WrappedType | PyRecordModel] = {}
         for model in models:
-            return_dict[model] = model.get_parent_of_type(parent_type)
+            if isinstance(parent_type, str):
+                return_dict[model] = model.get(Parent.of_type_name(parent_type))
+            else:
+                return_dict[model] = model.get(Parent.of_type(parent_type))
         return return_dict
 
     @staticmethod
-    def map_to_parents(models: Iterable[WrappedRecordModel], parent_type: type[WrappedType]) \
-            -> dict[WrappedRecordModel, list[WrappedType]]:
+    def map_to_parents(models: Iterable[IsRecordModel], parent_type: type[WrappedType] | str) \
+            -> dict[IsRecordModel, list[WrappedType] | list[PyRecordModel]]:
         """
         Map a list of record models to a list parents of a given type. The parents must already be loaded.
 
         :param models: A list of record models.
-        :param parent_type: The record model wrapper of the parents.
+        :param parent_type: The record model wrapper or data type name of the parents. If a data type name is
+            provided, the returned records will be PyRecordModels instead of WrappedRecordModels.
         :return: A dict[ModelType, list[ParentType]]. If an input model doesn't have a parent of the given parent type,
             then it will map to an empty list.
         """
-        return_dict: dict[WrappedRecordModel, list[WrappedType]] = {}
+        return_dict: dict[WrappedRecordModel, list[WrappedType] | list[PyRecordModel]] = {}
         for model in models:
-            return_dict[model] = model.get_parents_of_type(parent_type)
+            if isinstance(parent_type, str):
+                return_dict[model] = model.get(Parents.of_type_name(parent_type))
+            else:
+                return_dict[model] = model.get(Parents.of_type(parent_type))
         return return_dict
 
     @staticmethod
-    def map_by_parent(models: Iterable[WrappedRecordModel], parent_type: type[WrappedType]) \
-            -> dict[WrappedType, WrappedRecordModel]:
+    def map_by_parent(models: Iterable[IsRecordModel], parent_type: type[WrappedType] | str) \
+            -> dict[WrappedType | PyRecordModel, IsRecordModel]:
         """
         Take a list of record models and map them by their parent. Essentially an inversion of map_to_parent.
         If two records share the same parent, an exception will be thrown. The parents must already be loaded.
 
         :param models: A list of record models.
-        :param parent_type: The record model wrapper of the parents.
+        :param parent_type: The record model wrapper or data type name of the parents. If a data type name is
+            provided, the returned records will be PyRecordModels instead of WrappedRecordModels.
         :return: A dict[ParentType, ModelType]. If an input model doesn't have a parent of the given parent type,
             then it will not be in the resulting dictionary.
         """
-        to_parent: dict[WrappedRecordModel, WrappedType] = RecordHandler.map_to_parent(models, parent_type)
-        by_parent: dict[WrappedType, WrappedRecordModel] = {}
+        to_parent: dict[RecordModel, WrappedType | PyRecordModel] = RecordHandler.map_to_parent(models, parent_type)
+        by_parent: dict[WrappedType | PyRecordModel, RecordModel] = {}
         for record, parent in to_parent.items():
             if parent is None:
                 continue
@@ -1011,70 +1033,81 @@ class RecordHandler:
         return by_parent
 
     @staticmethod
-    def map_by_parents(models: Iterable[WrappedRecordModel], parent_type: type[WrappedType]) \
-            -> dict[WrappedType, list[WrappedRecordModel]]:
+    def map_by_parents(models: Iterable[IsRecordModel], parent_type: type[WrappedType] | str) \
+            -> dict[WrappedType | PyRecordModel, list[IsRecordModel]]:
         """
         Take a list of record models and map them by their parents. Essentially an inversion of map_to_parents. Input
         models that share a parent will end up in the same list. The parents must already be loaded.
 
         :param models: A list of record models.
-        :param parent_type: The record model wrapper of the parents.
+        :param parent_type: The record model wrapper or data type name of the parents. If a data type name is
+            provided, the returned records will be PyRecordModels instead of WrappedRecordModels.
         :return: A dict[ParentType, list[ModelType]]. If an input model doesn't have a parent of the given parent type,
             then it will not be in the resulting dictionary.
         """
-        to_parents: dict[WrappedRecordModel, list[WrappedType]] = RecordHandler.map_to_parents(models, parent_type)
-        by_parents: dict[WrappedType, list[WrappedRecordModel]] = {}
+        to_parents: dict[RecordModel, list[WrappedType] | list[PyRecordModel]] = RecordHandler\
+            .map_to_parents(models, parent_type)
+        by_parents: dict[WrappedType | PyRecordModel, list[RecordModel]] = {}
         for record, parents in to_parents.items():
             for parent in parents:
                 by_parents.setdefault(parent, []).append(record)
         return by_parents
 
     @staticmethod
-    def map_to_child(models: Iterable[WrappedRecordModel], child_type: type[WrappedType])\
-            -> dict[WrappedRecordModel, WrappedType]:
+    def map_to_child(models: Iterable[IsRecordModel], child_type: type[WrappedType] | str) \
+            -> dict[IsRecordModel, WrappedType | PyRecordModel]:
         """
         Map a list of record models to a single child of a given type. The children must already be loaded.
 
         :param models: A list of record models.
-        :param child_type: The record model wrapper of the child.
+        :param child_type: The record model wrapper or data type name of the children. If a data type name is
+            provided, the returned records will be PyRecordModels instead of WrappedRecordModels.
         :return: A dict[ModelType, ChildType]. If an input model doesn't have a child of the given child type, then
             it will map to None.
         """
-        return_dict: dict[WrappedRecordModel, WrappedType] = {}
+        return_dict: dict[RecordModel, WrappedType | PyRecordModel] = {}
         for model in models:
-            return_dict[model] = model.get_child_of_type(child_type)
+            if isinstance(child_type, str):
+                return_dict[model] = model.get(Child.of_type_name(child_type))
+            else:
+                return_dict[model] = model.get(Child.of_type(child_type))
         return return_dict
 
     @staticmethod
-    def map_to_children(models: Iterable[WrappedRecordModel], child_type: type[WrappedType]) \
-            -> dict[WrappedRecordModel, list[WrappedType]]:
+    def map_to_children(models: Iterable[IsRecordModel], child_type: type[WrappedType] | str) \
+            -> dict[IsRecordModel, list[WrappedType] | PyRecordModel]:
         """
         Map a list of record models to a list children of a given type. The children must already be loaded.
 
         :param models: A list of record models.
-        :param child_type: The record model wrapper of the children.
+        :param child_type: The record model wrapper or data type name of the children. If a data type name is
+            provided, the returned records will be PyRecordModels instead of WrappedRecordModels.
         :return: A dict[ModelType, list[ChildType]]. If an input model doesn't have children of the given child type,
             then it will map to an empty list.
         """
-        return_dict: dict[WrappedRecordModel, list[WrappedType]] = {}
+        return_dict: dict[RecordModel, list[WrappedType] | list[PyRecordModel]] = {}
         for model in models:
-            return_dict[model] = model.get_children_of_type(child_type)
+            if isinstance(child_type, str):
+                return_dict[model] = model.get(Children.of_type_name(child_type))
+            else:
+                return_dict[model] = model.get(Children.of_type(child_type))
         return return_dict
 
     @staticmethod
-    def map_by_child(models: Iterable[WrappedRecordModel], child_type: type[WrappedType]) \
-            -> dict[WrappedType, WrappedRecordModel]:
+    def map_by_child(models: Iterable[IsRecordModel], child_type: type[WrappedType] | str) \
+            -> dict[WrappedType | str, IsRecordModel]:
         """
         Take a list of record models and map them by their children. Essentially an inversion of map_to_child.
         If two records share the same child, an exception will be thrown. The children must already be loaded.
 
         :param models: A list of record models.
-        :param child_type: The record model wrapper of the children.
+        :param child_type: The record model wrapper or data type name of the children. If a data type name is
+            provided, the returned records will be PyRecordModels instead of WrappedRecordModels.
         :return: A dict[ChildType, ModelType]. If an input model doesn't have a child of the given child type,
             then it will not be in the resulting dictionary.
         """
-        to_child: dict[WrappedRecordModel, WrappedType] = RecordHandler.map_to_child(models, child_type)
-        by_child: dict[WrappedType, WrappedRecordModel] = {}
+        to_child: dict[RecordModel, WrappedType | PyRecordModel] = RecordHandler.map_to_child(models, child_type)
+        by_child: dict[WrappedType | PyRecordModel, RecordModel] = {}
         for record, child in to_child.items():
             if child is None:
                 continue
@@ -1085,45 +1118,50 @@ class RecordHandler:
         return by_child
 
     @staticmethod
-    def map_by_children(models: Iterable[WrappedRecordModel], child_type: type[WrappedType]) \
-            -> dict[WrappedType, list[WrappedRecordModel]]:
+    def map_by_children(models: Iterable[IsRecordModel], child_type: type[WrappedType] | str) \
+            -> dict[WrappedType | PyRecordModel, list[IsRecordModel]]:
         """
         Take a list of record models and map them by their children. Essentially an inversion of map_to_children. Input
         models that share a child will end up in the same list. The children must already be loaded.
 
         :param models: A list of record models.
-        :param child_type: The record model wrapper of the children.
+        :param child_type: The record model wrapper or data type name of the children. If a data type name is
+            provided, the returned records will be PyRecordModels instead of WrappedRecordModels.
         :return: A dict[ChildType, list[ModelType]]. If an input model doesn't have children of the given child type,
             then it will not be in the resulting dictionary.
         """
-        to_children: dict[WrappedRecordModel, list[WrappedType]] = RecordHandler.map_to_children(models, child_type)
-        by_children: dict[WrappedType, list[WrappedRecordModel]] = {}
+        to_children: dict[RecordModel, list[WrappedType] | list[PyRecordModel]] = RecordHandler\
+            .map_to_children(models, child_type)
+        by_children: dict[WrappedType | PyRecordModel, list[RecordModel]] = {}
         for record, children in to_children.items():
             for child in children:
                 by_children.setdefault(child, []).append(record)
         return by_children
 
     @staticmethod
-    def map_to_forward_side_link(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
-                                 side_link_type: type[WrappedType]) -> dict[WrappedRecordModel, WrappedType]:
+    def map_to_forward_side_link(models: Iterable[IsRecordModel], field_name: FieldIdentifier,
+                                 side_link_type: type[WrappedType] | None) \
+            -> dict[IsRecordModel, WrappedType | PyRecordModel]:
         """
         Map a list of record models to their forward side link. 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 link.
+        :param side_link_type: The record model wrapper of the forward side link. If None, the side links will
+            be returned as PyRecordModels instead of WrappedRecordModels.
         :return: A dict[ModelType, SlideLink]. If an input model doesn't have a forward side link of the given type,
             then it will map to None.
         """
         field_name: str = AliasUtil.to_data_field_name(field_name)
-        return_dict: dict[WrappedRecordModel, WrappedType] = {}
+        return_dict: dict[RecordModel, WrappedType | PyRecordModel] = {}
         for model in models:
-            return_dict[model] = model.get_forward_side_link(field_name, side_link_type)
+            return_dict[model] = model.get(ForwardSideLink.of(field_name, side_link_type))
         return return_dict
 
     @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_link(models: Iterable[IsRecordModel], field_name: FieldIdentifier,
+                                 side_link_type: type[WrappedType] | None) \
+            -> dict[WrappedType | PyRecordModel, IsRecordModel]:
         """
         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.
@@ -1131,14 +1169,15 @@ class RecordHandler:
 
         :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.
+        :param side_link_type: The record model wrapper of the forward side links. If None, the side links will
+            be returned as PyRecordModels instead of WrappedRecordModels.
         :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\
+        to_side_link: dict[RecordModel, WrappedType | PyRecordModel] = RecordHandler\
             .map_to_forward_side_link(models, field_name, side_link_type)
-        by_side_link: dict[WrappedType, WrappedRecordModel] = {}
+        by_side_link: dict[WrappedType | PyRecordModel, RecordModel] = {}
         for record, side_link in to_side_link.items():
             if side_link is None:
                 continue
@@ -1149,8 +1188,9 @@ class RecordHandler:
         return by_side_link
 
     @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_links(models: Iterable[IsRecordModel], field_name: FieldIdentifier,
+                                  side_link_type: type[WrappedType] | None) \
+            -> dict[WrappedType | PyRecordModel, list[IsRecordModel]]:
         """
         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.
@@ -1158,14 +1198,15 @@ class RecordHandler:
 
         :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.
+        :param side_link_type: The record model wrapper of the forward side links. If None, the side links will
+            be returned as PyRecordModels instead of WrappedRecordModels.
         :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\
+        to_side_link: dict[RecordModel, WrappedType | PyRecordModel] = RecordHandler\
             .map_to_forward_side_link(models, field_name, side_link_type)
-        by_side_link: dict[WrappedType, list[WrappedRecordModel]] = {}
+        by_side_link: dict[WrappedType | PyRecordModel, list[RecordModel]] = {}
         for record, side_link in to_side_link.items():
             if side_link is None:
                 continue
@@ -1173,8 +1214,9 @@ class RecordHandler:
         return by_side_link
 
     @staticmethod
-    def map_to_reverse_side_link(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
-                                 side_link_type: type[WrappedType]) -> dict[WrappedRecordModel, WrappedType]:
+    def map_to_reverse_side_link(models: Iterable[IsRecordModel], field_name: FieldIdentifier,
+                                 side_link_type: type[WrappedType] | str) \
+            -> dict[IsRecordModel, WrappedType | PyRecordModel]:
         """
         Map a list of record models to the reverse side link of a given type. If a given record has more than one
         reverse side link of this type, an exception is thrown. The reverse side links must already be loaded.
@@ -1182,14 +1224,18 @@ class RecordHandler:
         :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.
+        :param side_link_type: The record model wrapper or data type name of the reverse side links. If a data type
+            name is provided, the returned records will be PyRecordModels instead of WrappedRecordModels.
         :return: A dict[ModelType, SideLink]. If an input model doesn't have reverse side links of the given type,
             then it will map to None.
         """
         field_name: str = AliasUtil.to_data_field_name(field_name)
-        return_dict: dict[WrappedRecordModel, WrappedType] = {}
+        return_dict: dict[RecordModel, WrappedType | PyRecordModel] = {}
         for model in models:
-            links: list[WrappedType] = model.get_reverse_side_link(field_name, side_link_type)
+            if isinstance(side_link_type, str):
+                links: list[WrappedType] = model.get(ReverseSideLink.of(side_link_type, field_name))
+            else:
+                links: list[WrappedType] = model.get(ReverseSideLink.of_type(side_link_type, field_name))
             if len(links) > 1:
                 raise SapioException(f"Model {model.data_type_name} {model.record_id} has more than one reverse link "
                                      f"of type {side_link_type.get_wrapper_data_type_name()}.")
@@ -1197,8 +1243,9 @@ class RecordHandler:
         return return_dict
 
     @staticmethod
-    def map_to_reverse_side_links(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
-                                  side_link_type: type[WrappedType]) -> dict[WrappedRecordModel, list[WrappedType]]:
+    def map_to_reverse_side_links(models: Iterable[IsRecordModel], field_name: FieldIdentifier,
+                                  side_link_type: type[WrappedType] | str) \
+            -> dict[IsRecordModel, list[WrappedType] | list[PyRecordModel]]:
         """
         Map a list of record models to a list reverse side links of a given type. The reverse side links must already
         be loaded.
@@ -1206,19 +1253,24 @@ class RecordHandler:
         :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.
+        :param side_link_type: The record model wrapper or data type name of the reverse side links. If a data type
+            name is provided, the returned records will be PyRecordModels instead of WrappedRecordModels.
         :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]] = {}
+        return_dict: dict[RecordModel, list[WrappedType] | list[PyRecordModel]] = {}
         for model in models:
-            return_dict[model] = model.get_reverse_side_link(field_name, side_link_type)
+            if isinstance(side_link_type, str):
+                return_dict[model] = model.get(ReverseSideLink.of(side_link_type, field_name))
+            else:
+                return_dict[model] = model.get(ReverseSideLink.of_type(side_link_type, field_name))
         return return_dict
 
     @staticmethod
-    def map_by_reverse_side_link(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
-                                 side_link_type: type[WrappedType]) -> dict[WrappedType, WrappedRecordModel]:
+    def map_by_reverse_side_link(models: Iterable[IsRecordModel], field_name: FieldIdentifier,
+                                 side_link_type: type[WrappedType] | str) \
+            -> dict[WrappedType | PyRecordModel, IsRecordModel]:
         """
         Take a list of record models and map them by their reverse side link. Essentially an inversion of
         map_to_reverse_side_link. If two records share the same reverse side link, an exception is thrown.
@@ -1227,14 +1279,15 @@ class RecordHandler:
         :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.
+        :param side_link_type: The record model wrapper or data type name of the reverse side links. If a data type
+            name is provided, the returned records will be PyRecordModels instead of WrappedRecordModels.
         :return: A dict[SideLink, ModelType]. If an input model doesn't have a reverse 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\
+        to_side_link: dict[RecordModel, WrappedType | PyRecordModel] = RecordHandler\
             .map_to_reverse_side_link(models, field_name, side_link_type)
-        by_side_link: dict[WrappedType, WrappedRecordModel] = {}
+        by_side_link: dict[WrappedType | PyRecordModel, RecordModel] = {}
         for record, side_link in to_side_link.items():
             if side_link is None:
                 continue
@@ -1245,8 +1298,8 @@ class RecordHandler:
         return by_side_link
 
     @staticmethod
-    def map_by_reverse_side_links(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
-                                  side_link_type: type[WrappedType]) -> dict[WrappedType, list[WrappedRecordModel]]:
+    def map_by_reverse_side_links(models: Iterable[IsRecordModel], field_name: FieldIdentifier,
+                                  side_link_type: type[WrappedType] | str) -> dict[WrappedType | PyRecordModel, list[IsRecordModel]]:
         """
         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.
@@ -1255,7 +1308,8 @@ class RecordHandler:
         :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.
+        :param side_link_type: The record model wrapper or data type name of the reverse side links. If a data type
+            name is provided, the returned records will be PyRecordModels instead of WrappedRecordModels.
         :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.
         """
@@ -1270,9 +1324,9 @@ class RecordHandler:
 
     # 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.
-    def get_linear_path(self, models: Iterable[RecordModel], path: RelationshipPath,
+    def get_linear_path(self, models: Iterable[IsRecordModel], path: RelationshipPath,
                         wrapper_type: type[WrappedType] | None = None) \
-            -> dict[RecordModel, WrappedType | PyRecordModel | None]:
+            -> dict[IsRecordModel, WrappedType | PyRecordModel | None]:
         """
         Given a relationship path, travel the path starting from the input models. Returns the record at the end of the
         path, if any. The hierarchy must be linear (1:1 relationship between data types at every step) and the
@@ -1285,7 +1339,7 @@ class RecordHandler:
         :return: Each record model mapped to the record at the end of the path starting from itself. If the end of the
             path couldn't be reached, the record will map to None.
         """
-        ret_dict: dict[RecordModel, WrappedType | None] = {}
+        ret_dict: dict[RecordModel, WrappedType | PyRecordModel | None] = {}
         # PR-46832: Update path traversal to account for changes to RelationshipPath in Sapiopylib.
         path: list[RelationshipNode] = path.path
         for model in models:
@@ -1332,9 +1386,9 @@ class RecordHandler:
             ret_dict.update({model: self.wrap_model(current, wrapper_type) if current else None})
         return ret_dict
 
-    def get_branching_path(self, models: Iterable[RecordModel], path: RelationshipPath,
+    def get_branching_path(self, models: Iterable[IsRecordModel], path: RelationshipPath,
                            wrapper_type: type[WrappedType] | None = None)\
-            -> dict[RecordModel, list[WrappedType] | list[PyRecordModel]]:
+            -> dict[IsRecordModel, list[WrappedType] | list[PyRecordModel]]:
         """
         Given a relationship path, travel the path starting from the input models. Returns the record at the end of the
         path, if any. The hierarchy may be non-linear (1:Many relationships between data types are allowed) and the
@@ -1347,7 +1401,7 @@ class RecordHandler:
         :return: Each record model mapped to the records at the end of the path starting from itself. If the end of the
             path couldn't be reached, the record will map to an empty list.
         """
-        ret_dict: dict[RecordModel, list[WrappedType]] = {}
+        ret_dict: dict[RecordModel, list[WrappedType] | list[PyRecordModel]] = {}
         # PR-46832: Update path traversal to account for changes to RelationshipPath in Sapiopylib.
         path: list[RelationshipNode] = path.path
         for model in models:
@@ -1383,9 +1437,9 @@ class RecordHandler:
 
     # FR-46155: Create a relationship traversing function that returns a single function at the end of the path like
     # get_linear_path but can handle branching paths in the middle of the search like get_branching_path.
-    def get_flat_path(self, models: Iterable[RecordModel], path: RelationshipPath,
+    def get_flat_path(self, models: Iterable[IsRecordModel], path: RelationshipPath,
                       wrapper_type: type[WrappedType] | None = None) \
-            -> dict[RecordModel, WrappedType | PyRecordModel | None]:
+            -> dict[IsRecordModel, WrappedType | PyRecordModel | None]:
         """
         Given a relationship path, travel the path starting from the input models. Returns the record at the end of the
         path, if any. The hierarchy may be non-linear (1:Many relationships between data types are allowed) and the
@@ -1402,7 +1456,7 @@ class RecordHandler:
         :return: Each record model mapped to the record at the end of the path starting from itself. If the end of the
             path couldn't be reached, the record will map to None.
         """
-        ret_dict: dict[RecordModel, WrappedType | None] = {}
+        ret_dict: dict[RecordModel, WrappedType | PyRecordModel | None] = {}
         # PR-46832: Update path traversal to account for changes to RelationshipPath in Sapiopylib.
         path: list[RelationshipNode] = path.path
         for model in models:

sapiopycommons/webhook/webhook_handlers.py

@@ -7,7 +7,6 @@ import traceback
 from abc import abstractmethod
 from logging import Logger
 
-from sapiopylib.rest import UserManagerService, GroupManagerService, MessengerService
 from sapiopylib.rest.AccessionService import AccessionManager
 from sapiopylib.rest.CustomReportService import CustomReportManager
 from sapiopylib.rest.DashboardManager import DashboardManager
@@ -16,10 +15,13 @@ from sapiopylib.rest.DataRecordManagerService import DataRecordManager
 from sapiopylib.rest.DataService import DataManager
 from sapiopylib.rest.DataTypeService import DataTypeManager
 from sapiopylib.rest.ELNService import ElnManager
+from sapiopylib.rest.GroupManagerService import VeloxGroupManager
+from sapiopylib.rest.MessengerService import SapioMessenger
 from sapiopylib.rest.PicklistService import PickListManager
 from sapiopylib.rest.ReportManager import ReportManager
 from sapiopylib.rest.SesssionManagerService import SessionManager
 from sapiopylib.rest.User import SapioUser
+from sapiopylib.rest.UserManagerService import VeloxUserManager
 from sapiopylib.rest.WebhookService import AbstractWebhookHandler
 from sapiopylib.rest.pojo.Message import VeloxLogMessage, VeloxLogLevel
 from sapiopylib.rest.pojo.webhook.ClientCallbackRequest import PopupType
@@ -85,9 +87,9 @@ class CommonsWebhookHandler(AbstractWebhookHandler):
     """A class for making requests to the data type webservice endpoints."""
     eln_man: ElnManager
     """A class for making requests to the ELN management webservice endpoints."""
-    group_man: GroupManagerService
+    group_man: VeloxGroupManager
     """A class for making requests to the group management webservice endpoints."""
-    messenger: MessengerService
+    messenger: SapioMessenger
     """A class for making requests to the message webservice endpoints."""
     list_man: PickListManager
     """A class for making requests to the pick list webservice endpoints."""
@@ -95,7 +97,7 @@ class CommonsWebhookHandler(AbstractWebhookHandler):
     """A class for making requests to the report webservice endpoints."""
     session_man: SessionManager
     """A class for making requests to the session management webservice endpoints."""
-    user_man: UserManagerService
+    user_man: VeloxUserManager
     """A class for making requests to the user management webservice endpoints."""
 
     rec_man: RecordModelManager

{sapiopycommons-2025.7.8a581.dist-info → sapiopycommons-2025.7.9a583.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sapiopycommons
-Version: 2025.7.8a581
+Version: 2025.7.9a583
 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>

{sapiopycommons-2025.7.8a581.dist-info → sapiopycommons-2025.7.9a583.dist-info}/RECORD

@@ -1,11 +1,10 @@
 sapiopycommons/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sapiopycommons/callbacks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sapiopycommons/callbacks/callback_util.py,sha256=rps6RA6lmzCOwiBqPQAe2Mkf0CIF4RjHPQTYgduMAgE,153011
+sapiopycommons/callbacks/callback_util.py,sha256=OuPJ1o6jcDQ7qV-dxrjAkJerGbVI9_9P-xu0r3ODaMM,153008
 sapiopycommons/callbacks/field_builder.py,sha256=rnIP-RJafk3mZlAx1eJ8a0eSW9Ps_L6_WadCmusnENw,38772
-sapiopycommons/chem/IndigoMolecules.py,sha256=30bsnZ2o4fJXUV6kUTI-I6fDa7bQj7zfE3rOQQ7WD5M,5287
+sapiopycommons/chem/IndigoMolecules.py,sha256=7ucCaRMLu1zfH2uPIvXwRTSdpNcS03O1P9p_O-5B4xQ,5110
 sapiopycommons/chem/Molecules.py,sha256=mVqPn32MPMjF0iZas-5MFkS-upIdoW5OB72KKZmJRJA,12523
 sapiopycommons/chem/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sapiopycommons/chem/ps_commons.py,sha256=ngM6wAo_UMCkb--rtjLMyABysMopHmCc0C2LzYdDK7Y,19848
 sapiopycommons/customreport/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sapiopycommons/customreport/auto_pagers.py,sha256=89p-tik0MhsOplYje6LbAW4WClldpAmb8YXFDoXhIlY,17144
 sapiopycommons/customreport/column_builder.py,sha256=0RO53e9rKPZ07C--KcepN6_tpRw_FxF3O9vdG0ilKG8,3014
@@ -52,7 +51,7 @@ sapiopycommons/processtracking/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5
 sapiopycommons/processtracking/custom_workflow_handler.py,sha256=eYKdYlwo8xx-6AkB_iPUBNV9yDoNvW2h_Sm3i8JpmRU,25844
 sapiopycommons/processtracking/endpoints.py,sha256=5AJLbhRKQsOeeOdQa888xcCJZD5aavxD-DHZ36Qob_M,12548
 sapiopycommons/recordmodel/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sapiopycommons/recordmodel/record_handler.py,sha256=HfYOl_dDHFd0SEQS3g48_a4zsm36ODWkvZunwzCFDos,90666
+sapiopycommons/recordmodel/record_handler.py,sha256=WxmgrWQ3nX3eVZSHJY7e8fj7CI7azSyEyovmYcy9098,95021
 sapiopycommons/rules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sapiopycommons/rules/eln_rule_handler.py,sha256=MnE-eSl1kNfaXWFi9elTOC9V2fdUzrwWTvCHUprC8_I,11388
 sapiopycommons/rules/on_save_rule_handler.py,sha256=fkNIlslAZZ0BUrRiwecyvf42JBR8FpCCQ6DBNKXP2jE,11155
@@ -61,9 +60,9 @@ sapiopycommons/sftpconnect/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJ
 sapiopycommons/sftpconnect/sftp_builder.py,sha256=lFK3FeXk-sFLefW0hqY8WGUQDeYiGaT6yDACzT_zFgQ,3015
 sapiopycommons/webhook/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 sapiopycommons/webhook/webhook_context.py,sha256=D793uLsb1691SalaPnBUk3rOSxn_hYLhdvkaIxjNXss,1909
-sapiopycommons/webhook/webhook_handlers.py,sha256=tUVNCw05CDGu1gFDm2g558hX_O203WVm_n__ojjoRRM,39841
+sapiopycommons/webhook/webhook_handlers.py,sha256=7o_wXOruhT9auNh8OfhJAh4WhhiPKij67FMBSpGPICc,39939
 sapiopycommons/webhook/webservice_handlers.py,sha256=tyaYGG1-v_JJrJHZ6cy5mGCxX9z1foLw7pM4MDJlFxs,14297
-sapiopycommons-2025.7.8a581.dist-info/METADATA,sha256=pqCJd-E4Z9GWbcI1jTNMzzBbdz3VRIACPNNHIjN0utM,3142
-sapiopycommons-2025.7.8a581.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-sapiopycommons-2025.7.8a581.dist-info/licenses/LICENSE,sha256=HyVuytGSiAUQ6ErWBHTqt1iSGHhLmlC8fO7jTCuR8dU,16725
-sapiopycommons-2025.7.8a581.dist-info/RECORD,,
+sapiopycommons-2025.7.9a583.dist-info/METADATA,sha256=zOjGEYY42rhigetoYC87X-jQ8rLzPNqEuP3stxwqarM,3142
+sapiopycommons-2025.7.9a583.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+sapiopycommons-2025.7.9a583.dist-info/licenses/LICENSE,sha256=HyVuytGSiAUQ6ErWBHTqt1iSGHhLmlC8fO7jTCuR8dU,16725
+sapiopycommons-2025.7.9a583.dist-info/RECORD,,

sapiopycommons/chem/ps_commons.py

@@ -1,455 +0,0 @@
-"""
-Parallel Synthesis Commons
-Author: Yechen Qiao
-"""
-import json
-from dataclasses import dataclass
-from typing import Any
-
-from indigo import IndigoObject
-from sapiopycommons.chem.IndigoMolecules import indigo, get_aromatic_dearomatic_forms, renderer
-
-
-class SerializableQueryMolecule:
-    mol_block: str
-    smarts: str
-    render_svg: str
-
-    @staticmethod
-    def create(query_molecule: IndigoObject):
-        aromatic, dearomatic = get_aromatic_dearomatic_forms(query_molecule)
-        ret: SerializableQueryMolecule = SerializableQueryMolecule()
-        ret.mol_block = aromatic.molfile()
-        ret.smarts = aromatic.smarts()
-        ret.render_svg = renderer.renderToString(dearomatic)
-        return ret
-
-    def to_json(self) -> dict[str, Any]:
-        """
-        Save the SerializableQueryMolecule to a JSON string.
-        :return: A JSON string representation of the query molecule.
-        """
-        return {
-            "mol_block": self.mol_block,
-            "smarts": self.smarts,
-            "render_svg": self.render_svg
-        }
-
-
-class SerializableMoleculeMatch:
-    """
-    A serializable match that stores and loads a match that can be serialized to JSON.
-    """
-    _query_atom_to_atom: dict[int, int]
-    _query_bond_to_bond: dict[int, int]
-    _query_molecule_file: str
-    _matching_molecule_file: str
-    _query_molecule: IndigoObject
-    _matching_molecule: IndigoObject
-    _record_id: int  # Only when received from Sapio.
-
-    @property
-    def record_id(self) -> int:
-        """
-        Get the record ID of the match.
-        :return: The record ID.
-        """
-        return self._record_id
-
-    def __str__(self):
-        return json.dumps(self.to_json())
-
-    def __hash__(self):
-        return hash(self._query_molecule.smarts())
-
-    def __eq__(self, other):
-        if not isinstance(other, SerializableMoleculeMatch):
-            return False
-        if self._query_atom_to_atom == other._query_atom_to_atom and \
-                self._query_bond_to_bond == other._query_bond_to_bond and \
-                self._query_molecule_file == other._query_molecule_file and \
-                self._matching_molecule_file == other._matching_molecule_file and \
-                self._record_id == other._record_id:
-            return True
-        if self._query_molecule.smarts() != other._query_molecule.smarts():
-            return False
-        return are_symmetrical_subs(self, other)
-
-    def mapAtom(self, atom: IndigoObject) -> IndigoObject | None:
-        if not self._query_atom_to_atom or atom.index() not in self._query_atom_to_atom:
-            return None
-        index = self._query_atom_to_atom[atom.index()]
-        return self._matching_molecule.getAtom(index)
-
-    def mapBond(self, bond: IndigoObject) -> IndigoObject | None:
-        if not self._query_bond_to_bond or bond.index() not in self._query_bond_to_bond:
-            return None
-        index = self._query_bond_to_bond[bond.index()]
-        return self._matching_molecule.getBond(index)
-
-    def to_json(self) -> dict[str, Any]:
-        """
-        Save the SerializableMoleculeMatch to a JSON string.
-        :return: A JSON string representation of the match.
-        """
-        return {
-            "query_molecule_file": self._query_molecule_file,
-            "matching_molecule_file": self._matching_molecule_file,
-            "query_atom_to_atom": self._query_atom_to_atom,
-            "query_bond_to_bond": self._query_bond_to_bond,
-            "record_id": self._record_id
-        }
-
-    @staticmethod
-    def from_json(json_dct: dict[str, Any]) -> 'SerializableMoleculeMatch':
-        """
-        Load a SerializableMoleculeMatch from a JSON string.
-        :param json_dct: A JSON string representation of the match.
-        :return: A new SerializableMoleculeMatch instance.
-        """
-        smm = SerializableMoleculeMatch()
-        smm._query_atom_to_atom = {}
-        for key, value in json_dct.get("query_atom_to_atom", {}).items():
-            smm._query_atom_to_atom[int(key)] = int(value)
-        smm._query_bond_to_bond = {}
-        for key, value in json_dct.get("query_bond_to_bond", {}).items():
-            smm._query_bond_to_bond[int(key)] = int(value)
-        smm._query_molecule_file = json_dct.get("query_molecule_file")
-        smm._matching_molecule_file = json_dct.get("matching_molecule_file")
-        smm._query_molecule = indigo.loadQueryMolecule(smm._query_molecule_file)
-        smm._matching_molecule = indigo.loadMolecule(smm._matching_molecule_file)
-        smm._record_id = json_dct.get("record_id", 0)  # Default to 0 if not present
-        return smm
-
-    @staticmethod
-    def create(query_molecule: IndigoObject, matching_molecule: IndigoObject,
-               match: IndigoObject) -> 'SerializableMoleculeMatch':
-        """
-        Create a SerializableMoleculeMatch from a query molecule, matching molecule, and match.
-        :param query_molecule: The query molecule.
-        :param matching_molecule: The matching molecule.
-        :param match: The match object containing atom mappings.
-        :return: A new SerializableMoleculeMatch instance.
-        """
-        smm = SerializableMoleculeMatch()
-        smm._query_atom_to_atom = {}
-        smm._query_bond_to_bond = {}
-        smm._query_molecule = query_molecule.clone()
-        smm._matching_molecule = matching_molecule.clone()
-        smm._query_molecule_file = query_molecule.molfile()
-        smm._matching_molecule_file = matching_molecule.molfile()
-        smm._record_id = 0
-
-        for qatom in query_molecule.iterateAtoms():
-            concrete_atom = match.mapAtom(qatom)
-            if concrete_atom is None:
-                continue
-            smm._query_atom_to_atom[qatom.index()] = concrete_atom.index()
-
-        for qbond in query_molecule.iterateBonds():
-            concrete_bond = match.mapBond(qbond)
-            if concrete_bond is None:
-                continue
-            smm._query_bond_to_bond[qbond.index()] = concrete_bond.index()
-        return smm
-
-    def get_matched_molecule_copy(self):
-        return self._matching_molecule.clone()
-
-
-@dataclass
-class ReplacementReaction:
-    """
-    A replacement reaction stores reactio template with 1 reactant replaced by specific user match.
-    """
-    reaction: IndigoObject
-    reaction_reactant: IndigoObject
-    replacement_reactant: IndigoObject
-    replacement_query_reaction_match: SerializableMoleculeMatch
-
-
-# noinspection PyProtectedMember
-def highlight_mol_substructure_serial_match(molecule: IndigoObject, serializable_match: SerializableMoleculeMatch):
-    """
-    Highlight the substructure in the molecule based on the SerializableMoleculeMatch.
-    :param molecule: The molecule to highlight.
-    :param serializable_match: The SerializableMoleculeMatch containing atom mappings.
-    """
-    for qatom in serializable_match._query_molecule.iterateAtoms():
-        atom = serializable_match.mapAtom(qatom)
-        if atom is None:
-            continue
-        atom.highlight()
-
-        for nei in atom.iterateNeighbors():
-            if not nei.isPseudoatom() and not nei.isRSite() and nei.atomicNumber() == 1:
-                nei.highlight()
-                nei.bond().highlight()
-
-    for bond in serializable_match._query_molecule.iterateBonds():
-        bond = serializable_match.mapBond(bond)
-        if bond is None:
-            continue
-        bond.highlight()
-
-
-def clear_highlights(molecule: IndigoObject):
-    """
-    Clear all highlights in the molecule.
-    :param molecule: The molecule to clear highlights from.
-    """
-    for atom in molecule.iterateAtoms():
-        atom.unhighlight()
-    for bond in molecule.iterateBonds():
-        bond.unhighlight()
-
-
-def clear_reaction_highlights(reaction: IndigoObject):
-    """
-    Clear all highlights in the reaction.
-    :param reaction: The reaction to clear highlights from.
-    """
-    for reactant in reaction.iterateReactants():
-        clear_highlights(reactant)
-    for product in reaction.iterateProducts():
-        clear_highlights(product)
-
-
-def reserve_atom_mapping_number_of_search_result(q_reaction: IndigoObject, q_reactant: IndigoObject,
-                                                 new_reaction_reactant: IndigoObject, new_reaction: IndigoObject,
-                                                 sub_match: SerializableMoleculeMatch) -> None:
-    """
-    Set the atom mapping number on the query molecule based on the atom mapping number of the sub_match molecule, if it exists.
-    :param new_reaction: The new reaction where the new reaction's reactant is found. This will be the target reaciton to write AAM to.
-    :param new_reaction_reactant: The new reaction's reactant where the AAM will be written to.
-    :param q_reactant: The query reactant from the query reaction that is being matched.
-    :param q_reaction: The query reaction that contains the query reactant for the sub_match.
-    :param sub_match: The substructure search match obtained from indigo.substructureMatcher(mol).match(query).
-    """
-    for query_atom in q_reactant.iterateAtoms():
-        concrete_atom = sub_match.mapAtom(query_atom)
-        if concrete_atom is None:
-            continue
-        reaction_atom = q_reactant.getAtom(query_atom.index())
-        map_num = q_reaction.atomMappingNumber(reaction_atom)
-        if map_num:
-            concrete_atom = new_reaction_reactant.getAtom(concrete_atom.index())
-            new_reaction.setAtomMappingNumber(concrete_atom, map_num)
-
-
-def clean_product_aam(reaction: IndigoObject):
-    """
-    Remove atom mappings from product that are not present in the reactants.
-    """
-    existing_mapping_numbers = set()
-    for reactant in reaction.iterateReactants():
-        for atom in reactant.iterateAtoms():
-            map_num = reaction.atomMappingNumber(atom)
-            if map_num:
-                existing_mapping_numbers.add(map_num)
-
-    for product in reaction.iterateProducts():
-        for atom in product.iterateAtoms():
-            map_num = reaction.atomMappingNumber(atom)
-            if map_num and map_num not in existing_mapping_numbers:
-                reaction.setAtomMappingNumber(atom, 0)  # YQ: atom number 0 means no mapping number in Indigo
-
-
-def make_concrete_reaction(reactants: list[IndigoObject], products: list[IndigoObject], replacement: IndigoObject,
-                           replacement_index: int) -> tuple[IndigoObject, IndigoObject]:
-    """
-    Create a concrete reaction from the given reactants and products, replacing the specified reactant with the replacement molecule.
-    :param reactants: List of reactant molecules.
-    :param products: List of product molecules.
-    :param replacement: The molecule to replace in the reactants.
-    :param replacement_index: The index of the reactant to replace.
-    :return: A new IndigoObject representing the concrete reaction.
-    """
-    concrete_reaction = indigo.createQueryReaction()
-    for i, reactant in enumerate(reactants):
-        if i == replacement_index:
-            concrete_reaction.addReactant(indigo.loadQueryMolecule(replacement.molfile()))
-        else:
-            concrete_reaction.addReactant(reactant.clone())
-    for product in products:
-        concrete_reaction.addProduct(product.clone())
-    return concrete_reaction, concrete_reaction.getMolecule(replacement_index)
-
-
-def is_ambiguous_atom(atom: IndigoObject) -> bool:
-    """
-    Test whether the symbol is an adjacent matching wildcard.
-    """
-    if atom.isPseudoatom() or atom.isRSite():
-        return True
-    symbol = atom.symbol()
-    if symbol in {'A', 'Q', 'X', 'M', 'AH', 'QH', 'XH', 'MH', 'NOT', 'R', '*'}:
-        return True
-    return "[" in symbol and "]" in symbol
-
-
-def get_react_site_highlights(product, ignored_atom_indexes):
-    """
-    Get the highlights for the reaction site in the product, ignoring the atoms that are not part of the reaction site.
-    :param product: The product molecule.
-    :param ignored_atom_indexes: A set of atom indexes to ignore.
-    :return: An IndigoObject with highlighted atoms and bonds that are part of the reaction site.
-    """
-    highlight = product.clone()
-    for atom in highlight.iterateAtoms():
-        if atom.index() not in ignored_atom_indexes:
-            atom.highlight()
-            for nei in atom.iterateNeighbors():
-                if nei.index() not in ignored_atom_indexes:
-                    nei.highlight()
-                    nei.bond().highlight()
-    return highlight
-
-
-def get_used_reactants_for_match(
-        reaction: IndigoObject, q_reaction: IndigoObject, reaction_match: IndigoObject,
-        kept_replacement_reaction_list_list: list[list[ReplacementReaction]]) -> list[ReplacementReaction]:
-    """
-    Find the replacement reactions that correspond to the reactants in reaction that also matches the query reaction.
-    Return None if any of the reactants do not have a corresponding replacement reaction, even though reaction may have matches directly to the query reaction.
-    Otherwise, return a list of ReplacementReaction objects that correspond to the reactants in the reaction ordered by the reactants in the query reaction.
-    """
-    q_reactants = []
-    for q_reactant in q_reaction.iterateReactants():
-        q_reactants.append(q_reactant)
-    q_products = []
-    for q_product in q_reaction.iterateProducts():
-        q_products.append(q_product)
-    reactants = []
-    for enum_r in reaction.iterateReactants():
-        reactants.append(enum_r)
-    products = []
-    for enum_p in reaction.iterateProducts():
-        products.append(enum_p)
-    ret: list[ReplacementReaction] = []
-    for i, q_reactant in enumerate(q_reactants):
-        replacement_list = kept_replacement_reaction_list_list[i]
-        enum_r = reactants[i]
-        useful_enumr_atom_indexes = set()
-        for rr_atom in q_reactant.iterateAtoms():
-            enum_atom = reaction_match.mapAtom(rr_atom)
-            if enum_atom:
-                useful_enumr_atom_indexes.add(enum_atom.index())
-        found: ReplacementReaction | None = None
-        for rr in replacement_list:
-            if found:
-                break
-            exact_match = indigo.exactMatch(enum_r, rr.replacement_reactant)
-            if not exact_match:
-                # YQ Skip if this enumeration is not meant to be the same reactant as replacement we are iterating.
-                continue
-            # YQ these are atoms in replacement reactant that are actually used in the query reactant
-            useful_rr_atom_indexes = set(rr.replacement_query_reaction_match._query_atom_to_atom.values())
-            useful_rr_neighbor_indexes = set()
-            # YQ furthermore, an atom is also considered useful for purpose of matching, if it neighbors a useful index, and is an ambiguous atom in query.
-            q_reactant: IndigoObject
-            for q_atom in q_reactant.iterateAtoms():
-                if is_ambiguous_atom(q_atom):
-                    for q_neighbor in q_atom.iterateNeighbors():
-                        mapped_atom = rr.replacement_query_reaction_match.mapAtom(q_neighbor)
-                        if mapped_atom:
-                            rr_atom_index = mapped_atom.index()
-                            useful_rr_neighbor_indexes.add(rr_atom_index)
-
-            useful_enum_r_mapping_numbers = set()
-            all_enum_r_mapping_numbers = set()
-            for enum_atom in enum_r.iterateAtoms():
-                enum_atom_index = enum_atom.index()
-                mapping_num = reaction.atomMappingNumber(enum_atom)
-                if mapping_num > 0:
-                    all_enum_r_mapping_numbers.add(mapping_num)
-                    # Assuming rr atom indexes are exact match to enum r.
-                    if enum_atom_index in useful_rr_atom_indexes:
-                        useful_enum_r_mapping_numbers.add(mapping_num)
-            ignoring_enum_r_mapping_numbers = all_enum_r_mapping_numbers - useful_enum_r_mapping_numbers - useful_rr_neighbor_indexes
-            all_products_match = True
-
-            rr_products = []
-            for rr_product in rr.reaction.iterateProducts():
-                rr_products.append(rr_product)
-            for j, product in enumerate(products):
-                q_product = rr_products[j]
-                product_matcher = indigo.substructureMatcher(product)
-                ignored_atom_indexes = set()
-                for enum_product_atom in product.iterateAtoms():
-                    enum_mapping_number = reaction.atomMappingNumber(enum_product_atom)
-                    # YQ For each atom in product: either it is not related to this reactant, or it must be inside the reactant site of the reactant.
-                    if enum_mapping_number in ignoring_enum_r_mapping_numbers:
-                        product_matcher.ignoreAtom(enum_product_atom)
-                        ignored_atom_indexes.add(enum_product_atom.index())
-                match = product_matcher.match(q_product)
-                if not match:
-                    all_products_match = False
-                else:
-                    found = rr
-
-            if all_products_match:
-                break
-        if found:
-            ret.append(found)
-        else:
-            return []
-    return ret
-
-
-def are_symmetrical_subs(match1: SerializableMoleculeMatch, match2: SerializableMoleculeMatch) -> bool:
-    """
-    Check if two SerializableMoleculeMatch objects are symmetrical.
-    That is, if we only get the atoms and bonds in the mapping, the two molecules are identical.
-    :param match1: The first SerializableMoleculeMatch object.
-    :param match2: The second SerializableMoleculeMatch object.
-    :return: True if the matches are symmetrical, False otherwise.
-    """
-    match1_test = match1.get_matched_molecule_copy()
-    match1_atom_indexes = set(match1._query_atom_to_atom.values())
-    match1_bond_indexes = set(match1._query_bond_to_bond.values())
-    atom_delete_list: list[int] = []
-    atom_mirror_list: list[int] = []
-    bond_delete_list: list[int] = []
-    bond_mirror_list: list[int] = []
-    for atom in match1_test.iterateAtoms():
-        if atom.index() not in match1_atom_indexes:
-            atom_delete_list.append(atom.index())
-        else:
-            atom_mirror_list.append(atom.index())
-    for bond in match1_test.iterateBonds():
-        if bond.index() not in match1_bond_indexes:
-            bond_delete_list.append(bond.index())
-        else:
-            bond_mirror_list.append(bond.index())
-    match1_test.removeBonds(bond_delete_list)
-    match1_test.removeAtoms(atom_delete_list)
-    match1_mirror_test = match1.get_matched_molecule_copy()
-    match1_mirror_test.removeBonds(bond_mirror_list)
-    match1_mirror_test.removeAtoms(atom_mirror_list)
-
-    match2_test = match2.get_matched_molecule_copy()
-    match2_atom_indexes = set(match2._query_atom_to_atom.values())
-    match2_bond_indexes = set(match2._query_bond_to_bond.values())
-    atom_delete_list = []
-    bond_delete_list = []
-    atom_mirror_list = []
-    bond_mirror_list = []
-    for atom in match2_test.iterateAtoms():
-        if atom.index() not in match2_atom_indexes:
-            atom_delete_list.append(atom.index())
-        else:
-            atom_mirror_list.append(atom.index())
-    for bond in match2_test.iterateBonds():
-        if bond.index() not in match2_bond_indexes:
-            bond_delete_list.append(bond.index())
-        else:
-            bond_mirror_list.append(bond.index())
-    match2_test.removeBonds(bond_delete_list)
-    match2_test.removeAtoms(atom_delete_list)
-    match2_mirror_test = match2.get_matched_molecule_copy()
-    match2_mirror_test.removeBonds(bond_mirror_list)
-    match2_mirror_test.removeAtoms(atom_mirror_list)
-
-    return match1_test.canonicalSmiles() == match2_test.canonicalSmiles() and \
-        match1_mirror_test.canonicalSmiles() == match2_mirror_test.canonicalSmiles()