opentrons 8.3.1a1__py2.py3-none-any.whl → 8.4.0a0__py2.py3-none-any.whl

opentrons/protocol_api/labware.py

@@ -19,23 +19,34 @@ from typing import (
     List,
     Dict,
     Optional,
-    Union,
     Tuple,
     cast,
     Sequence,
     Mapping,
+    Union,
+    Literal,
 )
 
-from opentrons_shared_data.labware.types import LabwareDefinition, LabwareParameters
+from opentrons_shared_data.labware.types import (
+    LabwareDefinition,
+    LabwareDefinition2,
+    LabwareParameters2,
+    LabwareParameters3,
+)
 
-from opentrons.types import Location, Point, NozzleMapInterface
+from opentrons.types import (
+    Location,
+    Point,
+    NozzleMapInterface,
+    MeniscusTrackingTarget,
+)
 from opentrons.protocols.api_support.types import APIVersion
 from opentrons.protocols.api_support.util import (
     requires_version,
     APIVersionError,
     UnsupportedAPIError,
 )
-
+from opentrons.protocol_engine.types.liquid_level_detection import LiquidTrackingType
 
 # TODO(mc, 2022-09-02): re-exports provided for backwards compatibility
 # remove when their usage is no longer needed
@@ -49,7 +60,10 @@ from . import validation
 from ._liquid import Liquid
 from ._types import OffDeckType
 from .core import well_grid
-from .core.engine import ENGINE_CORE_API_VERSION, SET_OFFSET_RESTORED_API_VERSION
+from .core.engine import (
+    ENGINE_CORE_API_VERSION,
+    SET_OFFSET_RESTORED_API_VERSION,
+)
 from .core.labware import AbstractLabware
 from .core.module import AbstractModuleCore
 from .core.core_map import LoadedCoreMap
@@ -248,16 +262,21 @@ class Well:
         return Location(self._core.get_center(), self)
 
     @requires_version(2, 21)
-    def meniscus(self, z: float = 0.0) -> Location:
+    def meniscus(
+        self, target: Literal["start", "end", "dynamic"], z: float = 0.0
+    ) -> Location:
         """
         :param z: An offset on the z-axis, in mm. Positive offsets are higher and
             negative offsets are lower.
+        :param target: The relative position inside the well to target when performing a liquid handling operation.
         :return: A :py:class:`~opentrons.types.Location` that indicates location is meniscus and that holds the ``z`` offset in its point.z field.
 
         :meta private:
         """
         return Location(
-            point=Point(x=0, y=0, z=z), labware=self, _ot_internal_is_meniscus=True
+            point=Point(x=0, y=0, z=z),
+            labware=self,
+            _meniscus_tracking=MeniscusTrackingTarget(target),
         )
 
     @requires_version(2, 8)
@@ -316,6 +335,35 @@ class Well:
             volume=volume,
         )
 
+    @requires_version(2, 21)
+    def current_liquid_height(self) -> LiquidTrackingType:
+        """Get the current liquid height in a well."""
+        return self._core.current_liquid_height()
+
+    @requires_version(2, 21)
+    def current_liquid_volume(self) -> LiquidTrackingType:
+        """Get the current liquid volume in a well."""
+        return self._core.get_liquid_volume()
+
+    @requires_version(2, 21)
+    def estimate_liquid_height_after_pipetting(
+        self,
+        operation_volume: float,
+    ) -> LiquidTrackingType:
+        """Check the height of the liquid within a well.
+
+        :returns: The height, in mm, of the liquid from the deck.
+
+        :meta private:
+
+        This is intended for Opentrons internal use only and is not a guaranteed API.
+        """
+
+        projected_final_height = self._core.estimate_liquid_height_after_pipetting(
+            operation_volume=operation_volume,
+        )
+        return projected_final_height
+
     def _from_center_cartesian(self, x: float, y: float, z: float) -> Point:
         """
         Private version of from_center_cartesian. Present only for backward
@@ -509,7 +557,7 @@ class Labware:
 
     @property
     @requires_version(2, 0)
-    def parameters(self) -> "LabwareParameters":
+    def parameters(self) -> "LabwareParameters2 | LabwareParameters3":
         """Internal properties of a labware including type and quirks."""
         return self._core.get_parameters()
 
@@ -658,6 +706,8 @@ class Labware:
             automatically.
 
         :return: The initialized and loaded labware object representing the Lid Stack.
+
+        :meta private:
         """
         if self._api_version < validation.LID_STACK_VERSION_GATE:
             raise APIVersionError(
@@ -712,11 +762,15 @@ class Labware:
 
         .. list-table::
             :header-rows: 1
+            :widths: 1 5
 
             * - API level
               - Offset behavior
             * - 2.12–2.13
               - Offsets only apply to the exact :py:class:`.Labware` instance.
+
+                If your protocol has multiple instances of the same type of labware,
+                you must either use ``set_offset()`` on all of them or none of them.
             * - 2.14–2.17
               - ``set_offset()`` is not available, and the API raises an error.
             * - 2.18 and newer
@@ -1417,7 +1471,7 @@ def next_available_tip(
 # TODO(mc, 2022-11-09): implementation detail, move somewhere else
 # only used in old calibration flows by robot-server
 def load_from_definition(
-    definition: "LabwareDefinition",
+    definition: "LabwareDefinition2",
     parent: Location,
     label: Optional[str] = None,
     api_level: Optional[APIVersion] = None,
@@ -1461,8 +1515,8 @@ def load(
     label: Optional[str] = None,
     namespace: Optional[str] = None,
     version: int = 1,
-    bundled_defs: Optional[Dict[str, LabwareDefinition]] = None,
-    extra_defs: Optional[Dict[str, LabwareDefinition]] = None,
+    bundled_defs: Optional[Mapping[str, LabwareDefinition2]] = None,
+    extra_defs: Optional[Mapping[str, LabwareDefinition2]] = None,
     api_level: Optional[APIVersion] = None,
 ) -> Labware:
     """
@@ -1500,4 +1554,14 @@ def load(
         extra_defs=extra_defs,
     )
 
+    # The legacy `load_from_definition()` function that we're calling only supports
+    # schemaVersion==2 labware. Fortunately, when robot-server calls this function,
+    # we only expect it to try to load schemaVersion==2 labware, so we never expect
+    # this ValueError to be raised in practice.
+    if definition["schemaVersion"] != 2:
+        raise ValueError(
+            f"{namespace}/{load_name}/{version} has schema {definition['schemaVersion']}."
+            " Only schema 2 is supported."
+        )
+
     return load_from_definition(definition, parent, label, api_level)

opentrons/protocol_api/module_contexts.py

@@ -29,6 +29,7 @@ from .core.common import (
     HeaterShakerCore,
     MagneticBlockCore,
     AbsorbanceReaderCore,
+    FlexStackerCore,
 )
 from .core.core_map import LoadedCoreMap
 from .core.engine import ENGINE_CORE_API_VERSION
@@ -1098,3 +1099,142 @@ class AbsorbanceReaderContext(ModuleContext):
         :returns: A dictionary of wavelengths to dictionary of values ordered by well name.
         """
         return self._core.read(filename=export_filename)
+
+
+class FlexStackerContext(ModuleContext):
+    """An object representing a connected Flex Stacker module.
+
+    It should not be instantiated directly; instead, it should be
+    created through :py:meth:`.ProtocolContext.load_module`.
+
+    .. versionadded:: 2.23
+    """
+
+    _core: FlexStackerCore
+
+    @property
+    @requires_version(2, 23)
+    def serial_number(self) -> str:
+        """Get the module's unique hardware serial number."""
+        return self._core.get_serial_number()
+
+    @requires_version(2, 23)
+    def retrieve(self) -> Labware:
+        """Retrieve a labware from the Flex Stacker and place it on the shuttle.
+
+        :returns: The retrieved :py:class:`Labware` object. This will always be the main labware,
+                  even if the Flex Stacker contains labware on an adapter. To get the adapter object,
+                  call :py:class:`Labware.parent` on the returned labware.
+
+        """
+        self._core.retrieve()
+
+        labware_core = self._protocol_core.get_labware_on_module(self._core)
+        if labware_core is not None and labware_core.is_adapter():
+            adapter_core = labware_core
+            adapter = Labware(
+                core=adapter_core,
+                api_version=self._api_version,
+                protocol_core=self._protocol_core,
+                core_map=self._core_map,
+            )
+            self._core_map.add(adapter_core, adapter)
+            labware_core = self._protocol_core.get_labware_on_labware(adapter_core)
+
+        # the core retrieve command should have already raised the error
+        # if labware_core is None, this is just to satisfy the type checker
+        assert labware_core is not None, "Retrieve failed to return labware"
+        # check core map first
+        try:
+            labware = self._core_map.get(labware_core)
+        except KeyError:
+            # If the labware is not already in the core map,
+            # create a new Labware object
+            labware = Labware(
+                core=labware_core,
+                api_version=self._api_version,
+                protocol_core=self._protocol_core,
+                core_map=self._core_map,
+            )
+            self._core_map.add(labware_core, labware)
+        return labware
+
+    @requires_version(2, 23)
+    def store(self) -> None:
+        """Move the labware currently on the Flex Stacker shuttle into the Flex Stacker."""
+        self._core.store()
+
+    @requires_version(2, 23)
+    def set_stored_labware(
+        self,
+        load_name: str,
+        namespace: str | None = None,
+        version: int | None = None,
+        adapter: str | None = None,
+        lid: str | None = None,
+        count: int | None = None,
+    ) -> None:
+        """Configure what kind of labware the Flex Stacker will store.
+
+        :param str load_name: A string to use for looking up a labware definition.
+            You can find the ``load_name`` for any Opentrons-verified labware on the
+            `Labware Library <https://labware.opentrons.com>`__.
+        :param str namespace: The namespace that the labware definition belongs to.
+            If unspecified, the API will automatically search two namespaces:
+
+              - ``"opentrons"``, to load standard Opentrons labware definitions.
+              - ``"custom_beta"``, to load custom labware definitions created with the
+                `Custom Labware Creator <https://labware.opentrons.com/create>`__.
+
+            You might need to specify an explicit ``namespace`` if you have a custom
+            definition whose ``load_name`` is the same as an Opentrons-verified
+            definition, and you want to explicitly choose one or the other.
+        :param version: The version of the labware definition. You should normally
+            leave this unspecified to let ``load_labware()`` choose a version
+            automatically.
+        :param adapter: An adapter to load the labware on top of. Accepts the same
+            values as the ``load_name`` parameter of :py:meth:`.load_adapter`. The
+            adapter will use the same namespace as the labware, and the API will
+            choose the adapter's version automatically.
+        :param lid: A lid to load the on top of the main labware. Accepts the same
+            values as the ``load_name`` parameter of :py:meth:`.load_lid_stack`. The
+            lid will use the same namespace as the labware, and the API will
+            choose the lid's version automatically.
+        :param count: The number of labware that the Flex Stacker should start the protocol
+            storing. If not specified, this will be the maximum amount of this kind of
+            labware that the Flex Stacker is capable of storing.
+
+        """
+        self._core.set_stored_labware(
+            main_load_name=load_name,
+            main_namespace=namespace,
+            main_version=version,
+            lid_load_name=lid,
+            lid_namespace=namespace,
+            lid_version=version,
+            adapter_load_name=adapter,
+            adapter_namespace=namespace,
+            adapter_version=version,
+            count=count,
+        )
+
+    @requires_version(2, 23)
+    def fill(self, message: str, count: int | None = None) -> None:
+        """Pause the protocol to add more labware to the Flex Stacker.
+
+        :param message: A message to display in the Opentrons App to note what kind of labware to add.
+        :param count: The amount of labware the Flex Stacker should hold after this command is executed.
+                      If not specified, the Flex Stacker should be full after this command is executed.
+        """
+        self._core.fill(message, count)
+
+    @requires_version(2, 23)
+    def empty(self, message: str) -> None:
+        """Pause the protocol to remove labware from the Flex Stacker.
+
+        :param message: A message to display in the Opentrons App to note what should be removed from
+                        the Flex Stacker.
+        """
+        self._core.empty(
+            message,
+        )

opentrons/protocol_api/protocol_context.py

@@ -14,17 +14,19 @@ from typing import (
 
 from opentrons_shared_data.labware.types import LabwareDefinition
 from opentrons_shared_data.pipette.types import PipetteNameType
-from opentrons_shared_data.robot.types import RobotTypeEnum
 
 from opentrons.types import Mount, Location, DeckLocation, DeckSlotName, StagingSlotName
-from opentrons.config import feature_flags
 from opentrons.legacy_broker import LegacyBroker
 from opentrons.hardware_control.modules.types import (
     MagneticBlockModel,
     AbsorbanceReaderModel,
+    FlexStackerModuleModel,
 )
 from opentrons.legacy_commands import protocol_commands as cmds, types as cmd_types
-from opentrons.legacy_commands.helpers import stringify_labware_movement_command
+from opentrons.legacy_commands.helpers import (
+    stringify_labware_movement_command,
+    stringify_lid_movement_command,
+)
 from opentrons.legacy_commands.publisher import (
     CommandPublisher,
     publish,
@@ -58,6 +60,7 @@ from .core.module import (
     AbstractHeaterShakerCore,
     AbstractMagneticBlockCore,
     AbstractAbsorbanceReaderCore,
+    AbstractFlexStackerCore,
 )
 from .robot_context import RobotContext, HardwareManager
 from .core.engine import ENGINE_CORE_API_VERSION
@@ -76,6 +79,7 @@ from .module_contexts import (
     HeaterShakerContext,
     MagneticBlockContext,
     AbsorbanceReaderContext,
+    FlexStackerContext,
     ModuleContext,
 )
 from ._parameters import Parameters
@@ -91,6 +95,7 @@ ModuleTypes = Union[
     HeaterShakerContext,
     MagneticBlockContext,
     AbsorbanceReaderContext,
+    FlexStackerContext,
 ]
 
 
@@ -444,13 +449,16 @@ class ProtocolContext(CommandPublisher):
             values as the ``load_name`` parameter of :py:meth:`.load_adapter`. The
             adapter will use the same namespace as the labware, and the API will
             choose the adapter's version automatically.
-        :param lid: A lid to load the on top of the main labware. Accepts the same
-            values as the ``load_name`` parameter of :py:meth:`.load_lid_stack`. The
-            lid will use the same namespace as the labware, and the API will
-            choose the lid's version automatically.
 
                         .. versionadded:: 2.15
         """
+        # TODO: re-include in docstring when 2.23 is ready
+        #         :param lid: A lid to load the on top of the main labware. Accepts the same
+        #             values as the ``load_name`` parameter of :py:meth:`.load_lid_stack`. The
+        #             lid will use the same namespace as the labware, and the API will
+        #             choose the lid's version automatically.
+        #
+        #                         .. versionadded:: 2.23
         if isinstance(location, OffDeckType) and self._api_version < APIVersion(2, 15):
             raise APIVersionError(
                 api_element="Loading a labware off-deck",
@@ -859,6 +867,10 @@ class ProtocolContext(CommandPublisher):
 
                   .. versionchanged:: 2.15
                     Added ``MagneticBlockContext`` return value.
+
+                  .. TODO uncomment when 2.23 is ready
+                    versionchanged:: 2.23
+                    Added ``FlexStackerModuleContext`` return value.
         """
         if configuration:
             if self._api_version < APIVersion(2, 4):
@@ -887,7 +899,18 @@ class ProtocolContext(CommandPublisher):
             requested_model, AbsorbanceReaderModel
         ) and self._api_version < APIVersion(2, 21):
             raise APIVersionError(
-                f"Module of type {module_name} is only available in versions 2.21 and above."
+                api_element=f"Module of type {module_name}",
+                until_version="2.21",
+                current_version=f"{self._api_version}",
+            )
+        if (
+            isinstance(requested_model, FlexStackerModuleModel)
+            and self._api_version < validation.FLEX_STACKER_VERSION_GATE
+        ):
+            raise APIVersionError(
+                api_element=f"Module of type {module_name}",
+                until_version=str(validation.FLEX_STACKER_VERSION_GATE),
+                current_version=f"{self._api_version}",
             )
 
         deck_slot = (
@@ -898,7 +921,11 @@ class ProtocolContext(CommandPublisher):
             )
         )
         if isinstance(deck_slot, StagingSlotName):
-            raise ValueError("Cannot load a module onto a staging slot.")
+            # flex stacker modules can only be loaded into staging slot inside a protocol
+            if isinstance(requested_model, FlexStackerModuleModel):
+                deck_slot = validation.convert_flex_stacker_load_slot(deck_slot)
+            else:
+                raise ValueError(f"Cannot load {module_name} onto a staging slot.")
 
         module_core = self._core.load_module(
             model=requested_model,
@@ -1329,17 +1356,17 @@ class ProtocolContext(CommandPublisher):
             display_color=display_color,
         )
 
+    @requires_version(2, 23)
     def define_liquid_class(
         self,
         name: str,
     ) -> LiquidClass:
-        """Define a liquid class for use in the protocol."""
-        if feature_flags.allow_liquid_classes(
-            robot_type=RobotTypeEnum.robot_literal_to_enum(self._core.robot_type)
-        ):
-            return self._core.define_liquid_class(name=name)
-        else:
-            raise NotImplementedError("This method is not implemented.")
+        """
+        Define a liquid class for use in the protocol.
+
+        :meta private:
+        """
+        return self._core.define_liquid_class(name=name)
 
     @property
     @requires_version(2, 5)
@@ -1392,6 +1419,8 @@ class ProtocolContext(CommandPublisher):
             automatically.
 
         :return:  The initialized and loaded labware object representing the Lid Stack.
+
+        :meta private:
         """
         if self._api_version < validation.LID_STACK_VERSION_GATE:
             raise APIVersionError(
@@ -1441,6 +1470,115 @@ class ProtocolContext(CommandPublisher):
         )
         return labware
 
+    @requires_version(2, 23)
+    def move_lid(
+        self,
+        source_location: Union[DeckLocation, Labware],
+        new_location: Union[DeckLocation, Labware, OffDeckType, WasteChute, TrashBin],
+        use_gripper: bool = False,
+        pick_up_offset: Optional[Mapping[str, float]] = None,
+        drop_offset: Optional[Mapping[str, float]] = None,
+    ) -> Labware | None:
+        """Move a lid from a valid source to a new location. Can return a Lid Stack if one is created.
+
+        :param source_location: Where to take the lid from. This is either:
+
+                * A deck slot like ``1``, ``"1"``, or ``"D1"``. See :ref:`deck-slots`.
+                * A labware or adapter that's already been loaded on the deck
+                  with :py:meth:`load_labware` or :py:meth:`load_adapter`.
+                * A lid stack that's already been loaded on the deck with
+                  with :py:meth:`load_lid_stack`.
+
+        :param new_location: Where to move the lid to. This is either:
+
+                * A deck slot like ``1``, ``"1"``, or ``"D1"``. See :ref:`deck-slots`.
+                * A hardware module that's already been loaded on the deck
+                  with :py:meth:`load_module`.
+                * A labware or adapter that's already been loaded on the deck
+                  with :py:meth:`load_labware` or :py:meth:`load_adapter`.
+                * The special constant :py:obj:`OFF_DECK`.
+
+        :param use_gripper: Whether to use the Flex Gripper for this movement.
+
+                * If ``True``, use the gripper to perform an automatic
+                  movement. This will raise an error in an OT-2 protocol.
+                * If ``False``, pause protocol execution until the user
+                  performs the movement. Protocol execution remains paused until
+                  the user presses **Confirm and resume**.
+
+        Gripper-only parameters:
+
+        :param pick_up_offset: Optional x, y, z vector offset to use when picking up a lid.
+        :param drop_offset: Optional x, y, z vector offset to use when dropping off a lid.
+
+        Before moving a lid to or from a labware in a hardware module, make sure that the
+        labware's current and new locations are accessible, i.e., open the Thermocycler lid
+        or open the Heater-Shaker's labware latch.
+
+        :meta private:
+        """
+        source: Union[LabwareCore, DeckSlotName, StagingSlotName]
+        if isinstance(source_location, Labware):
+            source = source_location._core
+        else:
+            source = validation.ensure_and_convert_deck_slot(
+                source_location, self._api_version, self._core.robot_type
+            )
+
+        destination: Union[
+            ModuleCore,
+            LabwareCore,
+            WasteChute,
+            OffDeckType,
+            DeckSlotName,
+            StagingSlotName,
+            TrashBin,
+        ]
+        if isinstance(new_location, Labware):
+            destination = new_location._core
+        elif isinstance(new_location, (OffDeckType, WasteChute, TrashBin)):
+            destination = new_location
+        else:
+            destination = validation.ensure_and_convert_deck_slot(
+                new_location, self._api_version, self._core.robot_type
+            )
+
+        _pick_up_offset = (
+            validation.ensure_valid_labware_offset_vector(pick_up_offset)
+            if pick_up_offset
+            else None
+        )
+        _drop_offset = (
+            validation.ensure_valid_labware_offset_vector(drop_offset)
+            if drop_offset
+            else None
+        )
+        with publish_context(
+            broker=self.broker,
+            command=cmds.move_labware(
+                # This needs to be called from protocol context and not the command for import loop reasons
+                text=stringify_lid_movement_command(
+                    source_location, new_location, use_gripper
+                )
+            ),
+        ):
+            result = self._core.move_lid(
+                source_location=source,
+                new_location=destination,
+                use_gripper=use_gripper,
+                pause_for_manual_move=True,
+                pick_up_offset=_pick_up_offset,
+                drop_offset=_drop_offset,
+            )
+        if result is not None:
+            return Labware(
+                core=result,
+                api_version=self._api_version,
+                protocol_core=self._core,
+                core_map=self._core_map,
+            )
+        return None
+
 
 def _create_module_context(
     module_core: Union[ModuleCore, NonConnectedModuleCore],
@@ -1462,6 +1600,8 @@ def _create_module_context(
         module_cls = MagneticBlockContext
     elif isinstance(module_core, AbstractAbsorbanceReaderCore):
         module_cls = AbsorbanceReaderContext
+    elif isinstance(module_core, AbstractFlexStackerCore):
+        module_cls = FlexStackerContext
     else:
         assert False, "Unsupported module type"