opentrons 8.1.0__py2.py3-none-any.whl → 8.2.0__py2.py3-none-any.whl

opentrons/protocol_engine/commands/command.py

@@ -3,8 +3,8 @@
 
 from __future__ import annotations
 
+import dataclasses
 from abc import ABC, abstractmethod
-from dataclasses import dataclass
 from datetime import datetime
 from enum import Enum
 from typing import (
@@ -21,6 +21,7 @@ from pydantic import BaseModel, Field
 from pydantic.generics import GenericModel
 
 from opentrons.hardware_control import HardwareControlAPI
+from opentrons.protocol_engine.state.update_types import StateUpdate
 
 from ..resources import ModelUtils
 from ..errors import ErrorOccurrence
@@ -29,7 +30,7 @@ from ..notes import CommandNote, CommandNoteAdder
 # Work around type-only circular dependencies.
 if TYPE_CHECKING:
     from .. import execution
-    from ..state import StateView
+    from ..state.state import StateView
 
 
 _ParamsT = TypeVar("_ParamsT", bound=BaseModel)
@@ -38,7 +39,6 @@ _ResultT = TypeVar("_ResultT", bound=BaseModel)
 _ResultT_co = TypeVar("_ResultT_co", bound=BaseModel, covariant=True)
 _ErrorT = TypeVar("_ErrorT", bound=ErrorOccurrence)
 _ErrorT_co = TypeVar("_ErrorT_co", bound=ErrorOccurrence, covariant=True)
-_PrivateResultT_co = TypeVar("_PrivateResultT_co", covariant=True)
 
 
 class CommandStatus(str, Enum):
@@ -106,19 +106,23 @@ class BaseCommandCreate(
     )
 
 
-@dataclass(frozen=True)
-class SuccessData(Generic[_ResultT_co, _PrivateResultT_co]):
+@dataclasses.dataclass(frozen=True)
+class SuccessData(Generic[_ResultT_co]):
     """Data from the successful completion of a command."""
 
     public: _ResultT_co
     """Public result data. Exposed over HTTP and stored in databases."""
 
-    private: _PrivateResultT_co
-    """Additional result data, only given to `opentrons.protocol_engine` internals."""
+    state_update: StateUpdate = dataclasses.field(
+        # todo(mm, 2024-08-22): Remove the default once all command implementations
+        # use this, to make it harder to forget in new command implementations.
+        default_factory=StateUpdate
+    )
+    """How the engine state should be updated to reflect this command success."""
 
 
-@dataclass(frozen=True)
-class DefinedErrorData(Generic[_ErrorT_co, _PrivateResultT_co]):
+@dataclasses.dataclass(frozen=True)
+class DefinedErrorData(Generic[_ErrorT_co]):
     """Data from a command that failed with a defined error.
 
     This should only be used for "defined" errors, not any error.
@@ -128,8 +132,16 @@ class DefinedErrorData(Generic[_ErrorT_co, _PrivateResultT_co]):
     public: _ErrorT_co
     """Public error data. Exposed over HTTP and stored in databases."""
 
-    private: _PrivateResultT_co
-    """Additional error data, only given to `opentrons.protocol_engine` internals."""
+    state_update: StateUpdate = dataclasses.field(
+        # todo(mm, 2024-08-22): Remove the default once all command implementations
+        # use this, to make it harder to forget in new command implementations.
+        default_factory=StateUpdate
+    )
+    """How the engine state should be updated to reflect this command failure."""
+
+    state_update_if_false_positive: StateUpdate = dataclasses.field(
+        default_factory=StateUpdate
+    )
 
 
 class BaseCommand(
@@ -173,7 +185,9 @@ class BaseCommand(
     )
     error: Union[
         _ErrorT,
-        # ErrorOccurrence here is for undefined errors not captured by _ErrorT.
+        # ErrorOccurrence here is a catch-all for undefined errors not captured by
+        # _ErrorT, or defined errors that don't parse into _ErrorT because, for example,
+        # they are from an older software version that was missing some fields.
         ErrorOccurrence,
         None,
     ] = Field(
@@ -219,13 +233,11 @@ class BaseCommand(
                     # Our _ImplementationCls must return public result data that can fit
                     # in our `result` field:
                     _ResultT,
-                    # But we don't care (here) what kind of private result data it returns:
-                    object,
                 ],
                 DefinedErrorData[
-                    # Likewise, for our `error` field:
+                    # Our _ImplementationCls must return public error data that can fit
+                    # in our `error` field:
                     _ErrorT,
-                    object,
                 ],
             ],
         ]
@@ -235,8 +247,8 @@ class BaseCommand(
 _ExecuteReturnT_co = TypeVar(
     "_ExecuteReturnT_co",
     bound=Union[
-        SuccessData[BaseModel, object],
-        DefinedErrorData[ErrorOccurrence, object],
+        SuccessData[BaseModel],
+        DefinedErrorData[ErrorOccurrence],
     ],
     covariant=True,
 )
@@ -258,6 +270,7 @@ class AbstractCommandImpl(
         state_view: StateView,
         hardware_api: HardwareControlAPI,
         equipment: execution.EquipmentHandler,
+        file_provider: execution.FileProvider,
         movement: execution.MovementHandler,
         gantry_mover: execution.GantryMover,
         labware_movement: execution.LabwareMovementHandler,

opentrons/protocol_engine/commands/command_unions.py

@@ -10,9 +10,8 @@ from opentrons.util.get_union_elements import get_union_elements
 from .command import DefinedErrorData
 from .pipetting_common import (
     OverpressureError,
-    OverpressureErrorInternalData,
     LiquidNotFoundError,
-    LiquidNotFoundErrorInternalData,
+    TipPhysicallyAttachedError,
 )
 
 from . import absorbance_reader
@@ -142,10 +141,10 @@ from .load_pipette import (
     LoadPipetteCreate,
     LoadPipetteResult,
     LoadPipetteCommandType,
-    LoadPipettePrivateResult,
 )
 
 from .move_labware import (
+    GripperMovementError,
     MoveLabware,
     MoveLabwareParams,
     MoveLabwareCreate,
@@ -216,7 +215,6 @@ from .pick_up_tip import (
     PickUpTipResult,
     PickUpTipCommandType,
     TipPhysicallyMissingError,
-    TipPhysicallyMissingErrorInternalData,
 )
 
 from .touch_tip import (
@@ -273,7 +271,6 @@ from .configure_for_volume import (
     ConfigureForVolumeCreate,
     ConfigureForVolumeResult,
     ConfigureForVolumeCommandType,
-    ConfigureForVolumePrivateResult,
 )
 
 from .prepare_to_aspirate import (
@@ -290,7 +287,6 @@ from .configure_nozzle_layout import (
     ConfigureNozzleLayoutParams,
     ConfigureNozzleLayoutResult,
     ConfigureNozzleLayoutCommandType,
-    ConfigureNozzleLayoutPrivateResult,
 )
 
 from .verify_tip_presence import (
@@ -382,8 +378,11 @@ Command = Annotated[
         thermocycler.OpenLid,
         thermocycler.CloseLid,
         thermocycler.RunProfile,
+        thermocycler.RunExtendedProfile,
+        absorbance_reader.CloseLid,
+        absorbance_reader.OpenLid,
         absorbance_reader.Initialize,
-        absorbance_reader.MeasureAbsorbance,
+        absorbance_reader.ReadAbsorbance,
         calibration.CalibrateGripper,
         calibration.CalibratePipette,
         calibration.CalibrateModule,
@@ -392,6 +391,8 @@ Command = Annotated[
         unsafe.UnsafeDropTipInPlace,
         unsafe.UpdatePositionEstimators,
         unsafe.UnsafeEngageAxes,
+        unsafe.UnsafeUngripLabware,
+        unsafe.UnsafePlaceLabware,
     ],
     Field(discriminator="commandType"),
 ]
@@ -455,8 +456,11 @@ CommandParams = Union[
     thermocycler.OpenLidParams,
     thermocycler.CloseLidParams,
     thermocycler.RunProfileParams,
+    thermocycler.RunExtendedProfileParams,
+    absorbance_reader.CloseLidParams,
+    absorbance_reader.OpenLidParams,
     absorbance_reader.InitializeParams,
-    absorbance_reader.MeasureAbsorbanceParams,
+    absorbance_reader.ReadAbsorbanceParams,
     calibration.CalibrateGripperParams,
     calibration.CalibratePipetteParams,
     calibration.CalibrateModuleParams,
@@ -465,6 +469,8 @@ CommandParams = Union[
     unsafe.UnsafeDropTipInPlaceParams,
     unsafe.UpdatePositionEstimatorsParams,
     unsafe.UnsafeEngageAxesParams,
+    unsafe.UnsafeUngripLabwareParams,
+    unsafe.UnsafePlaceLabwareParams,
 ]
 
 CommandType = Union[
@@ -526,8 +532,11 @@ CommandType = Union[
     thermocycler.OpenLidCommandType,
     thermocycler.CloseLidCommandType,
     thermocycler.RunProfileCommandType,
+    thermocycler.RunExtendedProfileCommandType,
+    absorbance_reader.CloseLidCommandType,
+    absorbance_reader.OpenLidCommandType,
     absorbance_reader.InitializeCommandType,
-    absorbance_reader.MeasureAbsorbanceCommandType,
+    absorbance_reader.ReadAbsorbanceCommandType,
     calibration.CalibrateGripperCommandType,
     calibration.CalibratePipetteCommandType,
     calibration.CalibrateModuleCommandType,
@@ -536,6 +545,8 @@ CommandType = Union[
     unsafe.UnsafeDropTipInPlaceCommandType,
     unsafe.UpdatePositionEstimatorsCommandType,
     unsafe.UnsafeEngageAxesCommandType,
+    unsafe.UnsafeUngripLabwareCommandType,
+    unsafe.UnsafePlaceLabwareCommandType,
 ]
 
 CommandCreate = Annotated[
@@ -598,8 +609,11 @@ CommandCreate = Annotated[
         thermocycler.OpenLidCreate,
         thermocycler.CloseLidCreate,
         thermocycler.RunProfileCreate,
+        thermocycler.RunExtendedProfileCreate,
+        absorbance_reader.CloseLidCreate,
+        absorbance_reader.OpenLidCreate,
         absorbance_reader.InitializeCreate,
-        absorbance_reader.MeasureAbsorbanceCreate,
+        absorbance_reader.ReadAbsorbanceCreate,
         calibration.CalibrateGripperCreate,
         calibration.CalibratePipetteCreate,
         calibration.CalibrateModuleCreate,
@@ -608,6 +622,8 @@ CommandCreate = Annotated[
         unsafe.UnsafeDropTipInPlaceCreate,
         unsafe.UpdatePositionEstimatorsCreate,
         unsafe.UnsafeEngageAxesCreate,
+        unsafe.UnsafeUngripLabwareCreate,
+        unsafe.UnsafePlaceLabwareCreate,
     ],
     Field(discriminator="commandType"),
 ]
@@ -671,8 +687,11 @@ CommandResult = Union[
     thermocycler.OpenLidResult,
     thermocycler.CloseLidResult,
     thermocycler.RunProfileResult,
+    thermocycler.RunExtendedProfileResult,
+    absorbance_reader.CloseLidResult,
+    absorbance_reader.OpenLidResult,
     absorbance_reader.InitializeResult,
-    absorbance_reader.MeasureAbsorbanceResult,
+    absorbance_reader.ReadAbsorbanceResult,
     calibration.CalibrateGripperResult,
     calibration.CalibratePipetteResult,
     calibration.CalibrateModuleResult,
@@ -681,24 +700,18 @@ CommandResult = Union[
     unsafe.UnsafeDropTipInPlaceResult,
     unsafe.UpdatePositionEstimatorsResult,
     unsafe.UnsafeEngageAxesResult,
+    unsafe.UnsafeUngripLabwareResult,
+    unsafe.UnsafePlaceLabwareResult,
 ]
 
-# todo(mm, 2024-06-12): Ideally, command return types would have specific
-# CommandPrivateResults paired with specific CommandResults. For example,
-# a TouchTipResult can never be paired with a LoadPipettePrivateResult in practice,
-# and ideally our types would reflect that.
-CommandPrivateResult = Union[
-    None,
-    LoadPipettePrivateResult,
-    ConfigureForVolumePrivateResult,
-    ConfigureNozzleLayoutPrivateResult,
-]
 
 # All `DefinedErrorData`s that implementations will actually return in practice.
 CommandDefinedErrorData = Union[
-    DefinedErrorData[TipPhysicallyMissingError, TipPhysicallyMissingErrorInternalData],
-    DefinedErrorData[OverpressureError, OverpressureErrorInternalData],
-    DefinedErrorData[LiquidNotFoundError, LiquidNotFoundErrorInternalData],
+    DefinedErrorData[TipPhysicallyMissingError],
+    DefinedErrorData[TipPhysicallyAttachedError],
+    DefinedErrorData[OverpressureError],
+    DefinedErrorData[LiquidNotFoundError],
+    DefinedErrorData[GripperMovementError],
 ]
 
 

opentrons/protocol_engine/commands/comment.py

@@ -24,16 +24,18 @@ class CommentResult(BaseModel):
 
 
 class CommentImplementation(
-    AbstractCommandImpl[CommentParams, SuccessData[CommentResult, None]]
+    AbstractCommandImpl[CommentParams, SuccessData[CommentResult]]
 ):
     """Comment command implementation."""
 
     def __init__(self, **kwargs: object) -> None:
         pass
 
-    async def execute(self, params: CommentParams) -> SuccessData[CommentResult, None]:
+    async def execute(self, params: CommentParams) -> SuccessData[CommentResult]:
         """No operation taken other than capturing message in command."""
-        return SuccessData(public=CommentResult(), private=None)
+        return SuccessData(
+            public=CommentResult(),
+        )
 
 
 class Comment(BaseCommand[CommentParams, CommentResult, ErrorOccurrence]):

opentrons/protocol_engine/commands/configure_for_volume.py

@@ -7,7 +7,7 @@ from typing_extensions import Literal
 from .pipetting_common import PipetteIdMixin
 from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
 from ..errors.error_occurrence import ErrorOccurrence
-from .configuring_common import PipetteConfigUpdateResultMixin
+from ..state.update_types import StateUpdate
 
 if TYPE_CHECKING:
     from ..execution import EquipmentHandler
@@ -34,12 +34,6 @@ class ConfigureForVolumeParams(PipetteIdMixin):
     )
 
 
-class ConfigureForVolumePrivateResult(PipetteConfigUpdateResultMixin):
-    """Result sent to the store but not serialized."""
-
-    pass
-
-
 class ConfigureForVolumeResult(BaseModel):
     """Result data from execution of an ConfigureForVolume command."""
 
@@ -49,7 +43,7 @@ class ConfigureForVolumeResult(BaseModel):
 class ConfigureForVolumeImplementation(
     AbstractCommandImpl[
         ConfigureForVolumeParams,
-        SuccessData[ConfigureForVolumeResult, ConfigureForVolumePrivateResult],
+        SuccessData[ConfigureForVolumeResult],
     ]
 ):
     """Configure for volume command implementation."""
@@ -59,7 +53,7 @@ class ConfigureForVolumeImplementation(
 
     async def execute(
         self, params: ConfigureForVolumeParams
-    ) -> SuccessData[ConfigureForVolumeResult, ConfigureForVolumePrivateResult]:
+    ) -> SuccessData[ConfigureForVolumeResult]:
         """Check that requested pipette can be configured for the given volume."""
         pipette_result = await self._equipment.configure_for_volume(
             pipette_id=params.pipetteId,
@@ -67,13 +61,16 @@ class ConfigureForVolumeImplementation(
             tip_overlap_version=params.tipOverlapNotAfterVersion,
         )
 
+        state_update = StateUpdate()
+        state_update.update_pipette_config(
+            pipette_id=pipette_result.pipette_id,
+            config=pipette_result.static_config,
+            serial_number=pipette_result.serial_number,
+        )
+
         return SuccessData(
             public=ConfigureForVolumeResult(),
-            private=ConfigureForVolumePrivateResult(
-                pipette_id=pipette_result.pipette_id,
-                serial_number=pipette_result.serial_number,
-                config=pipette_result.static_config,
-            ),
+            state_update=state_update,
         )
 
 

opentrons/protocol_engine/commands/configure_nozzle_layout.py

@@ -1,5 +1,6 @@
 """Configure nozzle layout command request, result, and implementation models."""
 from __future__ import annotations
+from opentrons.protocol_engine.state.update_types import StateUpdate
 from pydantic import BaseModel
 from typing import TYPE_CHECKING, Optional, Type, Union
 from typing_extensions import Literal
@@ -9,9 +10,6 @@ from .pipetting_common import (
 )
 from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
 from ..errors.error_occurrence import ErrorOccurrence
-from .configuring_common import (
-    PipetteNozzleLayoutResultMixin,
-)
 from ..types import (
     AllNozzleLayoutConfiguration,
     SingleNozzleLayoutConfiguration,
@@ -39,12 +37,6 @@ class ConfigureNozzleLayoutParams(PipetteIdMixin):
     ]
 
 
-class ConfigureNozzleLayoutPrivateResult(PipetteNozzleLayoutResultMixin):
-    """Result sent to the store but not serialized."""
-
-    pass
-
-
 class ConfigureNozzleLayoutResult(BaseModel):
     """Result data from execution of an configureNozzleLayout command."""
 
@@ -54,7 +46,7 @@ class ConfigureNozzleLayoutResult(BaseModel):
 class ConfigureNozzleLayoutImplementation(
     AbstractCommandImpl[
         ConfigureNozzleLayoutParams,
-        SuccessData[ConfigureNozzleLayoutResult, ConfigureNozzleLayoutPrivateResult],
+        SuccessData[ConfigureNozzleLayoutResult],
     ]
 ):
     """Configure nozzle layout command implementation."""
@@ -67,7 +59,7 @@ class ConfigureNozzleLayoutImplementation(
 
     async def execute(
         self, params: ConfigureNozzleLayoutParams
-    ) -> SuccessData[ConfigureNozzleLayoutResult, ConfigureNozzleLayoutPrivateResult]:
+    ) -> SuccessData[ConfigureNozzleLayoutResult]:
         """Check that requested pipette can support the requested nozzle layout."""
         primary_nozzle = params.configurationParams.dict().get("primaryNozzle")
         front_right_nozzle = params.configurationParams.dict().get("frontRightNozzle")
@@ -85,12 +77,14 @@ class ConfigureNozzleLayoutImplementation(
             **nozzle_params,
         )
 
+        update_state = StateUpdate()
+        update_state.update_pipette_nozzle(
+            pipette_id=params.pipetteId, nozzle_map=nozzle_map
+        )
+
         return SuccessData(
             public=ConfigureNozzleLayoutResult(),
-            private=ConfigureNozzleLayoutPrivateResult(
-                pipette_id=params.pipetteId,
-                nozzle_map=nozzle_map,
-            ),
+            state_update=update_state,
         )
 
 

opentrons/protocol_engine/commands/custom.py

@@ -40,16 +40,18 @@ class CustomResult(BaseModel):
 
 
 class CustomImplementation(
-    AbstractCommandImpl[CustomParams, SuccessData[CustomResult, None]]
+    AbstractCommandImpl[CustomParams, SuccessData[CustomResult]]
 ):
     """Custom command implementation."""
 
     # TODO(mm, 2022-11-09): figure out how a plugin can specify a custom command
     # implementation. For now, always no-op, so we can use custom commands as containers
     # for legacy RPC (pre-ProtocolEngine) payloads.
-    async def execute(self, params: CustomParams) -> SuccessData[CustomResult, None]:
+    async def execute(self, params: CustomParams) -> SuccessData[CustomResult]:
         """A custom command does nothing when executed directly."""
-        return SuccessData(public=CustomResult.construct(), private=None)
+        return SuccessData(
+            public=CustomResult.construct(),
+        )
 
 
 class Custom(BaseCommand[CustomParams, CustomResult, ErrorOccurrence]):

opentrons/protocol_engine/commands/dispense.py

@@ -8,15 +8,15 @@ from opentrons_shared_data.errors.exceptions import PipetteOverpressureError
 from pydantic import Field
 
 from ..types import DeckPoint
+from ..state.update_types import StateUpdate, CLEAR
 from .pipetting_common import (
     PipetteIdMixin,
     DispenseVolumeMixin,
     FlowRateMixin,
-    WellLocationMixin,
+    LiquidHandlingWellLocationMixin,
     BaseLiquidHandlingResult,
     DestinationPositionResult,
     OverpressureError,
-    OverpressureErrorInternalData,
 )
 from .command import (
     AbstractCommandImpl,
@@ -30,13 +30,14 @@ from ..errors.error_occurrence import ErrorOccurrence
 if TYPE_CHECKING:
     from ..execution import MovementHandler, PipettingHandler
     from ..resources import ModelUtils
+    from ..state.state import StateView
 
 
 DispenseCommandType = Literal["dispense"]
 
 
 class DispenseParams(
-    PipetteIdMixin, DispenseVolumeMixin, FlowRateMixin, WellLocationMixin
+    PipetteIdMixin, DispenseVolumeMixin, FlowRateMixin, LiquidHandlingWellLocationMixin
 ):
     """Payload required to dispense to a specific well."""
 
@@ -53,8 +54,8 @@ class DispenseResult(BaseLiquidHandlingResult, DestinationPositionResult):
 
 
 _ExecuteReturn = Union[
-    SuccessData[DispenseResult, None],
-    DefinedErrorData[OverpressureError, OverpressureErrorInternalData],
+    SuccessData[DispenseResult],
+    DefinedErrorData[OverpressureError],
 ]
 
 
@@ -63,31 +64,54 @@ class DispenseImplementation(AbstractCommandImpl[DispenseParams, _ExecuteReturn]
 
     def __init__(
         self,
+        state_view: StateView,
         movement: MovementHandler,
         pipetting: PipettingHandler,
         model_utils: ModelUtils,
         **kwargs: object,
     ) -> None:
+        self._state_view = state_view
         self._movement = movement
         self._pipetting = pipetting
         self._model_utils = model_utils
 
     async def execute(self, params: DispenseParams) -> _ExecuteReturn:
         """Move to and dispense to the requested well."""
+        state_update = StateUpdate()
+        well_location = params.wellLocation
+        labware_id = params.labwareId
+        well_name = params.wellName
+        volume = params.volume
+
+        # TODO(pbm, 10-15-24): call self._state_view.geometry.validate_dispense_volume_into_well()
+
         position = await self._movement.move_to_well(
             pipette_id=params.pipetteId,
-            labware_id=params.labwareId,
-            well_name=params.wellName,
-            well_location=params.wellLocation,
+            labware_id=labware_id,
+            well_name=well_name,
+            well_location=well_location,
         )
+        deck_point = DeckPoint.construct(x=position.x, y=position.y, z=position.z)
+        state_update.set_pipette_location(
+            pipette_id=params.pipetteId,
+            new_labware_id=labware_id,
+            new_well_name=well_name,
+            new_deck_point=deck_point,
+        )
+
         try:
             volume = await self._pipetting.dispense_in_place(
                 pipette_id=params.pipetteId,
-                volume=params.volume,
+                volume=volume,
                 flow_rate=params.flowRate,
                 push_out=params.pushOut,
             )
         except PipetteOverpressureError as e:
+            state_update.set_liquid_operated(
+                labware_id=labware_id,
+                well_name=well_name,
+                volume_added=CLEAR,
+            )
             return DefinedErrorData(
                 public=OverpressureError(
                     id=self._model_utils.generate_id(),
@@ -101,23 +125,21 @@ class DispenseImplementation(AbstractCommandImpl[DispenseParams, _ExecuteReturn]
                     ],
                     errorInfo={"retryLocation": (position.x, position.y, position.z)},
                 ),
-                private=OverpressureErrorInternalData(
-                    position=DeckPoint.construct(
-                        x=position.x, y=position.y, z=position.z
-                    )
-                ),
+                state_update=state_update,
             )
         else:
+            state_update.set_liquid_operated(
+                labware_id=labware_id,
+                well_name=well_name,
+                volume_added=volume,
+            )
             return SuccessData(
-                public=DispenseResult(
-                    volume=volume,
-                    position=DeckPoint(x=position.x, y=position.y, z=position.z),
-                ),
-                private=None,
+                public=DispenseResult(volume=volume, position=deck_point),
+                state_update=state_update,
             )
 
 
-class Dispense(BaseCommand[DispenseParams, DispenseResult, ErrorOccurrence]):
+class Dispense(BaseCommand[DispenseParams, DispenseResult, OverpressureError]):
     """Dispense command model."""
 
     commandType: DispenseCommandType = "dispense"