opentrons 8.6.0a1__py3-none-any.whl

opentrons/protocols/execution/dev_types.py

@@ -0,0 +1,181 @@
+from typing import Callable, Dict, TYPE_CHECKING, Any
+
+from typing_extensions import Protocol, TypedDict
+
+from opentrons_shared_data.protocol.types import (
+    BlowoutParams,
+    DelayParams,
+    PipetteAccessParams,
+    StandardLiquidHandlingParams,
+    TouchTipParams,
+    MoveToSlotParams,
+    TemperatureParams,
+    ModuleIDParams,
+    MagneticModuleEngageParams,
+    ThermocyclerRunProfileParams,
+    ThermocyclerSetTargetBlockParams,
+    MoveToWellParams,
+)
+
+if TYPE_CHECKING:
+    from opentrons.protocol_api.protocol_context import ProtocolContext
+    from opentrons.protocol_api.instrument_context import InstrumentContext
+    from opentrons.protocol_api.module_contexts import (
+        MagneticModuleContext,
+        ThermocyclerContext,
+        TemperatureModuleContext,
+    )
+    from opentrons.protocol_api.labware import Labware
+
+
+# this file defines types that require dev dependencies
+# and are only relevant for static typechecking.
+#
+#  - code should be written so that this file can fail to import
+#  - or the things defined in here can be None at execution time
+#  - only types that match the above criteria should be put here
+#  - please include this file as close to a leaf as possible
+
+if Protocol is not None:
+
+    class Dictable(Protocol):
+        """A protocol defining the _asdict interface to
+        classes generated from typing.NamedTuple, which cannot
+        be used as a type annotation because it is a type ctor
+        not a type (https://github.com/python/mypy/issues/3915)
+        """
+
+        async def _asdict(self) -> Dict[Any, Any]:
+            ...
+
+
+# using a lot of string literals here instead of the enum values from
+# opentrons_shared_data.protocol.constants because of
+# https://github.com/python/mypy/issues/4128
+PipetteDispatch = TypedDict(
+    "PipetteDispatch",
+    {
+        "delay": Callable[["ProtocolContext", "DelayParams"], None],
+        "blowout": Callable[
+            [Dict[str, "InstrumentContext"], Dict[str, "Labware"], "BlowoutParams"],
+            None,
+        ],
+        "pickUpTip": Callable[
+            [
+                Dict[str, "InstrumentContext"],
+                Dict[str, "Labware"],
+                "PipetteAccessParams",
+            ],
+            None,
+        ],
+        "dropTip": Callable[
+            [
+                Dict[str, "InstrumentContext"],
+                Dict[str, "Labware"],
+                "PipetteAccessParams",
+            ],
+            None,
+        ],
+        "aspirate": Callable[
+            [
+                Dict[str, "InstrumentContext"],
+                Dict[str, "Labware"],
+                "StandardLiquidHandlingParams",
+            ],
+            None,
+        ],
+        "dispense": Callable[
+            [
+                Dict[str, "InstrumentContext"],
+                Dict[str, "Labware"],
+                "StandardLiquidHandlingParams",
+            ],
+            None,
+        ],
+        "touchTip": Callable[
+            [Dict[str, "InstrumentContext"], Dict[str, "Labware"], "TouchTipParams"],
+            None,
+        ],
+        "moveToSlot": Callable[
+            ["ProtocolContext", Dict[str, "InstrumentContext"], "MoveToSlotParams"],
+            None,
+        ],
+        "moveToWell": Callable[
+            [Dict[str, "InstrumentContext"], Dict[str, "Labware"], "MoveToWellParams"],
+            None,
+        ],
+        "airGap": Callable[
+            [
+                Dict[str, "InstrumentContext"],
+                Dict[str, "Labware"],
+                "StandardLiquidHandlingParams",
+            ],
+            None,
+        ],
+    },
+    total=False,
+)
+
+
+JsonV4MagneticModuleDispatch = TypedDict(
+    "JsonV4MagneticModuleDispatch",
+    {
+        "magneticModule/engageMagnet": Callable[
+            ["MagneticModuleContext", "MagneticModuleEngageParams"], None
+        ],
+        "magneticModule/disengageMagnet": Callable[
+            ["MagneticModuleContext", "ModuleIDParams"], None
+        ],
+    },
+)
+
+JsonV4TemperatureModuleDispatch = TypedDict(
+    "JsonV4TemperatureModuleDispatch",
+    {
+        "temperatureModule/setTargetTemperature": Callable[
+            ["TemperatureModuleContext", "TemperatureParams"], None
+        ],
+        "temperatureModule/deactivate": Callable[
+            ["TemperatureModuleContext", "ModuleIDParams"], None
+        ],
+        "temperatureModule/awaitTemperature": Callable[
+            ["TemperatureModuleContext", "TemperatureParams"], None
+        ],
+    },
+)
+
+JsonV4ThermocyclerDispatch = TypedDict(
+    "JsonV4ThermocyclerDispatch",
+    {
+        "thermocycler/closeLid": Callable[
+            ["ThermocyclerContext", "ModuleIDParams"], None
+        ],
+        "thermocycler/openLid": Callable[
+            ["ThermocyclerContext", "ModuleIDParams"], None
+        ],
+        "thermocycler/deactivateBlock": Callable[
+            ["ThermocyclerContext", "ModuleIDParams"], None
+        ],
+        "thermocycler/deactivateLid": Callable[
+            ["ThermocyclerContext", "ModuleIDParams"], None
+        ],
+        "thermocycler/setTargetBlockTemperature": Callable[
+            ["ThermocyclerContext", "ThermocyclerSetTargetBlockParams"], None
+        ],
+        "thermocycler/setTargetLidTemperature": Callable[
+            ["ThermocyclerContext", "TemperatureParams"], None
+        ],
+        "thermocycler/runProfile": Callable[
+            ["ThermocyclerContext", "ThermocyclerRunProfileParams"], None
+        ],
+        "thermocycler/awaitBlockTemperature": Callable[
+            ["ThermocyclerContext", "TemperatureParams"], None
+        ],
+        "thermocycler/awaitLidTemperature": Callable[
+            ["ThermocyclerContext", "TemperatureParams"], None
+        ],
+        "thermocycler/awaitProfileComplete": Callable[
+            ["ThermocyclerContext", "ModuleIDParams"], None
+        ],
+    },
+)

opentrons/protocols/execution/errors.py

@@ -0,0 +1,40 @@
+from types import TracebackType
+from typing import Optional
+
+from opentrons_shared_data.errors.exceptions import GeneralError
+
+
+class ExceptionInProtocolError(GeneralError):
+    """This exception wraps an exception that was raised from a protocol
+    for proper error message formatting by the rpc, since it's only here that
+    we can properly figure out formatting
+    """
+
+    def __init__(
+        self,
+        original_exc: Exception,
+        original_tb: Optional[TracebackType],
+        message: str,
+        line: Optional[int],
+    ) -> None:
+        self.original_exc = original_exc
+        self.original_tb = original_tb
+        self.line = line
+        super().__init__(
+            wrapping=[original_exc],
+            message=_build_message(
+                exception_class_name=self.original_exc.__class__.__name__,
+                line_number=self.line,
+                message=message,
+            ),
+        )
+
+    def __str__(self) -> str:
+        return self.message
+
+
+def _build_message(
+    exception_class_name: str, line_number: Optional[int], message: str
+) -> str:
+    line_number_part = f" [line {line_number}]" if line_number is not None else ""
+    return f"{exception_class_name}{line_number_part}: {message}"

opentrons/protocols/execution/execute.py

@@ -0,0 +1,84 @@
+import logging
+from typing import Optional
+
+from opentrons.protocol_api import ProtocolContext
+from opentrons.protocol_api._parameters import Parameters
+from opentrons.protocols.execution.execute_python import exec_run
+from opentrons.protocols.execution.json_dispatchers import (
+    pipette_command_map,
+    temperature_module_command_map,
+    magnetic_module_command_map,
+    thermocycler_module_command_map,
+)
+from opentrons.protocols.execution import execute_json_v4, execute_json_v3
+
+from opentrons.protocols.types import PythonProtocol, Protocol
+from opentrons.protocols.api_support.types import APIVersion
+
+from opentrons.protocols.parameters.csv_parameter_interface import CSVParameter
+
+MODULE_LOG = logging.getLogger(__name__)
+
+
+def run_protocol(
+    protocol: Protocol,
+    context: ProtocolContext,
+    run_time_parameters_with_overrides: Optional[Parameters] = None,
+) -> None:
+    """Run a protocol.
+
+    :param protocol: The :py:class:`.protocols.types.Protocol` to execute
+    :param context: The protocol context to use.
+    :param run_time_parameters_with_overrides: Run time parameters defined in the protocol,
+        updated with the run's RTP override values. When we are running either simulate
+        or execute, this will be None (until RTP is supported in cli commands)
+    """
+    if isinstance(protocol, PythonProtocol):
+        try:
+            if protocol.api_level >= APIVersion(2, 0):
+                exec_run(
+                    proto=protocol,
+                    context=context,
+                    run_time_parameters_with_overrides=run_time_parameters_with_overrides,
+                )
+            else:
+                raise RuntimeError(
+                    f"Unsupported python API version: {protocol.api_level}"
+                )
+        except Exception:
+            raise
+        finally:
+            if protocol.api_level >= APIVersion(2, 18):
+                for parameter in context.params.get_all().values():
+                    if isinstance(parameter, CSVParameter) and parameter.file_opened:
+                        parameter.file.close()
+    else:
+        if protocol.contents["schemaVersion"] == 3:
+            ins = execute_json_v3.load_pipettes_from_json(context, protocol.contents)
+            lw = execute_json_v3.load_labware_from_json_defs(context, protocol.contents)
+            execute_json_v3.dispatch_json(context, protocol.contents, ins, lw)
+        elif protocol.contents["schemaVersion"] in [4, 5]:
+            # reuse the v3 fns for loading labware and pipettes
+            # b/c the v4 protocol has no changes for these keys
+            ins = execute_json_v3.load_pipettes_from_json(context, protocol.contents)
+
+            modules = execute_json_v4.load_modules_from_json(context, protocol.contents)
+
+            lw = execute_json_v4.load_labware_from_json_defs(
+                context, protocol.contents, modules
+            )
+            execute_json_v4.dispatch_json(
+                context,
+                protocol.contents,
+                ins,
+                lw,
+                modules,
+                pipette_command_map,
+                magnetic_module_command_map,
+                temperature_module_command_map,
+                thermocycler_module_command_map,
+            )
+        else:
+            raise RuntimeError(
+                f"Unsupported JSON protocol schema: {protocol.schema_version}"
+            )

opentrons/protocols/execution/execute_json_v3.py

@@ -0,0 +1,275 @@
+import logging
+from typing import Dict, TYPE_CHECKING
+
+from opentrons.protocol_api import ProtocolContext, InstrumentContext, Labware, Well
+from opentrons.protocols.api_support.labware_like import LabwareLike
+from opentrons.types import Point, Location
+from opentrons_shared_data.protocol.constants import (
+    JsonPipetteCommand,
+    JsonRobotCommand,
+)
+
+
+if TYPE_CHECKING:
+    from opentrons_shared_data.protocol.types import (
+        JsonProtocolV3,
+        JsonProtocol,
+        PipetteAccessParams,
+        StandardLiquidHandlingParams,
+        DelayParams,
+        FlowRateParams,
+        TouchTipParams,
+        PipetteAccessWithOffsetParams,
+        BlowoutParams,
+        MoveToSlotParams,
+    )
+    from opentrons.protocols.execution.dev_types import PipetteDispatch
+
+MODULE_LOG = logging.getLogger(__name__)
+
+
+def load_pipettes_from_json(
+    ctx: ProtocolContext, protocol: "JsonProtocol"
+) -> Dict[str, InstrumentContext]:
+    pipette_data = protocol["pipettes"]
+    pipettes_by_id = {}
+    for pipette_id, props in pipette_data.items():
+        mount = props["mount"]
+        name = props["name"]
+        instr = ctx.load_instrument(name, mount)
+        pipettes_by_id[pipette_id] = instr
+
+    return pipettes_by_id
+
+
+def _get_well(
+    loaded_labware: Dict[str, Labware], params: "PipetteAccessParams"
+) -> Well:
+    labwareId = params["labware"]
+    well = params["well"]
+    plate = loaded_labware[labwareId]
+    return plate[well]
+
+
+# TODO (Ian 2019-04-05) once Pipette commands allow flow rate as an
+# absolute value (not % value) as an argument in
+# aspirate/dispense/blowout/air_gap fns, remove this
+def _set_flow_rate(pipette: InstrumentContext, params: "FlowRateParams") -> None:
+    """
+    Set flow rate in uL/mm, to value obtained from command's params.
+    """
+    flow_rate_param = params["flowRate"]
+
+    if not (flow_rate_param > 0):
+        raise RuntimeError("Positive flowRate param required")
+
+    pipette.flow_rate.aspirate = flow_rate_param
+    pipette.flow_rate.dispense = flow_rate_param
+    pipette.flow_rate.blow_out = flow_rate_param
+
+
+def load_labware_from_json_defs(
+    ctx: ProtocolContext, protocol: "JsonProtocolV3"
+) -> Dict[str, Labware]:
+    protocol_labware = protocol["labware"]
+    definitions = protocol["labwareDefinitions"]
+    loaded_labware = {}
+
+    for labware_id, props in protocol_labware.items():
+        slot = props["slot"]
+        definition = definitions[props["definitionId"]]
+        label = props.get("displayName", None)
+        loaded_labware[labware_id] = ctx.load_labware_from_definition(
+            definition, slot, label
+        )
+
+    return loaded_labware
+
+
+def _get_location_with_offset(
+    loaded_labware: Dict[str, Labware], params: "PipetteAccessWithOffsetParams"
+) -> Location:
+    well = _get_well(loaded_labware, params)
+
+    # Never move to the bottom of the fixed trash
+    if LabwareLike(well).is_fixed_trash():
+        return well.top()
+
+    offset_from_bottom = params["offsetFromBottomMm"]
+    bottom = well.bottom()
+    return bottom.move(Point(z=offset_from_bottom))
+
+
+def _delay(context: ProtocolContext, params: "DelayParams") -> None:
+    wait = params["wait"]
+    message = params.get("message")
+    if wait is None or wait is False:
+        raise ValueError("Delay must be true, or a number")
+    elif wait is True:
+        message = message or "Pausing until user resumes"
+        context.pause(msg=message)
+    else:
+        context.delay(seconds=wait, msg=message)
+
+
+def _blowout(
+    instruments: Dict[str, InstrumentContext],
+    loaded_labware: Dict[str, Labware],
+    params: "BlowoutParams",
+) -> None:
+    pipette_id = params["pipette"]
+    pipette = instruments[pipette_id]
+    well = _get_well(loaded_labware, params)
+    _set_flow_rate(pipette, params)
+    pipette.blow_out(well)
+
+
+def _pick_up_tip(
+    instruments: Dict[str, InstrumentContext],
+    loaded_labware: Dict[str, Labware],
+    params: "PipetteAccessParams",
+) -> None:
+    pipette_id = params["pipette"]
+    pipette = instruments[pipette_id]
+    well = _get_well(loaded_labware, params)
+    pipette.pick_up_tip(well)
+
+
+def _drop_tip(
+    instruments: Dict[str, InstrumentContext],
+    loaded_labware: Dict[str, Labware],
+    params: "PipetteAccessParams",
+) -> None:
+    pipette_id = params["pipette"]
+    pipette = instruments[pipette_id]
+    well = _get_well(loaded_labware, params)
+    pipette.drop_tip(well)
+
+
+def _aspirate(
+    instruments: Dict[str, InstrumentContext],
+    loaded_labware: Dict[str, Labware],
+    params: "StandardLiquidHandlingParams",
+) -> None:
+    pipette_id = params["pipette"]
+    pipette = instruments[pipette_id]
+    location = _get_location_with_offset(loaded_labware, params)
+    volume = params["volume"]
+    _set_flow_rate(pipette, params)
+    pipette.aspirate(volume, location)
+
+
+def _dispense(
+    instruments: Dict[str, InstrumentContext],
+    loaded_labware: Dict[str, Labware],
+    params: "StandardLiquidHandlingParams",
+) -> None:
+    pipette_id = params["pipette"]
+    pipette = instruments[pipette_id]
+    location = _get_location_with_offset(loaded_labware, params)
+    volume = params["volume"]
+    _set_flow_rate(pipette, params)
+    pipette.dispense(volume, location)
+
+
+def _air_gap(
+    instruments: Dict[str, InstrumentContext],
+    loaded_labware: Dict[str, Labware],
+    params: "StandardLiquidHandlingParams",
+) -> None:
+    pipette_id = params["pipette"]
+    pipette = instruments[pipette_id]
+    offset_from_bottom = params["offsetFromBottomMm"]
+    volume = params["volume"]
+    _set_flow_rate(pipette, params)
+    well = _get_well(loaded_labware, params)
+    offset_from_top = offset_from_bottom - well.geometry._depth
+
+    # NOTE(IL, 2020-06-25): air_gap API fn is stateful, uses location
+    # cache. The JSON atomic command should be stateless. We'll
+    # explicitly move_to the specified well to ensure the location
+    # cache is set to that well.
+    pipette.move_to(well.top(offset_from_top))
+    pipette.air_gap(volume, offset_from_top)
+
+
+def _touch_tip(
+    instruments: Dict[str, InstrumentContext],
+    loaded_labware: Dict[str, Labware],
+    params: "TouchTipParams",
+) -> None:
+    pipette_id = params["pipette"]
+    pipette = instruments[pipette_id]
+    location = _get_location_with_offset(loaded_labware, params)
+    well = _get_well(loaded_labware, params)
+    # convert mmFromBottom to v_offset
+    v_offset = location.point.z - well.top().point.z
+    pipette.touch_tip(well, v_offset=v_offset)
+
+
+def _move_to_slot(
+    context: ProtocolContext,
+    instruments: Dict[str, InstrumentContext],
+    params: "MoveToSlotParams",
+) -> None:
+    pipette_id = params["pipette"]
+    pipette = instruments[pipette_id]
+    slot = params["slot"]
+    if slot not in context.deck:
+        raise ValueError('Invalid "slot" for "moveToSlot": {}'.format(slot))
+    slot_obj = context.deck.position_for(slot)
+
+    offset = params.get("offset", {})
+    offsetPoint = Point(offset.get("x", 0), offset.get("y", 0), offset.get("z", 0))
+
+    pipette.move_to(
+        slot_obj.move(offsetPoint),
+        force_direct=params.get("forceDirect", False),
+        minimum_z_height=params.get("minimumZHeight"),
+    )
+
+
+dispatcher_map: "PipetteDispatch" = {
+    JsonRobotCommand.delay.value: _delay,
+    JsonPipetteCommand.blowout.value: _blowout,
+    JsonPipetteCommand.pickUpTip.value: _pick_up_tip,
+    JsonPipetteCommand.dropTip.value: _drop_tip,
+    JsonPipetteCommand.aspirate.value: _aspirate,
+    JsonPipetteCommand.dispense.value: _dispense,
+    JsonPipetteCommand.touchTip.value: _touch_tip,
+    JsonPipetteCommand.moveToSlot.value: _move_to_slot,
+}
+
+
+def dispatch_json(
+    context: ProtocolContext,
+    protocol_data: "JsonProtocolV3",
+    instruments: Dict[str, InstrumentContext],
+    loaded_labware: Dict[str, Labware],
+) -> None:
+    commands = protocol_data["commands"]
+
+    pipette_commands = {
+        JsonPipetteCommand.blowout.value,
+        JsonPipetteCommand.pickUpTip.value,
+        JsonPipetteCommand.dropTip.value,
+        JsonPipetteCommand.aspirate.value,
+        JsonPipetteCommand.dispense.value,
+        JsonPipetteCommand.touchTip.value,
+    }
+
+    for command_item in commands:
+        command_type = command_item["command"]
+        params = command_item["params"]
+
+        # different `_command` helpers take different args
+        if command_type in pipette_commands:
+            dispatcher_map[command_type](  # type: ignore[call-arg]
+                instruments, loaded_labware, params  # type: ignore[arg-type]
+            )
+        elif command_type == JsonRobotCommand.delay.value:
+            dispatcher_map[command_type](context, params)  # type: ignore
+        elif command_type == JsonPipetteCommand.moveToSlot.value:
+            dispatcher_map[command_type](context, instruments, params)  # type: ignore
+        else:
+            raise RuntimeError("Unsupported command type {}".format(command_type))