opentrons 8.6.0a1__py3-none-any.whl

opentrons/protocol_engine/labware_offset_standardization.py

@@ -0,0 +1,194 @@
+"""Convert labware offset creation requests and stored elements between legacy and new."""
+
+from opentrons_shared_data.robot.types import RobotType
+from opentrons_shared_data.deck.types import DeckDefinitionV5
+from .errors import (
+    OffsetLocationInvalidError,
+    FixtureDoesNotExistError,
+)
+from .types import (
+    LabwareOffsetCreate,
+    LegacyLabwareOffsetCreate,
+    LabwareOffsetCreateInternal,
+    LegacyLabwareOffsetLocation,
+    LabwareOffsetLocationSequence,
+    OnLabwareOffsetLocationSequenceComponent,
+    OnAddressableAreaOffsetLocationSequenceComponent,
+    OnModuleOffsetLocationSequenceComponent,
+    ModuleModel,
+)
+from .resources import deck_configuration_provider
+
+
+def standardize_labware_offset_create(
+    request: LabwareOffsetCreate | LegacyLabwareOffsetCreate,
+    robot_type: RobotType,
+    deck_definition: DeckDefinitionV5,
+) -> LabwareOffsetCreateInternal:
+    """Turn a union of old and new labware offset create requests into a new one."""
+    location_sequence, legacy_location = _locations_for_create(
+        request, robot_type, deck_definition
+    )
+    return LabwareOffsetCreateInternal(
+        definitionUri=request.definitionUri,
+        locationSequence=location_sequence,
+        legacyLocation=legacy_location,
+        vector=request.vector,
+    )
+
+
+def legacy_offset_location_to_offset_location_sequence(
+    location: LegacyLabwareOffsetLocation, deck_definition: DeckDefinitionV5
+) -> LabwareOffsetLocationSequence:
+    """Convert a legacy location to a new-style sequence."""
+    sequence: LabwareOffsetLocationSequence = []
+    if location.definitionUri:
+        sequence.append(
+            OnLabwareOffsetLocationSequenceComponent(labwareUri=location.definitionUri)
+        )
+    if location.moduleModel:
+        sequence.append(
+            OnModuleOffsetLocationSequenceComponent(moduleModel=location.moduleModel)
+        )
+        cutout_id = deck_configuration_provider.get_cutout_id_by_deck_slot_name(
+            location.slotName
+        )
+
+        # Given a module model, try to figure out the equivalent cutout fixture.
+        #
+        # The Thermocycler is special. A single Thermocycler is represented in a deck
+        # configuration as two separate cutout fixtures, because it spans two separate
+        # cutouts. This makes it the only module whose module model string does not map
+        # 1:1 with a cutout fixture ID string.
+        #
+        # TODO(mm, 2025-04-11): This is fragile, and the failure mode when it does the
+        # wrong thing can mean labware offsets don't apply, which is pretty bad. We
+        # either need a more explicit module<->cutout-fixture mapping, or we need to
+        # avoid this mapping entirely.
+        if (
+            # Check for v2 specifically because v1 is OT-2-only and OT-2s don't have
+            # modules in their deck definitions; and v3 does not exist at the time of writing.
+            location.moduleModel
+            == ModuleModel.THERMOCYCLER_MODULE_V2
+        ):
+            possible_cutout_fixture_id = "thermocyclerModuleV2Front"
+        else:
+            possible_cutout_fixture_id = location.moduleModel.value
+
+        try:
+            addressable_area = deck_configuration_provider.get_labware_hosting_addressable_area_name_for_cutout_and_cutout_fixture(
+                cutout_id, possible_cutout_fixture_id, deck_definition
+            )
+            sequence.append(
+                OnAddressableAreaOffsetLocationSequenceComponent(
+                    addressableAreaName=addressable_area
+                )
+            )
+        except FixtureDoesNotExistError:
+            # this is an OT-2 (or this module isn't supported in the deck definition) and we should use a
+            # slot addressable area name
+            sequence.append(
+                OnAddressableAreaOffsetLocationSequenceComponent(
+                    addressableAreaName=location.slotName.value
+                )
+            )
+
+    else:
+        # Slight hack: we should have a more formal association here. However, since the slot
+        # name is already standardized, and since the addressable areas for slots are just the
+        # name of the slots, we can rely on this.
+        sequence.append(
+            OnAddressableAreaOffsetLocationSequenceComponent(
+                addressableAreaName=location.slotName.value
+            )
+        )
+    return sequence
+
+
+def _offset_location_sequence_head_to_labware_and_module(
+    location_sequence: LabwareOffsetLocationSequence,
+) -> tuple[ModuleModel | None, str | None]:
+    labware_uri: str | None = None
+    module_model: ModuleModel | None = None
+    for location in location_sequence:
+        if isinstance(location, OnAddressableAreaOffsetLocationSequenceComponent):
+            raise OffsetLocationInvalidError(
+                "Addressable areas may only be the final element of an offset location."
+            )
+        elif isinstance(location, OnLabwareOffsetLocationSequenceComponent):
+            if labware_uri is not None:
+                # We only take the first location
+                continue
+            if module_model is not None:
+                # Labware can't be underneath modules
+                raise OffsetLocationInvalidError(
+                    "Labware must not be underneath a module."
+                )
+            labware_uri = location.labwareUri
+        elif isinstance(location, OnModuleOffsetLocationSequenceComponent):
+            if module_model is not None:
+                # Bad, somebody put more than one module in here
+                raise OffsetLocationInvalidError(
+                    "Only one module location may exist in an offset location."
+                )
+            module_model = location.moduleModel
+        else:
+            raise OffsetLocationInvalidError(
+                f"Invalid location component in offset location: {repr(location)}"
+            )
+    return module_model, labware_uri
+
+
+def _offset_location_sequence_to_legacy_offset_location(
+    location_sequence: LabwareOffsetLocationSequence, deck_definition: DeckDefinitionV5
+) -> LegacyLabwareOffsetLocation:
+    if len(location_sequence) == 0:
+        raise OffsetLocationInvalidError(
+            "Offset locations must contain at least one component."
+        )
+    last_element = location_sequence[-1]
+    if not isinstance(last_element, OnAddressableAreaOffsetLocationSequenceComponent):
+        raise OffsetLocationInvalidError(
+            "Offset locations must end with an addressable area."
+        )
+    module_model, labware_uri = _offset_location_sequence_head_to_labware_and_module(
+        location_sequence[:-1]
+    )
+    (
+        cutout_id,
+        _cutout_fixtures,
+    ) = deck_configuration_provider.get_potential_cutout_fixtures(
+        last_element.addressableAreaName, deck_definition
+    )
+    slot_name = deck_configuration_provider.get_deck_slot_for_cutout_id(cutout_id)
+    return LegacyLabwareOffsetLocation(
+        slotName=slot_name, moduleModel=module_model, definitionUri=labware_uri
+    )
+
+
+def _locations_for_create(
+    request: LabwareOffsetCreate | LegacyLabwareOffsetCreate,
+    robot_type: RobotType,
+    deck_definition: DeckDefinitionV5,
+) -> tuple[LabwareOffsetLocationSequence, LegacyLabwareOffsetLocation]:
+    if isinstance(request, LabwareOffsetCreate):
+        return (
+            request.locationSequence,
+            _offset_location_sequence_to_legacy_offset_location(
+                request.locationSequence, deck_definition
+            ),
+        )
+    else:
+        normalized = request.location.model_copy(
+            update={
+                "slotName": request.location.slotName.to_equivalent_for_robot_type(
+                    robot_type
+                )
+            }
+        )
+        return (
+            legacy_offset_location_to_offset_location_sequence(
+                normalized, deck_definition
+            ),
+            normalized,
+        )

opentrons/protocol_engine/notes/__init__.py

@@ -0,0 +1,17 @@
+"""Protocol engine notes module."""
+
+from .notes import (
+    NoteKind,
+    CommandNote,
+    CommandNoteAdder,
+    CommandNoteTracker,
+    make_error_recovery_debug_note,
+)
+
+__all__ = [
+    "NoteKind",
+    "CommandNote",
+    "CommandNoteAdder",
+    "CommandNoteTracker",
+    "make_error_recovery_debug_note",
+]

opentrons/protocol_engine/notes/notes.py

@@ -0,0 +1,59 @@
+"""Definitions of data and interface shapes for notes."""
+from typing import Union, Literal, Protocol, List, TYPE_CHECKING
+from pydantic import BaseModel, Field
+
+if TYPE_CHECKING:
+    from opentrons.protocol_engine.error_recovery_policy import ErrorRecoveryType
+
+NoteKind = Union[Literal["warning", "information"], str]
+
+
+class CommandNote(BaseModel):
+    """A note about a command's execution or dispatch."""
+
+    noteKind: NoteKind = Field(
+        ...,
+        description="The kind of note this is. Only the literal possibilities should be"
+        " relied upon programmatically.",
+    )
+    shortMessage: str = Field(
+        ...,
+        description="The accompanying human-readable short message (suitable for display in a single line)",
+    )
+    longMessage: str = Field(
+        ...,
+        description="A longer message that may contain newlines and formatting characters describing the note.",
+    )
+    source: str = Field(
+        ..., description="An identifier for the party that created the note"
+    )
+
+
+def make_error_recovery_debug_note(type: "ErrorRecoveryType") -> CommandNote:
+    """Return a note for debugging error recovery.
+
+    This is intended to be read by developers and support people, not computers.
+    """
+    message = f"Handling this command failure with {type.name}."
+    return CommandNote.model_construct(
+        noteKind="debugErrorRecovery",
+        shortMessage=message,
+        longMessage=message,
+        source="execution",
+    )
+
+
+class CommandNoteAdder(Protocol):
+    """The shape of a function that something can use to add a command note."""
+
+    def __call__(self, note: CommandNote) -> None:
+        """When called, this function should add the passed Note to some list."""
+        ...
+
+
+class CommandNoteTracker(CommandNoteAdder, Protocol):
+    """The shape of a class that can track notes."""
+
+    def get_notes(self) -> List[CommandNote]:
+        """When called, should return all notes previously added with __call__."""
+        ...

opentrons/protocol_engine/plugins.py

@@ -0,0 +1,104 @@
+"""Protocol engine plugin interface."""
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import List
+from typing_extensions import final
+
+from .actions import Action, ActionDispatcher, ActionHandler
+from .state.state import StateView
+
+
+class AbstractPlugin(ActionHandler, ABC):
+    """An ProtocolEngine plugin to customize engine behavior.
+
+    A plugin may customize behavior in one of two ways:
+
+    1. It can react to actions as they flow through the action pipeline,
+       before they hit the StateStore.
+    2. It can dispatch new actions into the pipeline.
+    """
+
+    @final
+    @property
+    def state(self) -> StateView:
+        """Get the current ProtocolEngine state."""
+        return self._state
+
+    @final
+    def dispatch(self, action: Action) -> None:
+        """Dispatch an action into the action pipeline.
+
+        Arguments:
+            action: A new ProtocolEngine action to send into the pipeline.
+                This action will flow through all plugins, including
+                this one, so be careful to avoid infinite loops. In general,
+                do not dispatch an action your plugin will react to.
+        """
+        return self._action_dispatcher.dispatch(action)
+
+    def setup(self) -> None:
+        """Run any necessary setup steps prior to plugin usage."""
+        ...
+
+    async def teardown(self) -> None:
+        """Run any necessary teardown steps once the engine is stopped."""
+        ...
+
+    @abstractmethod
+    def handle_action(self, action: Action) -> None:
+        """React to an action going through the pipeline.
+
+        When reacting to an action, `self.state` will not yet
+        reflect the change represented by the action, because
+        plugins receive actions before the StateStore.
+
+        Arguments:
+            action: An action that has been dispatched into the pipeline
+                that this plugin may react to.
+        """
+        ...
+
+    # NOTE: using a "protected" method allows mypy to infer the types
+    # of private properties `_state` and `_action_dispatcher` without
+    # declaring them on the class
+    @final
+    def _configure(
+        self,
+        state: StateView,
+        action_dispatcher: ActionDispatcher,
+    ) -> None:
+        """Insert a StateView and ActionDispatcher into the plugin.
+
+        This is a protected method that should only be called internally
+        by the ProtocolEngine during plugin setup.
+        """
+        self._state = state
+        self._action_dispatcher = action_dispatcher
+
+
+class PluginStarter:
+    """Configure, setup, and tear down engine plugins."""
+
+    def __init__(
+        self,
+        state: StateView,
+        action_dispatcher: ActionDispatcher,
+    ) -> None:
+        """Create a PluginStarter interface with access to its dependencies."""
+        self._state = state
+        self._action_dispatcher = action_dispatcher
+        self._plugins: List[AbstractPlugin] = []
+
+    def start(self, plugin: AbstractPlugin) -> None:
+        """Configure a given plugin and add it to the dispatch pipeline."""
+        plugin._configure(state=self._state, action_dispatcher=self._action_dispatcher)
+        self._plugins.append(plugin)
+        self._action_dispatcher.add_handler(plugin)
+        plugin.setup()
+
+    async def stop(self) -> None:
+        """Stop any configured plugins."""
+        for p in self._plugins:
+            await p.teardown()
+
+        self._plugins = []