opentrons 8.6.0a1__py3-none-any.whl

opentrons/protocol_engine/__init__.py

@@ -0,0 +1,155 @@
+"""Protocol engine module.
+
+The protocol_engine module contains the logic necessary to take a stream of
+protocol commands, issued by some arbitrary protocol runner, and turn it into
+protocol state and side-effects like robot movements.
+
+The main interface is the `ProtocolEngine` class.
+"""
+
+from .protocol_engine import ProtocolEngine
+from .errors import ProtocolEngineError, ErrorOccurrence
+from .notes import CommandNote
+from .commands import (
+    Command,
+    CommandParams,
+    CommandCreate,
+    CommandStatus,
+    CommandType,
+    CommandIntent,
+)
+from .state.state import State, StateView
+from .state.state_summary import StateSummary
+from .state.commands import CommandSlice, CommandErrorSlice, CommandPointer
+from .state.config import Config
+from .plugins import AbstractPlugin
+
+from .types import (
+    LabwareOffset,
+    LegacyLabwareOffsetCreate,
+    LabwareOffsetCreate,
+    LabwareOffsetVector,
+    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,
+    LoadedPipette,
+    MotorAxis,
+    WellLocation,
+    LiquidHandlingWellLocation,
+    PickUpTipWellLocation,
+    DropTipWellLocation,
+    WellOrigin,
+    DropTipWellOrigin,
+    PickUpTipWellOrigin,
+    WellOffset,
+    ModuleModel,
+    ModuleDefinition,
+    Liquid,
+    LiquidClassRecord,
+    LiquidClassRecordWithId,
+    AllNozzleLayoutConfiguration,
+    SingleNozzleLayoutConfiguration,
+    RowNozzleLayoutConfiguration,
+    ColumnNozzleLayoutConfiguration,
+    QuadrantNozzleLayoutConfiguration,
+)
+
+
+__all__ = [
+    # main factory and interface exports
+    "create_protocol_engine",
+    "create_protocol_engine_in_thread",
+    "ProtocolEngine",
+    "StateSummary",
+    "Config",
+    # error types
+    "ProtocolEngineError",
+    "ErrorOccurrence",
+    # top level command unions and values
+    "Command",
+    "CommandParams",
+    "CommandCreate",
+    "CommandStatus",
+    "CommandType",
+    "CommandIntent",
+    "CommandNote",
+    # state interfaces and models
+    "State",
+    "StateView",
+    "CommandSlice",
+    "CommandErrorSlice",
+    "CommandPointer",
+    # public value interfaces and models
+    "LabwareOffset",
+    "LabwareOffsetCreate",
+    "LegacyLabwareOffsetCreate",
+    "LabwareOffsetLocationSequence",
+    "LabwareOffsetVector",
+    "OnLabwareOffsetLocationSequenceComponent",
+    "OnModuleOffsetLocationSequenceComponent",
+    "OnAddressableAreaOffsetLocationSequenceComponent",
+    "LabwareOffsetLocationSequenceComponents",
+    "LegacyLabwareOffsetCreate",
+    "LegacyLabwareOffsetLocation",
+    "LabwareMovementStrategy",
+    "AddressableOffsetVector",
+    "DeckSlotLocation",
+    "DeckPoint",
+    "DeckType",
+    "ModuleLocation",
+    "OnLabwareLocation",
+    "AddressableAreaLocation",
+    "InStackerHopperLocation",
+    "OFF_DECK_LOCATION",
+    "SYSTEM_LOCATION",
+    "Dimensions",
+    "EngineStatus",
+    "LabwareLocation",
+    "LoadableLabwareLocation",
+    "NonStackedLocation",
+    "LoadedLabware",
+    "LoadedModule",
+    "LoadedPipette",
+    "MotorAxis",
+    "WellLocation",
+    "LiquidHandlingWellLocation",
+    "PickUpTipWellLocation",
+    "DropTipWellLocation",
+    "WellOrigin",
+    "DropTipWellOrigin",
+    "PickUpTipWellOrigin",
+    "WellOffset",
+    "ModuleModel",
+    "ModuleDefinition",
+    "Liquid",
+    "LiquidClassRecord",
+    "LiquidClassRecordWithId",
+    "AllNozzleLayoutConfiguration",
+    "SingleNozzleLayoutConfiguration",
+    "RowNozzleLayoutConfiguration",
+    "ColumnNozzleLayoutConfiguration",
+    "QuadrantNozzleLayoutConfiguration",
+    # plugins
+    "AbstractPlugin",
+]

opentrons/protocol_engine/actions/__init__.py

@@ -0,0 +1,65 @@
+"""ProtocolEngine action interfaces.
+
+Actions are the driver of state changes in the ProtocolEngine.
+"""
+
+from .action_dispatcher import ActionDispatcher
+from .action_handler import ActionHandler
+from .actions import (
+    Action,
+    PlayAction,
+    PauseAction,
+    PauseSource,
+    StopAction,
+    ResumeFromRecoveryAction,
+    FinishAction,
+    HardwareStoppedAction,
+    QueueCommandAction,
+    RunCommandAction,
+    SucceedCommandAction,
+    FailCommandAction,
+    AddLabwareOffsetAction,
+    AddLabwareDefinitionAction,
+    AddLiquidAction,
+    SetDeckConfigurationAction,
+    AddAddressableAreaAction,
+    AddModuleAction,
+    FinishErrorDetails,
+    DoorChangeAction,
+    ResetTipsAction,
+    SetPipetteMovementSpeedAction,
+)
+from .get_state_update import get_state_updates
+
+__all__ = [
+    # action pipeline interface
+    "ActionDispatcher",
+    # action reaction interface
+    "ActionHandler",
+    # action values
+    "Action",
+    "PlayAction",
+    "PauseAction",
+    "StopAction",
+    "ResumeFromRecoveryAction",
+    "FinishAction",
+    "HardwareStoppedAction",
+    "QueueCommandAction",
+    "RunCommandAction",
+    "SucceedCommandAction",
+    "FailCommandAction",
+    "AddLabwareOffsetAction",
+    "AddLabwareDefinitionAction",
+    "AddLiquidAction",
+    "SetDeckConfigurationAction",
+    "AddAddressableAreaAction",
+    "AddModuleAction",
+    "DoorChangeAction",
+    "ResetTipsAction",
+    "SetPipetteMovementSpeedAction",
+    # action payload values
+    "PauseSource",
+    "FinishErrorDetails",
+    # helper functions
+    "get_state_updates",
+]

opentrons/protocol_engine/actions/action_dispatcher.py

@@ -0,0 +1,30 @@
+"""Action pipeline module."""
+from typing import List
+
+from .action_handler import ActionHandler
+from .actions import Action
+
+
+class ActionDispatcher:
+    """A pipeline, with an endpoint, that actions can be dispatched into."""
+
+    def __init__(self, sink: ActionHandler) -> None:
+        """Initialize the ActionDispatcher and action pipeline.
+
+        Arguments:
+            sink: The action handler that all actions in the pipeline
+                are sent to.
+        """
+        self._handlers: List[ActionHandler] = []
+        self._sink = sink
+
+    def add_handler(self, handler: ActionHandler) -> None:
+        """Add an action handler to the pipeline before the sink."""
+        self._handlers.append(handler)
+
+    def dispatch(self, action: Action) -> None:
+        """Dispatch an action into the pipeline."""
+        for handler in self._handlers:
+            handler.handle_action(action)
+
+        self._sink.handle_action(action)

opentrons/protocol_engine/actions/action_handler.py

@@ -0,0 +1,13 @@
+"""Abstract interfaces for engine plugins."""
+from abc import ABC, abstractmethod
+
+from .actions import Action
+
+
+class ActionHandler(ABC):
+    """An abstract interface for an object that reacts to actions."""
+
+    @abstractmethod
+    def handle_action(self, action: Action) -> None:
+        """React to a state-change action."""
+        ...

opentrons/protocol_engine/actions/actions.py

@@ -0,0 +1,302 @@
+"""State store actions.
+
+Actions can be passed to the ActionDispatcher, where they will trigger
+reactions in objects that subscribe to the pipeline, like the StateStore.
+"""
+import dataclasses
+from datetime import datetime
+from enum import Enum
+from typing import List, Optional, Union
+
+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 ..commands import (
+    Command,
+    CommandCreate,
+    CommandDefinedErrorData,
+)
+from ..error_recovery_policy import ErrorRecoveryPolicy, ErrorRecoveryType
+from ..notes.notes import CommandNote
+from ..state.update_types import StateUpdate
+from ..types import (
+    LabwareOffsetCreateInternal,
+    ModuleDefinition,
+    Liquid,
+    DeckConfigurationType,
+)
+
+
+@dataclasses.dataclass(frozen=True)
+class PlayAction:
+    """Start or resume processing commands in the engine."""
+
+    requested_at: datetime
+
+
+class PauseSource(str, Enum):
+    """The source of a PauseAction.
+
+    Attributes:
+        CLIENT: the pause came externally, from the engine client.
+        PROTOCOL: the pause came from the protocol itself.
+    """
+
+    CLIENT = "client"
+    PROTOCOL = "protocol"
+
+
+@dataclasses.dataclass(frozen=True)
+class PauseAction:
+    """Pause processing commands in the engine."""
+
+    source: PauseSource
+
+
+@dataclasses.dataclass(frozen=True)
+class StopAction:
+    """Request engine execution to stop soon."""
+
+    from_estop: bool = False
+
+
+@dataclasses.dataclass(frozen=True)
+class ResumeFromRecoveryAction:
+    """See `ProtocolEngine.resume_from_recovery()`."""
+
+    state_update: StateUpdate
+
+
+@dataclasses.dataclass(frozen=True)
+class FinishErrorDetails:
+    """Error details for the payload of a FinishAction or HardwareStoppedAction."""
+
+    error: Exception
+    error_id: str
+    created_at: datetime
+
+
+@dataclasses.dataclass(frozen=True)
+class FinishAction:
+    """Gracefully stop processing commands in the engine."""
+
+    set_run_status: bool = True
+    """Whether to set the engine status depending on `error_details`.
+
+    If True, the engine status will be marked `succeeded` or `failed`, depending on `error_details`.
+    If False, the engine status will be marked `stopped`.
+    """
+
+    error_details: Optional[FinishErrorDetails] = None
+    """The fatal error that caused the run to fail."""
+
+
+@dataclasses.dataclass(frozen=True)
+class HardwareStoppedAction:
+    """An action dispatched after hardware has been stopped for good, for this engine instance."""
+
+    completed_at: datetime
+
+    finish_error_details: Optional[FinishErrorDetails]
+    """The error that happened while doing post-run finish steps (homing and dropping tips)."""
+
+
+@dataclasses.dataclass(frozen=True)
+class DoorChangeAction:
+    """Handle events coming in from hardware control."""
+
+    door_state: DoorState
+    module_serial: str | None = None
+
+
+@dataclasses.dataclass(frozen=True)
+class QueueCommandAction:
+    """Add a command request to the queue."""
+
+    command_id: str
+    created_at: datetime
+    request: CommandCreate
+    request_hash: Optional[str]
+    failed_command_id: Optional[str] = None
+
+
+@dataclasses.dataclass(frozen=True)
+class RunCommandAction:
+    """Mark a given command as running.
+
+    At the time of dispatching this action, the command must be queued,
+    and no other command may be running.
+    """
+
+    command_id: str
+    started_at: datetime
+
+
+@dataclasses.dataclass(frozen=True)
+class SucceedCommandAction:
+    """Mark a given command as succeeded.
+
+    At the time of dispatching this action, the command must be running.
+    """
+
+    command: Command
+    """The command in its new succeeded state."""
+
+    state_update: StateUpdate = dataclasses.field(
+        # todo(mm, 2024-08-26): This has a default only to make it easier to transition
+        # old tests while https://opentrons.atlassian.net/browse/EXEC-639 is in
+        # progress. Make this mandatory when that's completed.
+        default_factory=StateUpdate
+    )
+
+
+@dataclasses.dataclass(frozen=True)
+class FailCommandAction:
+    """Mark a given command as failed.
+
+    At the time of dispatching this action, the command must be running.
+    """
+
+    command_id: str
+    """The command to fail."""
+
+    error_id: str
+    """An ID to assign to the command's error.
+
+    Must be unique to this occurrence of the error.
+
+    todo(mm, 2024-05-13): This is redundant with `error` when it's a defined error.
+    """
+
+    failed_at: datetime
+    """When the command failed.
+
+    todo(mm, 2024-05-13): This is redundant with `error` when it's a defined error.
+    """
+
+    error: Union[CommandDefinedErrorData, EnumeratedError]
+    """The error that caused the command to fail.
+
+    If it was a defined error, this should be the `DefinedErrorData` that the command
+    returned.
+
+    If it was an undefined error, this should be the underlying exception
+    that caused the command to fail, represented as an `EnumeratedError`.
+    """
+
+    notes: List[CommandNote]
+    """Overwrite the command's `.notes` with these."""
+
+    type: ErrorRecoveryType
+    """How this error should be handled in the context of the overall run."""
+
+    # This is a quick hack so FailCommandAction handlers can get the params of the
+    # command that failed. We probably want this to be a new "failure details"
+    # object instead, similar to how succeeded commands can send a "private result"
+    # to Protocol Engine internals.
+    running_command: Command
+    """The command to fail, in its prior `running` state."""
+
+
+@dataclasses.dataclass(frozen=True)
+class AddLabwareOffsetAction:
+    """Add a labware offset, to apply to subsequent `LoadLabwareCommand`s."""
+
+    labware_offset_id: str
+    created_at: datetime
+    request: LabwareOffsetCreateInternal
+
+
+@dataclasses.dataclass(frozen=True)
+class AddLabwareDefinitionAction:
+    """Add a labware definition, to apply to subsequent `LoadLabwareCommand`s."""
+
+    definition: LabwareDefinition
+
+
+@dataclasses.dataclass(frozen=True)
+class AddLiquidAction:
+    """Add a liquid, to apply to subsequent `LoadLiquid`s."""
+
+    liquid: Liquid
+
+
+@dataclasses.dataclass(frozen=True)
+class SetDeckConfigurationAction:
+    """See `ProtocolEngine.set_deck_configuration()`."""
+
+    deck_configuration: Optional[DeckConfigurationType]
+
+
+@dataclasses.dataclass(frozen=True)
+class AddAddressableAreaAction:
+    """Add a single addressable area to state.
+
+    This differs from the deck configuration in SetDeckConfigurationAction which
+    sends over a mapping of cutout fixtures. This action will only load one addressable
+    area and that should be pre-validated before being sent via the action.
+    """
+
+    addressable_area_name: str
+
+
+@dataclasses.dataclass(frozen=True)
+class AddModuleAction:
+    """Add an attached module directly to state without a location."""
+
+    module_id: str
+    serial_number: str
+    definition: ModuleDefinition
+    module_live_data: LiveData
+
+
+@dataclasses.dataclass(frozen=True)
+class ResetTipsAction:
+    """Reset the tip tracking state of a given tip rack."""
+
+    labware_id: str
+
+
+@dataclasses.dataclass(frozen=True)
+class SetPipetteMovementSpeedAction:
+    """Set the speed of a pipette's X/Y/Z movements. Does not affect plunger speed.
+
+    None will use the hardware API's default.
+    """
+
+    pipette_id: str
+    speed: Optional[float]
+
+
+@dataclasses.dataclass(frozen=True)
+class SetErrorRecoveryPolicyAction:
+    """See `ProtocolEngine.set_error_recovery_policy()`."""
+
+    error_recovery_policy: ErrorRecoveryPolicy
+
+
+Action = Union[
+    PlayAction,
+    PauseAction,
+    StopAction,
+    ResumeFromRecoveryAction,
+    FinishAction,
+    HardwareStoppedAction,
+    DoorChangeAction,
+    QueueCommandAction,
+    RunCommandAction,
+    SucceedCommandAction,
+    FailCommandAction,
+    AddLabwareOffsetAction,
+    AddLabwareDefinitionAction,
+    AddModuleAction,
+    SetDeckConfigurationAction,
+    AddAddressableAreaAction,
+    AddLiquidAction,
+    ResetTipsAction,
+    SetPipetteMovementSpeedAction,
+    SetErrorRecoveryPolicyAction,
+]

opentrons/protocol_engine/actions/get_state_update.py

@@ -0,0 +1,38 @@
+# noqa: D100
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+from .actions import (
+    Action,
+    ResumeFromRecoveryAction,
+    SucceedCommandAction,
+    FailCommandAction,
+)
+from ..commands.command import DefinedErrorData
+from ..error_recovery_policy import ErrorRecoveryType
+
+if TYPE_CHECKING:
+    from ..state.update_types import StateUpdate
+
+
+def get_state_updates(action: Action) -> list[StateUpdate]:
+    """Extract all the StateUpdates that the StateStores should apply when they apply an action."""
+    if isinstance(action, SucceedCommandAction):
+        return [action.state_update]
+
+    elif isinstance(action, FailCommandAction) and isinstance(
+        action.error, DefinedErrorData
+    ):
+        if action.type == ErrorRecoveryType.ASSUME_FALSE_POSITIVE_AND_CONTINUE:
+            return [
+                action.error.state_update,
+                action.error.state_update_if_false_positive,
+            ]
+        else:
+            return [action.error.state_update]
+
+    elif isinstance(action, ResumeFromRecoveryAction):
+        return [action.state_update]
+
+    else:
+        return []

opentrons/protocol_engine/clients/__init__.py

@@ -0,0 +1,5 @@
+"""ProtocolEngine clients."""
+from .sync_client import SyncClient
+from .transports import ChildThreadTransport
+
+__all__ = ["SyncClient", "ChildThreadTransport"]