sapiopycommons 2025.3.21a458__py3-none-any.whl → 2025.3.25a459__py3-none-any.whl

sapiopycommons/eln/experiment_report_util.py

@@ -4,6 +4,7 @@ from sapiopylib.rest.pojo.CustomReport import CustomReportCriteria, AbstractRepo
 from sapiopylib.rest.pojo.datatype.FieldDefinition import FieldType
 from sapiopylib.rest.pojo.eln.ElnExperiment import ElnExperiment, ElnExperimentQueryCriteria
 from sapiopylib.rest.pojo.eln.SapioELNEnums import ElnExperimentStatus, ElnBaseDataType
+from sapiopylib.rest.utils.recordmodel.PyRecordModel import PyRecordModel
 from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedType
 
 from sapiopycommons.customreport.auto_pagers import CustomReportDictAutoPager
@@ -209,16 +210,20 @@ class ExperimentReportUtil:
                 ret_val[record] = exp_id
         return ret_val
 
+    # CR-47491: Support providing a data type name string to receive PyRecordModels instead of requiring a WrapperType.
     @staticmethod
     def map_experiments_to_records_of_type(context: UserIdentifier, exp_ids: list[ExperimentIdentifier],
-                                           wrapper_type: type[WrappedType]) -> dict[int, list[WrappedType]]:
+                                           wrapper_type: type[WrappedType] | str) \
+            -> dict[int, list[WrappedType] | list[PyRecordModel]]:
         """
         Return a dictionary mapping each experiment id to a list of records of the given type that were used in each
         experiment. If an experiment didn't use any records of the given type then it will be mapped to an empty list.
 
         :param context: The current webhook context or a user object to send requests from.
         :param exp_ids: A list of experiment identifiers.
-        :param wrapper_type: The record model wrapper to use, corresponds to which data type we will query for.
+        :param wrapper_type: The record model wrapper or data type name to use, corresponds to which data type we will
+            query for. If a data type name is provided, the returned records will be PyRecordModels instead of
+            WrappedRecordModels.
         :return: A dictionary mapping each experiment id to a list of records of the given type that were used in that
             experiment.
         """
@@ -227,7 +232,7 @@ class ExperimentReportUtil:
 
         user = AliasUtil.to_sapio_user(context)
         record_handler = RecordHandler(user)
-        data_type_name: str = wrapper_type.get_wrapper_data_type_name()
+        data_type_name: str = AliasUtil.to_data_type_name(wrapper_type)
 
         exp_ids: list[int] = AliasUtil.to_notebook_ids(exp_ids)
         rows = ExperimentReportUtil.__get_record_experiment_relation_rows(user, data_type_name, exp_ids=exp_ids)

sapiopycommons/eln/experiment_tags.py

@@ -0,0 +1,7 @@
+# CSP paths:
+PLATE_DESIGNER_PLUGIN: str = "com.velox.gwt.client.plugins.multilayerplating.core.ElnMultiLayerPlatingClientPlugin"
+
+# 3D Plate Designer entry tags:
+PLATE_IDS_TAG: str = "MultiLayerPlating_Plate_RecordIdList"
+PLATE_CONFIG_PREFS_TAG: str = "MultiLayerPlating_Entry_PrePlating_Prefs"
+PLATE_LAYER_PREFS_TAG: str = "MultiLayerPlating_Entry_Prefs"

sapiopycommons/eln/plate_designer.py

@@ -1,43 +1,64 @@
 from sapiopylib.rest.utils.Protocols import ElnEntryStep
+from sapiopylib.rest.utils.plates.PlatingUtils import PlateLocation
+from sapiopylib.rest.utils.recordmodel.PyRecordModel import PyRecordModel
 from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedType
 
+from sapiopycommons.datatype.data_fields import PlateDesignerWellElementFields
 from sapiopycommons.eln.experiment_handler import ExperimentHandler
-from sapiopycommons.general.aliases import SapioRecord, RecordIdentifier, AliasUtil
+from sapiopycommons.eln.experiment_tags import PLATE_IDS_TAG
+from sapiopycommons.general.aliases import RecordIdentifier, AliasUtil, RecordModel, FieldValue
 from sapiopycommons.general.exceptions import SapioException
 from sapiopycommons.recordmodel.record_handler import RecordHandler
 
-PLATE_IDS_TAG: str = "MultiLayerPlating_Plate_RecordIdList"
+# Shorthands for longer type names.
+WellElement = PlateDesignerWellElementFields
 
 
-class PlateDesignerEntry:
+# FR-47486: Change the PlateDesignerEntry class to extend ElnEntryStep instead of containing one.
+class PlateDesignerEntry(ElnEntryStep):
     """
     A wrapper for 3D plate designer entries in experiments, providing functions for common actions when dealing with
     such entries.
     """
-    step: ElnEntryStep
-    __exp_handler: ExperimentHandler
-    __rec_handler: RecordHandler
-    __plates: list[SapioRecord] | None
-    __aliquots: list[SapioRecord] | None
-    __sources: list[SapioRecord] | None
-    __designer_elements: list[SapioRecord] | None
-    __plate_ids: list[int] | None
+    _exp_handler: ExperimentHandler
+    _rec_handler: RecordHandler
+    _plates: list[RecordModel] | None
+    _aliquots: list[RecordModel] | None
+    _sources: list[RecordModel] | None
+    _designer_elements: list[RecordModel] | None
+    _designer_elements_by_plate: dict[int, list[RecordModel]] | None
+    _plate_ids: list[int] | None
 
     def __init__(self, step: ElnEntryStep, exp_handler: ExperimentHandler):
         """
         :param step: The ElnEntryStep that is the 3D plate designer entry.
         :param exp_handler: An ExperimentHandler for the experiment that this entry comes from.
         """
-        self.step = step
-        self.__exp_handler = exp_handler
-        self.__rec_handler = RecordHandler(exp_handler.context)
-        self.__plates = None
-        self.__aliquots = None
-        self.__sources = None
-        self.__designer_elements = None
-        self.__plate_ids = None
+        super().__init__(exp_handler.protocol, step.eln_entry)
+        self._exp_handler = exp_handler
+        self._rec_handler = RecordHandler(exp_handler.user)
+        self._plates = None
+        self._aliquots = None
+        self._sources = None
+        self._designer_elements = None
+        self._designer_elements_by_plate = None
+        self._plate_ids = None
+
+    @property
+    def step(self) -> ElnEntryStep:
+        return self
+
+    def clear_cache(self) -> None:
+        """
+        Clear the caches for the plates and plate designer well elements in this plate designer entry. This will require
+        a new webservice call to get the plates and designer elements the next time they are requested.
+        """
+        self._plates = None
+        self._designer_elements = None
+        self._designer_elements_by_plate = None
 
-    def get_plates(self, wrapper_type: type[WrappedType]) -> list[WrappedType]:
+    # CR-47491: Support not providing a wrapper type to receive PyRecordModels instead of WrappedRecordModels.
+    def get_plates(self, wrapper_type: type[WrappedType] | None = None) -> list[WrappedType] | list[PyRecordModel]:
         """
         Get the plates that are in the designer entry.
 
@@ -45,13 +66,16 @@ class PlateDesignerEntry:
         will be invalidated if a set_plates or add_plates call is made, requiring a new webservice call the next time
         this function is called.
 
-        :param wrapper_type: The record model wrapper to use.
+        :param wrapper_type: The record model wrapper to use on the plates. If not provided, the returned records will
+            be PyRecordModels instead of WrappedRecordModels.
         :return: A list of the plates in the designer entry.
         """
-        if self.__plates is not None:
-            return self.__plates
-        self.__plates = self.__rec_handler.query_models_by_id(wrapper_type, self.__get_plate_ids())
-        return self.__plates
+        if self._plates is not None:
+            return self._plates
+        if wrapper_type is None:
+            wrapper_type = "Plate"
+        self._plates = self._rec_handler.query_models_by_id(wrapper_type, self.__get_plate_ids())
+        return self._plates
 
     def set_plates(self, plates: list[RecordIdentifier]) -> None:
         """
@@ -76,47 +100,50 @@ class PlateDesignerEntry:
         record_ids: list[int] = AliasUtil.to_record_ids(plates)
         self.__set_plate_ids(self.__get_plate_ids() + record_ids)
 
-    def get_sources(self, wrapper_type: type[WrappedType]) -> list[WrappedType]:
+    def get_sources(self, wrapper_type: type[WrappedType] | str) -> list[WrappedType] | list[PyRecordModel]:
         """
         Get the source records that were used to populate the plate designer entry's sample table. This looks for the
-        entries that the plate designer entry is dependent upon and gets their records if they match the data type name
-        of the given wrapper.
+        entries that the plate designer entry is implicitly dependent upon and gets their records if they match the
+        data type name of the given wrapper.
 
         Makes a webservice call to retrieve the dependent entries if the experiment handler had not already cached it.
         Makes another webservice call to get the records from the dependent entry and caches them for future calls.
 
-        :param wrapper_type: The record model wrapper to use.
+        :param wrapper_type: The record model wrapper or data type name of the records to retrieve. If a data type name
+            is provided, then the returned records will be PyRecordModels instead of WrappedRecordModels.
         :return: A list of the source records that populate the plate designer entry's sample table.
         """
-        if self.__sources is not None:
-            return self.__sources
+        if self._sources is not None:
+            return self._sources
 
         records: list[WrappedType] = []
-        dependent_ids: list[int] = self.step.eln_entry.dependency_set
-        for step in self.__exp_handler.get_all_steps(wrapper_type):
+        dependent_ids: list[int] = self.step.eln_entry.related_entry_id_set
+        for step in self._exp_handler.get_all_steps(wrapper_type):
             if step.get_id() in dependent_ids:
-                records.extend(self.__exp_handler.get_step_models(step, wrapper_type))
+                records.extend(self._exp_handler.get_step_models(step, wrapper_type))
 
-        self.__sources = records
-        return self.__sources
+        self._sources = records
+        return self._sources
 
-    def get_aliquots(self, wrapper_type: type[WrappedType]) -> list[WrappedType]:
+    def get_aliquots(self, wrapper_type: type[WrappedType] | None = None) -> list[WrappedType] | list[PyRecordModel]:
         """
         Get the aliquots that were created from this plate designer entry upon its submission.
 
         Makes a webservice call to retrieve the aliquots from the plate designer entry and caches them for future calls.
 
-        :param wrapper_type: The record model wrapper to use.
+        :param wrapper_type: The record model wrapper to use. If not provided, the returned records will be
+            PyRecordModels instead of WrappedRecordModels.
         :return: A list of the aliquots created by the plate designer entry.
         """
-        if not self.__exp_handler.step_is_submitted(self.step):
+        if not self._exp_handler.step_is_submitted(self.step):
             raise SapioException("The plate designer entry must be submitted before its aliquots can be retrieved.")
-        if self.__aliquots is not None:
-            return self.__aliquots
-        self.__aliquots = self.__exp_handler.get_step_models(self.step, wrapper_type)
-        return self.__aliquots
+        if self._aliquots is not None:
+            return self._aliquots
+        self._aliquots = self._exp_handler.get_step_models(self.step, wrapper_type)
+        return self._aliquots
 
-    def get_plate_designer_well_elements(self, wrapper_type: type[WrappedType]) -> list[WrappedType]:
+    def get_plate_designer_well_elements(self, wrapper_type: type[WrappedType] | None = None) \
+            -> list[WrappedType] | list[PyRecordModel]:
         """
         Get the plate designer well elements for the plates in the plate designer entry. These are the records in the
         system that determine how wells are displayed on each plate in the entry.
@@ -125,28 +152,101 @@ class PlateDesignerEntry:
         This cache will be invalidated if a set_plates or add_plates call is made, requiring a new webservice call the
         next time this function is called.
 
-        :param wrapper_type: The record model wrapper to use.
+        :param wrapper_type: The record model wrapper to use. If not provided, the returned records will be
+            PyRecordModels instead of WrappedRecordModels.
+        :return: A list of the plate designer well elements in the designer entry.
+        """
+        if self._designer_elements is not None:
+            return self._designer_elements
+        if wrapper_type is None:
+            wrapper_type: str = WellElement.DATA_TYPE_NAME
+        self._designer_elements = self._rec_handler.query_models(wrapper_type,
+                                                                 WellElement.PLATE_RECORD_ID__FIELD,
+                                                                 self.__get_plate_ids())
+        if self._designer_elements_by_plate is None:
+            self._designer_elements_by_plate = {}
+        self._designer_elements_by_plate.clear()
+        for element in self._designer_elements:
+            plate_id: int = element.get(WellElement.PLATE_RECORD_ID__FIELD)
+            self._designer_elements_by_plate.setdefault(plate_id, []).append(element)
+        return self._designer_elements
+
+    def get_well_elements_by_plate(self, plate: RecordIdentifier, wrapper_type: type[WrappedType] | None = None) \
+            -> list[WrappedType] | list[PyRecordModel]:
+        """
+        Get the plate designer well elements for the given plate in the plate designer entry. These are the records in
+        the system that determine how wells are displayed on the plate in the entry.
+
+        Makes a webservice call to get the plate designer well elements of the entry and caches them for future calls.
+        This cache will be invalidated if a set_plates or add_plates call is made, requiring a new webservice call the
+        next time this function is called.
+
+        :param plate: The plate to get the well elements for.
+        :param wrapper_type: The record model wrapper to use. If not provided, the returned records will be
+            PyRecordModels instead of WrappedRecordModels.
         :return: A list of the plate designer well elements in the designer entry.
         """
-        if self.__designer_elements is not None:
-            return self.__designer_elements
-        self.__designer_elements = self.__rec_handler.query_models(wrapper_type, "PlateRecordId",
-                                                                   self.__get_plate_ids())
-        return self.__designer_elements
+        plate: int = AliasUtil.to_record_id(plate)
+        if plate not in self.__get_plate_ids():
+            raise SapioException(f"Plate record ID {plate} is not in this plate designer entry.")
+        if self._designer_elements_by_plate is None:
+            self.get_plate_designer_well_elements(wrapper_type)
+        return self._designer_elements_by_plate[plate]
+
+    def create_well_element(self, sample: RecordModel, plate: RecordModel, location: PlateLocation | None = None,
+                            wrapper_type: type[WrappedType] | None = None) -> WrappedType | PyRecordModel:
+        """
+        Create a new plate designer well element for the input sample and plate. A record model manager store and commit
+        must be called to save this new well element to the server.
+
+        :param sample: The sample that the element is for. Must exist in the system (i.e. have a >0 record ID).
+        :param plate: The plate that the element is for. Must exist in the system (i.e. have a >0 record ID).
+        :param location: The location of the well element. If not provided, the row and column position fields of the
+            sample will be used.
+        :param wrapper_type: The record model wrapper to use for the plate designer well element. If not provided, the
+            returned record will be a PyRecordModel instead of a WrappedRecordModel.
+        :return: The newly created PlateDesignerWellElementModel.
+        """
+        # Confirm that we can actually make a designer element for the input records.
+        if AliasUtil.to_record_id(sample) <= 0:
+            raise SapioException("Cannot create plate designer well element for sample without a record ID.")
+        if AliasUtil.to_record_id(plate) <= 0:
+            raise SapioException("Cannot create plate designer well element for plate without a record ID.")
+        if AliasUtil.to_data_type_name(sample) != "Sample":
+            raise SapioException("Sample record must be of type Sample.")
+        if AliasUtil.to_data_type_name(plate) != "Plate":
+            raise SapioException("Plate record must be of type Plate.")
+
+        dt: type[WrappedType] | str = wrapper_type if wrapper_type else WellElement.DATA_TYPE_NAME
+        plate_id: int = AliasUtil.to_record_id(plate)
+        fields: dict[str, FieldValue] = {
+            WellElement.SOURCE_RECORD_ID__FIELD: AliasUtil.to_record_id(sample),
+            WellElement.PLATE_RECORD_ID__FIELD: plate_id,
+            WellElement.ROW_POSITION__FIELD: location.row_pos if location else sample.get_field_value("RowPosition"),
+            WellElement.COL_POSITION__FIELD: str(location.col_pos) if location else sample.get_field_value("ColPosition"),
+            WellElement.SOURCE_DATA_TYPE_NAME__FIELD: "Sample",
+        }
+        element = self._rec_handler.add_models_with_data(dt, [fields])[0]
+
+        # Add the new element to the cache.
+        if self._designer_elements is not None:
+            self._designer_elements.append(element)
+        if self._designer_elements_by_plate is not None and plate_id in self._designer_elements_by_plate:
+            self._designer_elements_by_plate.setdefault(plate_id, []).append(element)
+        return element
 
     def __get_plate_ids(self) -> list[int]:
-        if self.__plate_ids is not None:
-            return self.__plate_ids
-        id_tag: str = self.__exp_handler.get_step_option(self.step, PLATE_IDS_TAG)
+        if self._plate_ids is not None:
+            return self._plate_ids
+        id_tag: str = self._exp_handler.get_step_option(self.step, PLATE_IDS_TAG)
         if not id_tag:
             raise SapioException("No plates in the plate designer entry")
-        self.__plate_ids = [int(x) for x in id_tag.split(",")]
-        return self.__plate_ids
+        self._plate_ids = [int(x) for x in id_tag.split(",")]
+        return self._plate_ids
 
     def __set_plate_ids(self, record_ids: list[int]) -> None:
         record_ids.sort()
-        self.__exp_handler.add_step_options(self.step, {PLATE_IDS_TAG: ",".join([str(x) for x in record_ids])})
-        self.__plate_ids = record_ids
+        self._exp_handler.add_step_options(self.step, {PLATE_IDS_TAG: ",".join([str(x) for x in record_ids])})
+        self._plate_ids = record_ids
         # The plates and designer elements caches have been invalidated.
-        self.__plates = None
-        self.__designer_elements = None
+        self.clear_cache()