opentrons 8.3.2a0__py2.py3-none-any.whl → 8.4.0__py2.py3-none-any.whl

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
+
+                        .. versionadded:: 2.15
+        :param lid: A lid to load on the 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.
+            choose the adapter's version automatically.
 
-                        .. versionadded:: 2.15
+                        .. 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,19 @@ 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.
+        ..
+            This is intended for Opentrons internal use only and is not a guaranteed API.
+
+        :meta private:
+        """
+        return self._core.define_liquid_class(name=name)
 
     @property
     @requires_version(2, 5)
@@ -1364,13 +1393,13 @@ class ProtocolContext(CommandPublisher):
         version: Optional[int] = None,
     ) -> Labware:
         """
-        Load a stack of Lids onto a valid Deck Location or Adapter.
+        Load a stack of Opentrons Tough Auto-Sealing Lids onto a valid deck location or adapter.
 
         :param str load_name: A string to use for looking up a lid definition.
-            You can find the ``load_name`` for any standard lid on the Opentrons
+            You can find the ``load_name`` for any compatible lid on the Opentrons
             `Labware Library <https://labware.opentrons.com>`_.
         :param location: Either a :ref:`deck slot <deck-slots>`,
-            like ``1``, ``"1"``, or ``"D1"``, or the a valid Opentrons Adapter.
+            like ``1``, ``"1"``, or ``"D1"``, or a valid Opentrons Adapter.
         :param int quantity: The quantity of lids to be loaded in the stack.
         :param adapter: An adapter to load the lid stack on top of. Accepts the same
             values as the ``load_name`` parameter of :py:meth:`.load_adapter`. The
@@ -1391,7 +1420,10 @@ class ProtocolContext(CommandPublisher):
             leave this unspecified to let ``load_lid_stack()`` choose a version
             automatically.
 
-        :return:  The initialized and loaded labware object representing the Lid Stack.
+        :return:  The initialized and loaded labware object representing the lid stack.
+
+        .. versionadded:: 2.23
+
         """
         if self._api_version < validation.LID_STACK_VERSION_GATE:
             raise APIVersionError(
@@ -1441,6 +1473,116 @@ 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 compatible lid from a valid source to a new location. Can return a lid stack if one is created.
+
+        :param source_location: The lid's starting location. 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 to move the lid.
+
+                * 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.
+
+        .. versionadded:: 2.23
+
+        """
+        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 +1604,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"
 

opentrons/protocol_api/validation.py

@@ -14,13 +14,15 @@ from typing import (
 from math import isinf, isnan
 from typing_extensions import TypeGuard
 
-from opentrons_shared_data.labware.labware_definition import LabwareRole
-from opentrons_shared_data.pipette.types import PipetteNameType
+from opentrons_shared_data.labware.labware_definition import (
+    LabwareDefinition,
+    LabwareRole,
+)
+from opentrons_shared_data.pipette.types import PipetteNameType, PIPETTE_API_NAMES_MAP
 from opentrons_shared_data.robot.types import RobotType
 
 from opentrons.protocols.api_support.types import APIVersion, ThermocyclerStep
 from opentrons.protocols.api_support.util import APIVersionError
-from opentrons.protocols.models import LabwareDefinition
 from opentrons.protocols.advanced_control.transfers.common import TransferTipPolicyV2
 from opentrons.types import (
     Mount,
@@ -39,6 +41,7 @@ from opentrons.hardware_control.modules.types import (
     HeaterShakerModuleModel,
     MagneticBlockModel,
     AbsorbanceReaderModel,
+    FlexStackerModuleModel,
 )
 
 from .disposal_locations import TrashBin, WasteChute
@@ -56,29 +59,8 @@ _STAGING_DECK_SLOT_VERSION_GATE = APIVersion(2, 16)
 # The first APIVersion where Python protocols can load lids as stacks and treat them as attributes of a parent labware.
 LID_STACK_VERSION_GATE = APIVersion(2, 23)
 
-# Mapping of public Python Protocol API pipette load names
-# to names used by the internal Opentrons system
-_PIPETTE_NAMES_MAP = {
-    "p10_single": PipetteNameType.P10_SINGLE,
-    "p10_multi": PipetteNameType.P10_MULTI,
-    "p20_single_gen2": PipetteNameType.P20_SINGLE_GEN2,
-    "p20_multi_gen2": PipetteNameType.P20_MULTI_GEN2,
-    "p50_single": PipetteNameType.P50_SINGLE,
-    "p50_multi": PipetteNameType.P50_MULTI,
-    "p300_single": PipetteNameType.P300_SINGLE,
-    "p300_multi": PipetteNameType.P300_MULTI,
-    "p300_single_gen2": PipetteNameType.P300_SINGLE_GEN2,
-    "p300_multi_gen2": PipetteNameType.P300_MULTI_GEN2,
-    "p1000_single": PipetteNameType.P1000_SINGLE,
-    "p1000_single_gen2": PipetteNameType.P1000_SINGLE_GEN2,
-    "flex_1channel_50": PipetteNameType.P50_SINGLE_FLEX,
-    "flex_8channel_50": PipetteNameType.P50_MULTI_FLEX,
-    "flex_1channel_1000": PipetteNameType.P1000_SINGLE_FLEX,
-    "flex_8channel_1000": PipetteNameType.P1000_MULTI_FLEX,
-    "flex_8channel_1000_em": PipetteNameType.P1000_MULTI_EM,
-    "flex_96channel_1000": PipetteNameType.P1000_96,
-    "flex_96channel_200": PipetteNameType.P200_96,
-}
+# The first APIVersion where Python protocols can use the Flex Stacker module.
+FLEX_STACKER_VERSION_GATE = APIVersion(2, 23)
 
 
 class InvalidPipetteMountError(ValueError):
@@ -192,7 +174,7 @@ def ensure_pipette_name(pipette_name: str) -> PipetteNameType:
     pipette_name = ensure_lowercase_name(pipette_name)
 
     try:
-        return _PIPETTE_NAMES_MAP[pipette_name]
+        return PIPETTE_API_NAMES_MAP[pipette_name]
     except KeyError:
         raise ValueError(
             f"Cannot resolve {pipette_name} to pipette, must be given valid pipette name."
@@ -411,6 +393,7 @@ _MODULE_MODELS: Dict[str, ModuleModel] = {
     "heaterShakerModuleV1": HeaterShakerModuleModel.HEATER_SHAKER_V1,
     "magneticBlockV1": MagneticBlockModel.MAGNETIC_BLOCK_V1,
     "absorbanceReaderV1": AbsorbanceReaderModel.ABSORBANCE_READER_V1,
+    "flexStackerModuleV1": FlexStackerModuleModel.FLEX_STACKER_V1,
 }
 
 
@@ -644,6 +627,16 @@ def ensure_positive_float(value: Union[int, float]) -> float:
     return float_value
 
 
+def ensure_greater_than_zero_float(value: Union[int, float]) -> float:
+    """Ensure value is a positive and real float value."""
+    float_value = ensure_float(value)
+    if isnan(float_value) or isinf(float_value):
+        raise ValueError("Value must be a defined, non-infinite number.")
+    if float_value <= 0:
+        raise ValueError("Value must be a positive float greater than 0.")
+    return float_value
+
+
 def ensure_positive_int(value: int) -> int:
     """Ensure value is a positive integer."""
     if not isinstance(value, int):
@@ -711,20 +704,18 @@ def ensure_valid_flat_wells_list_for_transfer_v2(
         )
 
 
-def ensure_valid_tip_drop_location_for_transfer_v2(
-    tip_drop_location: Union[Location, Well, TrashBin, WasteChute]
-) -> Union[Location, Well, TrashBin, WasteChute]:
-    """Ensure that the tip drop location is valid for v2 transfer."""
+def ensure_valid_trash_location_for_transfer_v2(
+    trash_location: Union[Location, Well, TrashBin, WasteChute]
+) -> Union[Location, TrashBin, WasteChute]:
+    """Ensure that the trash location is valid for v2 transfer."""
     from .labware import Well
 
-    if (
-        isinstance(tip_drop_location, Well)
-        or isinstance(tip_drop_location, TrashBin)
-        or isinstance(tip_drop_location, WasteChute)
-    ):
-        return tip_drop_location
-    elif isinstance(tip_drop_location, Location):
-        _, maybe_well = tip_drop_location.labware.get_parent_labware_and_well()
+    if isinstance(trash_location, TrashBin) or isinstance(trash_location, WasteChute):
+        return trash_location
+    elif isinstance(trash_location, Well):
+        return trash_location.top()
+    elif isinstance(trash_location, Location):
+        _, maybe_well = trash_location.labware.get_parent_labware_and_well()
 
         if maybe_well is None:
             raise TypeError(
@@ -734,11 +725,30 @@ def ensure_valid_tip_drop_location_for_transfer_v2(
                 " since that is where a tip is dropped."
                 " However, the given location doesn't refer to any well."
             )
-        return tip_drop_location
+        return trash_location
     else:
         raise TypeError(
             f"If specified, location should be an instance of"
             f" `types.Location` (e.g. the return value from `Well.top()`)"
             f" or `Well` (e.g. `reservoir.wells()[0]`) or an instance of `TrashBin` or `WasteChute`."
-            f" However, it is '{tip_drop_location}'."
+            f" However, it is '{trash_location}'."
         )
+
+
+def convert_flex_stacker_load_slot(slot_name: StagingSlotName) -> DeckSlotName:
+    """
+    Ensure a Flex Stacker load location to a deck slot location.
+
+    Args:
+        slot_name: The input staging slot location.
+
+    Returns:
+        A `DeckSlotName` on the deck.
+    """
+    _map = {
+        StagingSlotName.SLOT_A4: DeckSlotName.SLOT_A3,
+        StagingSlotName.SLOT_B4: DeckSlotName.SLOT_B3,
+        StagingSlotName.SLOT_C4: DeckSlotName.SLOT_C3,
+        StagingSlotName.SLOT_D4: DeckSlotName.SLOT_D3,
+    }
+    return _map[slot_name]

opentrons/protocol_engine/__init__.py

@@ -26,21 +26,30 @@ from .plugins import AbstractPlugin
 
 from .types import (
     LabwareOffset,
+    LegacyLabwareOffsetCreate,
     LabwareOffsetCreate,
     LabwareOffsetVector,
-    LabwareOffsetLocation,
+    LegacyLabwareOffsetLocation,
+    LabwareOffsetLocationSequence,
+    OnLabwareOffsetLocationSequenceComponent,
+    OnModuleOffsetLocationSequenceComponent,
+    OnAddressableAreaOffsetLocationSequenceComponent,
+    LabwareOffsetLocationSequenceComponents,
     LabwareMovementStrategy,
     AddressableOffsetVector,
     DeckPoint,
     DeckType,
     DeckSlotLocation,
+    InStackerHopperLocation,
     ModuleLocation,
     OnLabwareLocation,
     AddressableAreaLocation,
     OFF_DECK_LOCATION,
+    SYSTEM_LOCATION,
     Dimensions,
     EngineStatus,
     LabwareLocation,
+    LoadableLabwareLocation,
     NonStackedLocation,
     LoadedLabware,
     LoadedModule,
@@ -94,8 +103,15 @@ __all__ = [
     # public value interfaces and models
     "LabwareOffset",
     "LabwareOffsetCreate",
+    "LegacyLabwareOffsetCreate",
+    "LabwareOffsetLocationSequence",
     "LabwareOffsetVector",
-    "LabwareOffsetLocation",
+    "OnLabwareOffsetLocationSequenceComponent",
+    "OnModuleOffsetLocationSequenceComponent",
+    "OnAddressableAreaOffsetLocationSequenceComponent",
+    "LabwareOffsetLocationSequenceComponents",
+    "LegacyLabwareOffsetCreate",
+    "LegacyLabwareOffsetLocation",
     "LabwareMovementStrategy",
     "AddressableOffsetVector",
     "DeckSlotLocation",
@@ -104,10 +120,13 @@ __all__ = [
     "ModuleLocation",
     "OnLabwareLocation",
     "AddressableAreaLocation",
+    "InStackerHopperLocation",
     "OFF_DECK_LOCATION",
+    "SYSTEM_LOCATION",
     "Dimensions",
     "EngineStatus",
     "LabwareLocation",
+    "LoadableLabwareLocation",
     "NonStackedLocation",
     "LoadedLabware",
     "LoadedModule",

opentrons/protocol_engine/actions/actions.py

@@ -8,12 +8,12 @@ from datetime import datetime
 from enum import Enum
 from typing import List, Optional, Union
 
-from opentrons.protocols.models import LabwareDefinition
+from opentrons_shared_data.errors import EnumeratedError
+from opentrons_shared_data.labware.labware_definition import LabwareDefinition
+
 from opentrons.hardware_control.types import DoorState
 from opentrons.hardware_control.modules import LiveData
 
-from opentrons_shared_data.errors import EnumeratedError
-
 from ..commands import (
     Command,
     CommandCreate,
@@ -23,7 +23,7 @@ from ..error_recovery_policy import ErrorRecoveryPolicy, ErrorRecoveryType
 from ..notes.notes import CommandNote
 from ..state.update_types import StateUpdate
 from ..types import (
-    LabwareOffsetCreate,
+    LabwareOffsetCreateInternal,
     ModuleDefinition,
     Liquid,
     DeckConfigurationType,
@@ -206,7 +206,7 @@ class AddLabwareOffsetAction:
 
     labware_offset_id: str
     created_at: datetime
-    request: LabwareOffsetCreate
+    request: LabwareOffsetCreateInternal
 
 
 @dataclasses.dataclass(frozen=True)

opentrons/protocol_engine/clients/sync_client.py

@@ -107,6 +107,12 @@ class SyncClient:
     ) -> commands.LoadLiquidClassResult:
         pass
 
+    @overload
+    def execute_command_without_recovery(
+        self, params: commands.GetNextTipParams
+    ) -> commands.GetNextTipResult:
+        pass
+
     def execute_command_without_recovery(
         self, params: commands.CommandParams
     ) -> commands.CommandResult: