feat(api): Alias del deck[...] to moveLabware(..., OFF_DECK) (#13239)

Author: SyntaxColoring

api/src/opentrons/protocol_api/core/engine/protocol.py

@@ -256,17 +256,20 @@ def move_labware(
             DeckSlotName, LabwareCore, ModuleCore, NonConnectedModuleCore, OffDeckType
         ],
         use_gripper: bool,
+        pause_for_manual_move: bool,
         pick_up_offset: Optional[Tuple[float, float, float]],
         drop_offset: Optional[Tuple[float, float, float]],
     ) -> None:
         """Move the given labware to a new location."""
         to_location = self._convert_labware_location(location=new_location)
 
-        strategy = (
-            LabwareMovementStrategy.USING_GRIPPER
-            if use_gripper
-            else LabwareMovementStrategy.MANUAL_MOVE_WITH_PAUSE
-        )
+        if use_gripper:
+            strategy = LabwareMovementStrategy.USING_GRIPPER
+        elif pause_for_manual_move:
+            strategy = LabwareMovementStrategy.MANUAL_MOVE_WITH_PAUSE
+        else:
+            strategy = LabwareMovementStrategy.MANUAL_MOVE_WITHOUT_PAUSE
+
         _pick_up_offset = (
             LabwareOffsetVector(
                 x=pick_up_offset[0], y=pick_up_offset[1], z=pick_up_offset[2]

api/src/opentrons/protocol_api/core/legacy/legacy_protocol_core.py

@@ -254,6 +254,7 @@ def move_labware(
             OffDeckType,
         ],
         use_gripper: bool,
+        pause_for_manual_move: bool,
         pick_up_offset: Optional[Tuple[float, float, float]],
         drop_offset: Optional[Tuple[float, float, float]],
     ) -> None:

api/src/opentrons/protocol_api/core/module.py

@@ -36,6 +36,7 @@ def get_deck_slot(self) -> DeckSlotName:
     def get_deck_slot_id(self) -> str:
         """Get the module's deck slot in a robot accurate format."""
 
+    @abstractmethod
     def get_display_name(self) -> str:
         """Get the module's display name."""
 

api/src/opentrons/protocol_api/core/protocol.py

@@ -86,6 +86,7 @@ def move_labware(
         labware_core: LabwareCoreType,
         new_location: Union[DeckSlotName, LabwareCoreType, ModuleCoreType, OffDeckType],
         use_gripper: bool,
+        pause_for_manual_move: bool,
         pick_up_offset: Optional[Tuple[float, float, float]],
         drop_offset: Optional[Tuple[float, float, float]],
     ) -> None:

api/src/opentrons/protocol_api/deck.py

@@ -6,13 +6,17 @@
 
 from opentrons.motion_planning import adjacent_slots_getters
 from opentrons.protocols.api_support.types import APIVersion
+from opentrons.protocols.api_support.util import APIVersionError
 from opentrons.types import DeckLocation, DeckSlotName, Location, Point
 from opentrons_shared_data.robot.dev_types import RobotType
 
+
 from .core.common import ProtocolCore
 from .core.core_map import LoadedCoreMap
+from .core.module import AbstractModuleCore
 from .labware import Labware
 from .module_contexts import ModuleContext
+from ._types import OFF_DECK
 from . import validation
 
 
@@ -91,6 +95,44 @@ def __getitem__(self, key: DeckLocation) -> Optional[DeckItem]:
 
         return item
 
+    def __delitem__(self, key: DeckLocation) -> None:
+        if self._api_version == APIVersion(2, 14):
+            # __delitem__() support history:
+            #
+            # * PAPIv<=2.13 (non Protocol Engine): Yes, but that goes through a different Deck class
+            # * PAPIv2.14 (Protocol Engine): No
+            # * PAPIv2.15 (Protocol Engine): Yes
+            raise APIVersionError(
+                f"Deleting deck elements is not supported with apiLevel {self._api_version}."
+                f" Try increasing your apiLevel to {APIVersion(2, 15)}."
+            )
+
+        slot_name = _get_slot_name(
+            key, self._api_version, self._protocol_core.robot_type
+        )
+        item_core = self._protocol_core.get_slot_item(slot_name)
+
+        if item_core is None:
+            # No-op if trying to delete from an empty slot.
+            # This matches pre-Protocol-Engine (PAPIv<=2.13) behavior.
+            pass
+        elif isinstance(item_core, AbstractModuleCore):
+            # Protocol Engine does not support removing modules from the deck.
+            # This is a change from pre-Protocol-Engine (PAPIv<=2.13) behavior, unfortunately.
+            raise TypeError(
+                f"Slot {repr(key)} contains a module, {item_core.get_display_name()}."
+                f" You can only delete labware, not modules."
+            )
+        else:
+            self._protocol_core.move_labware(
+                item_core,
+                new_location=OFF_DECK,
+                use_gripper=False,
+                pause_for_manual_move=False,
+                pick_up_offset=None,
+                drop_offset=None,
+            )
+
     def __iter__(self) -> Iterator[str]:
         """Iterate through all deck slots."""
         return iter(self._slot_definitions_by_name)

api/src/opentrons/protocol_api/protocol_context.py

@@ -597,6 +597,7 @@ def move_labware(
             labware_core=labware._core,
             new_location=location,
             use_gripper=use_gripper,
+            pause_for_manual_move=True,
             pick_up_offset=_pick_up_offset,
             drop_offset=_drop_offset,
         )

api/tests/opentrons/protocol_api/core/engine/test_protocol_core.py

@@ -546,10 +546,12 @@ def test_load_adapter(
 
 
 @pytest.mark.parametrize(
-    argnames=["use_gripper", "expected_strategy"],
+    argnames=["use_gripper", "pause_for_manual_move", "expected_strategy"],
     argvalues=[
-        (True, LabwareMovementStrategy.USING_GRIPPER),
-        (False, LabwareMovementStrategy.MANUAL_MOVE_WITH_PAUSE),
+        (True, False, LabwareMovementStrategy.USING_GRIPPER),
+        (True, True, LabwareMovementStrategy.USING_GRIPPER),
+        (False, False, LabwareMovementStrategy.MANUAL_MOVE_WITHOUT_PAUSE),
+        (False, True, LabwareMovementStrategy.MANUAL_MOVE_WITH_PAUSE),
     ],
 )
 @pytest.mark.parametrize(
@@ -566,6 +568,7 @@ def test_move_labware(
     mock_engine_client: EngineClient,
     expected_strategy: LabwareMovementStrategy,
     use_gripper: bool,
+    pause_for_manual_move: bool,
     pick_up_offset: Optional[Tuple[float, float, float]],
     drop_offset: Optional[Tuple[float, float, float]],
 ) -> None:
@@ -580,6 +583,7 @@ def test_move_labware(
         labware_core=labware,
         new_location=DeckSlotName.SLOT_5,
         use_gripper=use_gripper,
+        pause_for_manual_move=pause_for_manual_move,
         pick_up_offset=pick_up_offset,
         drop_offset=drop_offset,
     )
@@ -618,6 +622,7 @@ def test_move_labware_on_non_connected_module(
         labware_core=labware,
         new_location=non_connected_module_core,
         use_gripper=False,
+        pause_for_manual_move=True,
         pick_up_offset=None,
         drop_offset=None,
     )
@@ -650,6 +655,7 @@ def test_move_labware_off_deck(
         labware_core=labware,
         new_location=OFF_DECK,
         use_gripper=False,
+        pause_for_manual_move=True,
         pick_up_offset=None,
         drop_offset=None,
     )

api/tests/opentrons/protocol_api/test_deck.py

@@ -9,9 +9,15 @@
 
 from opentrons.motion_planning import adjacent_slots_getters as mock_adjacent_slots
 from opentrons.protocols.api_support.types import APIVersion
-from opentrons.protocol_api.core.common import ProtocolCore, LabwareCore
+from opentrons.protocols.api_support.util import APIVersionError
+from opentrons.protocol_api.core.common import ProtocolCore, LabwareCore, ModuleCore
 from opentrons.protocol_api.core.core_map import LoadedCoreMap
-from opentrons.protocol_api import Deck, Labware, validation as mock_validation
+from opentrons.protocol_api import (
+    Deck,
+    Labware,
+    OFF_DECK,
+    validation as mock_validation,
+)
 from opentrons.protocol_api.deck import CalibrationPosition
 from opentrons.types import DeckSlotName, Point
 
@@ -135,6 +141,89 @@ def test_get_slot_item(
     assert subject[42] is mock_labware
 
 
+def test_delitem_aliases_to_move_labware(
+    decoy: Decoy,
+    mock_protocol_core: ProtocolCore,
+    api_version: APIVersion,
+    subject: Deck,
+) -> None:
+    """It should be equivalent to a manual labware move to off-deck, without pausing."""
+    mock_labware_core = decoy.mock(cls=LabwareCore)
+
+    decoy.when(mock_protocol_core.robot_type).then_return("OT-3 Standard")
+    decoy.when(
+        mock_validation.ensure_and_convert_deck_slot(42, api_version, "OT-3 Standard")
+    ).then_return(DeckSlotName.SLOT_2)
+    decoy.when(mock_protocol_core.get_slot_item(DeckSlotName.SLOT_2)).then_return(
+        mock_labware_core
+    )
+
+    del subject[42]
+
+    decoy.verify(
+        mock_protocol_core.move_labware(
+            mock_labware_core,
+            OFF_DECK,
+            use_gripper=False,
+            pause_for_manual_move=False,
+            pick_up_offset=None,
+            drop_offset=None,
+        )
+    )
+
+
+@pytest.mark.parametrize("api_version", [APIVersion(2, 14)])
+def test_delitem_raises_on_api_2_14(
+    subject: Deck,
+) -> None:
+    """It should raise on apiLevel 2.14."""
+    with pytest.raises(APIVersionError):
+        del subject[1]
+
+
+def test_delitem_noops_if_slot_is_empty(
+    decoy: Decoy,
+    mock_protocol_core: ProtocolCore,
+    api_version: APIVersion,
+    subject: Deck,
+) -> None:
+    """It should do nothing, and not raise anything, if you try to delete from an empty slot."""
+    decoy.when(mock_protocol_core.robot_type).then_return("OT-3 Standard")
+    decoy.when(
+        mock_validation.ensure_and_convert_deck_slot(1, api_version, "OT-3 Standard")
+    ).then_return(DeckSlotName.SLOT_1)
+    decoy.when(mock_protocol_core.get_slot_item(DeckSlotName.SLOT_1)).then_return(None)
+
+    del subject[1]
+
+
+def test_delitem_raises_if_slot_has_module(
+    decoy: Decoy,
+    mock_protocol_core: ProtocolCore,
+    api_version: APIVersion,
+    subject: Deck,
+) -> None:
+    """It should raise a descriptive error if you try to delete a module."""
+    decoy.when(mock_protocol_core.robot_type).then_return("OT-3 Standard")
+    mock_module_core = decoy.mock(cls=ModuleCore)
+    decoy.when(mock_module_core.get_display_name()).then_return("<module display name>")
+    decoy.when(
+        mock_validation.ensure_and_convert_deck_slot(2, api_version, "OT-3 Standard")
+    ).then_return(DeckSlotName.SLOT_2)
+    decoy.when(mock_protocol_core.get_slot_item(DeckSlotName.SLOT_2)).then_return(
+        mock_module_core
+    )
+
+    with pytest.raises(
+        TypeError,
+        match=(
+            "Slot 2 contains a module, <module display name>."
+            " You can only delete labware, not modules."
+        ),
+    ):
+        del subject[2]
+
+
 @pytest.mark.parametrize(
     "deck_definition",
     [

api/tests/opentrons/protocol_api/test_protocol_context.py

@@ -517,6 +517,7 @@ def test_move_labware_to_slot(
             labware_core=mock_labware_core,
             new_location=DeckSlotName.SLOT_1,
             use_gripper=False,
+            pause_for_manual_move=True,
             pick_up_offset=None,
             drop_offset=(1, 2, 3),
         )
@@ -556,6 +557,7 @@ def test_move_labware_to_module(
             labware_core=mock_labware_core,
             new_location=mock_module_core,
             use_gripper=False,
+            pause_for_manual_move=True,
             pick_up_offset=None,
             drop_offset=None,
         )
@@ -586,6 +588,7 @@ def test_move_labware_off_deck(
             labware_core=mock_labware_core,
             new_location=OFF_DECK,
             use_gripper=False,
+            pause_for_manual_move=True,
             pick_up_offset=None,
             drop_offset=None,
         )