opentrons 8.6.0__py3-none-any.whl

opentrons/protocol_engine/execution/__init__.py

@@ -0,0 +1,50 @@
+"""Command execution module."""
+
+from .command_executor import CommandExecutor
+from .create_queue_worker import create_queue_worker
+from .equipment import (
+    EquipmentHandler,
+    LoadedLabwareData,
+    LoadedPipetteData,
+    LoadedModuleData,
+    LoadedConfigureForVolumeData,
+    ReloadedLabwareData,
+)
+from .movement import MovementHandler
+from .gantry_mover import GantryMover
+from .labware_movement import LabwareMovementHandler
+from .pipetting import PipettingHandler
+from .tip_handler import TipHandler
+from .queue_worker import QueueWorker
+from .rail_lights import RailLightsHandler
+from .run_control import RunControlHandler
+from .hardware_stopper import HardwareStopper
+from .door_watcher import DoorWatcher
+from .status_bar import StatusBarHandler
+from ..resources.file_provider import FileProvider
+
+# .thermocycler_movement_flagger omitted from package's public interface.
+
+
+__all__ = [
+    "CommandExecutor",
+    "create_queue_worker",
+    "EquipmentHandler",
+    "LoadedLabwareData",
+    "ReloadedLabwareData",
+    "LoadedPipetteData",
+    "LoadedModuleData",
+    "LoadedConfigureForVolumeData",
+    "MovementHandler",
+    "GantryMover",
+    "PipettingHandler",
+    "TipHandler",
+    "LabwareMovementHandler",
+    "QueueWorker",
+    "RunControlHandler",
+    "HardwareStopper",
+    "DoorWatcher",
+    "RailLightsHandler",
+    "StatusBarHandler",
+    "FileProvider",
+]

opentrons/protocol_engine/execution/command_executor.py

@@ -0,0 +1,216 @@
+"""Command side-effect execution logic container."""
+import asyncio
+from logging import getLogger
+from typing import Optional, List, Protocol
+
+from opentrons.hardware_control import HardwareControlAPI
+
+from opentrons_shared_data.errors.exceptions import (
+    EStopActivatedError,
+    EnumeratedError,
+    PythonException,
+)
+
+from opentrons.protocol_engine.commands.command import SuccessData
+from opentrons.protocol_engine.notes import make_error_recovery_debug_note
+
+from ..state.state import StateStore
+from ..resources import ModelUtils, FileProvider
+from ..commands import CommandStatus
+from ..actions import (
+    ActionDispatcher,
+    RunCommandAction,
+    SucceedCommandAction,
+    FailCommandAction,
+)
+from ..errors import RunStoppedError
+from ..errors.exceptions import EStopActivatedError as PE_EStopActivatedError
+from ..notes import CommandNote, CommandNoteTracker
+from .equipment import EquipmentHandler
+from .movement import MovementHandler
+from .gantry_mover import GantryMover
+from .labware_movement import LabwareMovementHandler
+from .pipetting import PipettingHandler
+from .tip_handler import TipHandler
+from .run_control import RunControlHandler
+from .rail_lights import RailLightsHandler
+from .status_bar import StatusBarHandler
+
+
+log = getLogger(__name__)
+
+
+class CommandNoteTrackerProvider(Protocol):
+    """The correct shape for a function that provides a CommandNoteTracker.
+
+    This function will be called by the executor once for each call to execute().
+    It is mostly useful for testing harnesses.
+    """
+
+    def __call__(self) -> CommandNoteTracker:
+        """Provide a new CommandNoteTracker."""
+        ...
+
+
+class _NoteTracker(CommandNoteTracker):
+    def __init__(self) -> None:
+        self._notes: List[CommandNote] = []
+
+    def __call__(self, note: CommandNote) -> None:
+        self._notes.append(note)
+
+    def get_notes(self) -> List[CommandNote]:
+        return self._notes
+
+
+class CommandExecutor:
+    """CommandExecutor container class.
+
+    CommandExecutor manages various child handlers that define procedures to
+    execute the side-effects of commands.
+    """
+
+    def __init__(
+        self,
+        hardware_api: HardwareControlAPI,
+        file_provider: FileProvider,
+        state_store: StateStore,
+        action_dispatcher: ActionDispatcher,
+        equipment: EquipmentHandler,
+        movement: MovementHandler,
+        gantry_mover: GantryMover,
+        labware_movement: LabwareMovementHandler,
+        pipetting: PipettingHandler,
+        tip_handler: TipHandler,
+        run_control: RunControlHandler,
+        rail_lights: RailLightsHandler,
+        status_bar: StatusBarHandler,
+        model_utils: Optional[ModelUtils] = None,
+        command_note_tracker_provider: Optional[CommandNoteTrackerProvider] = None,
+    ) -> None:
+        """Initialize the CommandExecutor with access to its dependencies."""
+        self._hardware_api = hardware_api
+        self._file_provider = file_provider
+        self._state_store = state_store
+        self._action_dispatcher = action_dispatcher
+        self._equipment = equipment
+        self._movement = movement
+        self._gantry_mover = gantry_mover
+        self._labware_movement = labware_movement
+        self._pipetting = pipetting
+        self._tip_handler = tip_handler
+        self._run_control = run_control
+        self._rail_lights = rail_lights
+        self._model_utils = model_utils or ModelUtils()
+        self._status_bar = status_bar
+        self._command_note_tracker_provider = (
+            command_note_tracker_provider or _NoteTracker
+        )
+
+    async def execute(self, command_id: str) -> None:
+        """Run a given command's execution procedure.
+
+        Arguments:
+            command_id: The identifier of the command to execute. The
+                command itself will be looked up from state.
+        """
+        queued_command = self._state_store.commands.get(command_id=command_id)
+        note_tracker = self._command_note_tracker_provider()
+        command_impl = queued_command._ImplementationCls(
+            state_view=self._state_store,
+            hardware_api=self._hardware_api,
+            file_provider=self._file_provider,
+            equipment=self._equipment,
+            movement=self._movement,
+            gantry_mover=self._gantry_mover,
+            labware_movement=self._labware_movement,
+            pipetting=self._pipetting,
+            tip_handler=self._tip_handler,
+            run_control=self._run_control,
+            rail_lights=self._rail_lights,
+            model_utils=self._model_utils,
+            status_bar=self._status_bar,
+            command_note_adder=note_tracker,
+        )
+
+        started_at = self._model_utils.get_timestamp()
+
+        self._action_dispatcher.dispatch(
+            RunCommandAction(command_id=queued_command.id, started_at=started_at)
+        )
+        running_command = self._state_store.commands.get(queued_command.id)
+        error_recovery_policy = self._state_store.commands.get_error_recovery_policy()
+
+        log.debug(
+            f"Executing {running_command.id}, {running_command.commandType}, {running_command.params}"
+        )
+        try:
+            result = await command_impl.execute(
+                running_command.params  # type: ignore[arg-type]
+            )
+
+        except (Exception, asyncio.CancelledError) as error:
+            # The command encountered an undefined error.
+
+            log.warning(f"Execution of {running_command.id} failed", exc_info=error)
+            # TODO(mc, 2022-11-14): mark command as stopped rather than failed
+            # https://opentrons.atlassian.net/browse/RCORE-390
+            if isinstance(error, asyncio.CancelledError):
+                error = RunStoppedError("Run was cancelled")
+            elif isinstance(error, EStopActivatedError):
+                error = PE_EStopActivatedError(wrapping=[error])
+            elif not isinstance(error, EnumeratedError):
+                error = PythonException(error)
+
+            error_recovery_type = error_recovery_policy(
+                self._state_store.config,
+                running_command,
+                None,
+            )
+            note_tracker(make_error_recovery_debug_note(error_recovery_type))
+            self._action_dispatcher.dispatch(
+                FailCommandAction(
+                    error=error,
+                    command_id=running_command.id,
+                    running_command=running_command,
+                    error_id=self._model_utils.generate_id(),
+                    failed_at=self._model_utils.get_timestamp(),
+                    notes=note_tracker.get_notes(),
+                    type=error_recovery_type,
+                )
+            )
+
+        else:
+            if isinstance(result, SuccessData):
+                update = {
+                    "result": result.public,
+                    "status": CommandStatus.SUCCEEDED,
+                    "completedAt": self._model_utils.get_timestamp(),
+                    "notes": note_tracker.get_notes(),
+                }
+                succeeded_command = running_command.model_copy(update=update)
+                self._action_dispatcher.dispatch(
+                    SucceedCommandAction(
+                        command=succeeded_command,
+                        state_update=result.state_update,
+                    ),
+                )
+            else:
+                # The command encountered a defined error.
+                error_recovery_type = error_recovery_policy(
+                    self._state_store.config,
+                    running_command,
+                    result,
+                )
+                note_tracker(make_error_recovery_debug_note(error_recovery_type))
+                self._action_dispatcher.dispatch(
+                    FailCommandAction(
+                        error=result,
+                        command_id=running_command.id,
+                        running_command=running_command,
+                        error_id=result.public.id,
+                        failed_at=result.public.createdAt,
+                        notes=note_tracker.get_notes(),
+                        type=error_recovery_type,
+                    )
+                )

opentrons/protocol_engine/execution/create_queue_worker.py

@@ -0,0 +1,102 @@
+"""QueueWorker and dependency factory."""
+from typing import AsyncGenerator, Callable
+
+from opentrons.hardware_control import HardwareControlAPI
+from opentrons.protocol_engine.execution.rail_lights import RailLightsHandler
+
+from ..state.state import StateStore
+from ..actions import ActionDispatcher
+from ..resources import FileProvider
+from .equipment import EquipmentHandler
+from .movement import MovementHandler
+from .gantry_mover import create_gantry_mover
+from .labware_movement import LabwareMovementHandler
+from .pipetting import create_pipetting_handler
+from .tip_handler import create_tip_handler
+from .run_control import RunControlHandler
+from .command_executor import CommandExecutor
+from .queue_worker import QueueWorker
+from .status_bar import StatusBarHandler
+
+
+def create_queue_worker(
+    hardware_api: HardwareControlAPI,
+    file_provider: FileProvider,
+    state_store: StateStore,
+    action_dispatcher: ActionDispatcher,
+    command_generator: Callable[[], AsyncGenerator[str, None]],
+) -> QueueWorker:
+    """Create a ready-to-use QueueWorker instance.
+
+    Arguments:
+        hardware_api: Hardware control API to pass down to dependencies.
+        file_provider: Provides access to robot server file writing procedures for protocol output.
+        state_store: StateStore to pass down to dependencies.
+        action_dispatcher: ActionDispatcher to pass down to dependencies.
+        error_recovery_policy: ErrorRecoveryPolicy to pass down to dependencies.
+        command_generator: Command generator to get the next command to execute.
+    """
+    gantry_mover = create_gantry_mover(
+        hardware_api=hardware_api,
+        state_view=state_store,
+    )
+
+    equipment_handler = EquipmentHandler(
+        hardware_api=hardware_api,
+        state_store=state_store,
+    )
+
+    movement_handler = MovementHandler(
+        hardware_api=hardware_api,
+        state_store=state_store,
+        gantry_mover=gantry_mover,
+    )
+
+    labware_movement_handler = LabwareMovementHandler(
+        hardware_api=hardware_api,
+        state_store=state_store,
+        equipment=equipment_handler,
+        movement=movement_handler,
+    )
+
+    pipetting_handler = create_pipetting_handler(
+        hardware_api=hardware_api,
+        state_view=state_store,
+    )
+
+    tip_handler = create_tip_handler(
+        hardware_api=hardware_api,
+        state_view=state_store,
+    )
+
+    run_control_handler = RunControlHandler(
+        state_store=state_store,
+        action_dispatcher=action_dispatcher,
+    )
+    rail_lights_handler = RailLightsHandler(
+        hardware_api=hardware_api,
+    )
+
+    status_bar_handler = StatusBarHandler(hardware_api=hardware_api)
+
+    command_executor = CommandExecutor(
+        hardware_api=hardware_api,
+        file_provider=file_provider,
+        state_store=state_store,
+        action_dispatcher=action_dispatcher,
+        equipment=equipment_handler,
+        movement=movement_handler,
+        gantry_mover=gantry_mover,
+        labware_movement=labware_movement_handler,
+        pipetting=pipetting_handler,
+        tip_handler=tip_handler,
+        run_control=run_control_handler,
+        rail_lights=rail_lights_handler,
+        status_bar=status_bar_handler,
+    )
+
+    return QueueWorker(
+        state_store=state_store,
+        command_executor=command_executor,
+        command_generator=command_generator,
+    )

opentrons/protocol_engine/execution/door_watcher.py

@@ -0,0 +1,119 @@
+"""Forward door events from a `HardwareControlAPI` into a `ProtocolEngine`."""
+
+from __future__ import annotations
+
+from asyncio import get_running_loop, run_coroutine_threadsafe
+from typing import Callable, Optional
+
+from opentrons.hardware_control import HardwareControlAPI
+from opentrons.hardware_control.types import (
+    HardwareEvent,
+    DoorStateNotification,
+    DoorState,
+    PauseType,
+)
+
+from opentrons.protocol_engine.actions import ActionDispatcher, DoorChangeAction
+
+from ..state.state import StateStore
+
+
+_UnsubscribeCallback = Callable[[], None]
+
+
+class DoorWatcher:
+    """Forward door events from a `HardwareControlAPI` into a `ProtocolEngine`."""
+
+    def __init__(
+        self,
+        state_store: StateStore,
+        hardware_api: HardwareControlAPI,
+        action_dispatcher: ActionDispatcher,
+    ) -> None:
+        """Initialize the DoorWatcher.
+
+        Args:
+            state_store: The StateStore to check if the protocol queue is running.
+            hardware_api: The HardwareControlAPI whose events we will listen for.
+                Assumed to be running in a separate thread from action_dispatcher.
+            action_dispatcher: The ActionDispatcher to dispatch actions into.
+                Assumed to be owned by the same event loop that this
+                DoorWatcher was constructed in.
+        """
+        self._state_store = state_store
+        self._hardware_api = hardware_api
+        self._action_dispatcher = action_dispatcher
+        self._loop = get_running_loop()
+        self._unsubscribe_callback: Optional[_UnsubscribeCallback] = None
+
+    def start(self) -> None:
+        """Subscribe to hardware events and start forwarding them as PE actions."""
+        if self._unsubscribe_callback is None:
+            self._unsubscribe_callback = self._hardware_api.register_callback(
+                self._handle_hardware_door_event
+            )
+
+    def stop(self) -> None:
+        """Unsubscribe from hardware events.
+
+        Safe to call more than once.
+
+        Warning:
+            This method does not wait for pending event dispatches to complete.
+            Depending on timing, there may be straggler hardware events
+            that the `ActionDispatcher` will see even after this method returns.
+        """
+        if self._unsubscribe_callback is not None:
+            self._unsubscribe_callback()
+            self._unsubscribe_callback = None
+
+    def _handle_hardware_door_event(self, event: HardwareEvent) -> None:
+        """Handle a door state hardware event, ensuring thread-safety.
+
+        This is used as a callback for HardwareControlAPI.register_callback(),
+        and it's run inside the hardware thread.
+
+        This method will only return after the `ProtocolEngine` processes the event.
+        If something else is hogging the event loop thread that the `ProtocolEngine`
+        is running in, that may take a moment, and the hardware thread may be blocked.
+
+        This method will deadlock if it's ever run from the same thread that
+        owns the event loop that this DoorWatcher was constructed in.
+        """
+        if isinstance(event, DoorStateNotification):
+            coroutine = self._handle_hardware_door_event_async(event)
+            future = run_coroutine_threadsafe(coroutine, self._loop)
+            # Wait for the dispatch to complete before returning,
+            # which is important for ordering guarantees.
+            future.result()
+
+    async def _handle_hardware_door_event_async(
+        self, event: DoorStateNotification
+    ) -> None:
+        """Handle a door state hardware event.
+
+        This must run in the event loop that owns self._action_dispatcher, for safety.
+
+        Defined as an async function, so we can use this with
+        run_coroutine_threadsafe(), which lets us block until
+        the dispatch completes.
+        """
+        # Throw away this event if this instance has already been stop()'d.
+        # This can happen if the stop() happens after the HardwareAPI has sent the event,
+        # but before this handler has had its turn to run in the asyncio event loop.
+        already_stopped = self._unsubscribe_callback is None
+        if already_stopped:
+            return
+
+        action = DoorChangeAction(
+            door_state=event.new_state, module_serial=event.module_serial
+        )
+
+        if (
+            self._state_store.commands.get_is_running()
+            and action.door_state == DoorState.OPEN
+            and self._state_store.config.block_on_door_open
+        ):
+            self._hardware_api.pause(PauseType.PAUSE)
+
+        self._action_dispatcher.dispatch(action)