opentrons 8.6.0__py3-none-any.whl

opentrons/protocols/execution/execute_json_v4.py

@@ -0,0 +1,359 @@
+import logging
+from typing import Dict, List, TYPE_CHECKING, Union
+from opentrons.hardware_control.modules.types import ThermocyclerStep
+from opentrons.protocol_api import (
+    ProtocolContext,
+    MagneticModuleContext,
+    TemperatureModuleContext,
+    ModuleContext,
+    ThermocyclerContext,
+)
+from opentrons_shared_data.protocol.types import (
+    MagneticModuleCommand,
+    TemperatureModuleCommand,
+    ThermocyclerCommand,
+)
+from .execute_json_v3 import _delay, _move_to_slot
+from opentrons.protocols.execution.types import LoadedLabware, Instruments
+from opentrons_shared_data.protocol.constants import (
+    JsonRobotCommand,
+    JsonPipetteCommand,
+)
+
+
+if TYPE_CHECKING:
+    from opentrons_shared_data.protocol.types import (
+        JsonProtocolV4,
+        JsonProtocolV5,
+        MagneticModuleEngageParams,
+        ModuleIDParams,
+        TemperatureParams,
+        ThermocyclerSetTargetBlockParams,
+        ThermocyclerRunProfileParams,
+        Command,
+        TemperatureModuleCommandId,
+        MagneticModuleCommandId,
+        ThermocyclerCommandId,
+    )
+    from opentrons.protocols.execution.dev_types import (
+        PipetteDispatch,
+        JsonV4MagneticModuleDispatch,
+        JsonV4TemperatureModuleDispatch,
+        JsonV4ThermocyclerDispatch,
+    )
+
+MODULE_LOG = logging.getLogger(__name__)
+
+# Special string for slot used by thermocycler in JSON protocols.
+TC_SPANNING_SLOT = "span7_8_10_11"
+
+
+def load_labware_from_json_defs(
+    ctx: ProtocolContext, protocol: "JsonProtocolV4", modules: Dict[str, ModuleContext]
+) -> LoadedLabware:
+    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)
+        if slot in modules:
+            loaded_labware[labware_id] = modules[slot].load_labware_from_definition(
+                definition, label
+            )
+        else:
+            loaded_labware[labware_id] = ctx.load_labware_from_definition(
+                definition, slot, label
+            )
+
+    return loaded_labware
+
+
+def load_modules_from_json(
+    ctx: ProtocolContext, protocol: "JsonProtocolV4"
+) -> Dict[str, ModuleContext]:
+    module_data = protocol["modules"]
+    modules_by_id: Dict[str, ModuleContext] = {}
+
+    # the sort order doesn't matter, we just need it to be stable
+    # to ensure `load_module` side-effects are deterministic
+    # (eg, multiple module support)
+    sorted_modules = sorted(
+        module_data.items(), key=lambda v: v[1]["slot"] + v[1]["model"]
+    )
+
+    for module_id, module_props in sorted_modules:
+        model = module_props["model"]
+        slot = module_props["slot"]
+        if slot == TC_SPANNING_SLOT:
+            instr = ctx.load_module(model)
+        else:
+            instr = ctx.load_module(model, slot)
+        modules_by_id[module_id] = instr
+
+    return modules_by_id
+
+
+def _engage_magnet(
+    module: MagneticModuleContext, params: "MagneticModuleEngageParams"
+) -> None:
+    engage_height = params["engageHeight"]
+    module.engage(height_from_base=engage_height)
+
+
+def _disengage_magnet(module: MagneticModuleContext, params: "ModuleIDParams") -> None:
+    module.disengage()
+
+
+def _temperature_module_set_temp(
+    module: TemperatureModuleContext, params: "TemperatureParams"
+) -> None:
+    temperature = params["temperature"]
+    module.start_set_temperature(temperature)
+
+
+def _temperature_module_deactivate(
+    module: TemperatureModuleContext, params: "ModuleIDParams"
+) -> None:
+    module.deactivate()
+
+
+def _temperature_module_await_temp(
+    module: TemperatureModuleContext, params: "TemperatureParams"
+) -> None:
+    temperature = params["temperature"]
+    module.await_temperature(temperature)
+
+
+def _thermocycler_close_lid(
+    module: ThermocyclerContext, params: "ModuleIDParams"
+) -> None:
+    module.close_lid()
+
+
+def _thermocycler_open_lid(
+    module: ThermocyclerContext, params: "ModuleIDParams"
+) -> None:
+    module.open_lid()
+
+
+def _thermocycler_deactivate_block(
+    module: ThermocyclerContext, params: "ModuleIDParams"
+) -> None:
+    module.deactivate_block()
+
+
+def _thermocycler_deactivate_lid(
+    module: ThermocyclerContext, params: "ModuleIDParams"
+) -> None:
+    module.deactivate_lid()
+
+
+def _thermocycler_set_block_temperature(
+    module: ThermocyclerContext, params: "ThermocyclerSetTargetBlockParams"
+) -> None:
+    temperature = params["temperature"]
+    module.set_block_temperature(temperature)
+
+
+def _thermocycler_set_lid_temperature(
+    module: ThermocyclerContext, params: "TemperatureParams"
+) -> None:
+    temperature = params["temperature"]
+    module.set_lid_temperature(temperature)
+
+
+def _thermocycler_run_profile(
+    module: ThermocyclerContext, params: "ThermocyclerRunProfileParams"
+) -> None:
+    volume = params["volume"]
+    profile = [
+        ThermocyclerStep(temperature=p["temperature"], hold_time_seconds=p["holdTime"])
+        for p in params["profile"]
+    ]
+    module.execute_profile(steps=profile, block_max_volume=volume, repetitions=1)
+
+
+def assert_no_async_tc_behavior(commands: List["Command"]) -> None:
+    # awaiters[i] corresponds to setters[i]
+    setters = [
+        "thermocycler/setTargetBlockTemperature",
+        "thermocycler/setTargetLidTemperature",
+        "thermocycler/runProfile",
+    ]
+    awaiters = [
+        "thermocycler/awaitBlockTemperature",
+        "thermocycler/awaitLidTemperature",
+        "thermocycler/awaitProfileComplete",
+    ]
+
+    command_types = [c["command"] for c in commands]
+
+    first_command = command_types[0]
+    if first_command in awaiters:
+        raise RuntimeError(
+            (
+                "Unsupported behavior. Cannot {} as the "
+                + "first command of a protocol"
+            ).format(first_command)
+        )
+
+    last_command = command_types[-1]
+    if last_command in setters:
+        raise RuntimeError(
+            (
+                "Unsupported behavior. Cannot {} as the " + "last command of a protocol"
+            ).format(last_command)
+        )
+
+    # [a, b, c, d] -> [a, b], [b, c], [c, d]
+    for a, b in zip(command_types, command_types[1:]):
+        #  a setter must be immediately followed
+        # by its corresponding awaiter
+        if a in setters:
+            expected_awaiter = awaiters[setters.index(a)]
+            if b != expected_awaiter:
+                raise RuntimeError(
+                    (
+                        "Unsupported behavior. {} must be immediately"
+                        + "followed by {}"
+                    ).format(a, expected_awaiter)
+                )
+        # an awaiter must be preceded by a setter
+        elif b in awaiters:
+            expected_setter = setters[awaiters.index(b)]
+            raise RuntimeError(
+                (
+                    "Unsupported behavior. {} must be immediately " + "preceded by {}"
+                ).format(b, expected_setter)
+            )
+
+
+def assert_tc_commands_do_not_use_unimplemented_params(
+    commands: List["Command"],
+) -> None:
+    # raise errors if commands include optional param keys that
+    # the executor/api does not currently support
+    unsupported_keys_by_command = {"thermocycler/setTargetBlockTemperature": ["volume"]}
+    for c in commands:
+        command_type = c["command"]
+        params = c["params"]
+        unsupported_keys = unsupported_keys_by_command.get(command_type, [])
+        for k in unsupported_keys:
+            if k in params:
+                raise RuntimeError(
+                    (
+                        "{} does not support {} param. "
+                        + "This may be implemented in a later version of "
+                        + "the robot server"
+                    ).format(command_type, k)
+                )
+
+
+def dispatch_json(
+    context: ProtocolContext,
+    protocol_data: Union["JsonProtocolV4", "JsonProtocolV5"],
+    instruments: Instruments,
+    loaded_labware: LoadedLabware,
+    modules: Dict[str, ModuleContext],
+    pipette_command_map: "PipetteDispatch",
+    magnetic_module_command_map: "JsonV4MagneticModuleDispatch",
+    temperature_module_command_map: "JsonV4TemperatureModuleDispatch",
+    thermocycler_module_command_map: "JsonV4ThermocyclerDispatch",
+) -> None:
+    commands = protocol_data["commands"]
+
+    assert_no_async_tc_behavior(commands)
+    assert_tc_commands_do_not_use_unimplemented_params(commands)
+
+    for command_item in commands:
+        command_type = command_item["command"]
+        params = command_item["params"]
+        # because of https://github.com/python/mypy/issues/8940
+        # we can't narrow down types using in sadly
+        if command_type in pipette_command_map:
+            pipette_command_map[command_type](  # type: ignore
+                instruments, loaded_labware, params
+            )
+        elif command_type in magnetic_module_command_map:
+            handleMagnetCommand(
+                params,  # type: ignore
+                modules,
+                command_type,  # type: ignore
+                magnetic_module_command_map,  # type: ignore[arg-type]
+            )
+        elif command_type in temperature_module_command_map:
+            handleTemperatureCommand(
+                params,  # type: ignore[arg-type]
+                modules,
+                command_type,  # type: ignore
+                temperature_module_command_map,  # type: ignore[arg-type]
+            )
+        elif command_type in thermocycler_module_command_map:
+            handleThermocyclerCommand(
+                params,  # type: ignore
+                modules,  # type: ignore
+                command_type,  # type: ignore
+                thermocycler_module_command_map,  # type: ignore[arg-type]
+            )
+        elif command_item["command"] == JsonRobotCommand.delay.value:
+            _delay(context, params)  # type: ignore
+        elif command_type == JsonPipetteCommand.moveToSlot.value:
+            _move_to_slot(context, instruments, params)  # type: ignore
+        else:
+            raise RuntimeError("Unsupported command type {}".format(command_type))
+
+
+def handleTemperatureCommand(
+    params: Union["TemperatureParams", "ModuleIDParams"],
+    modules: Dict[str, ModuleContext],
+    command_type: "TemperatureModuleCommandId",
+    temperature_module_command_map: TemperatureModuleCommand,
+) -> None:
+    module_id = params["module"]
+    module = modules[module_id]
+    if isinstance(module, TemperatureModuleContext):
+        temperature_module_command_map[command_type](module, params)  # type: ignore[typeddict-item]
+    else:
+        raise RuntimeError(
+            "Temperature Module does not match " + "TemperatureModuleContext interface"
+        )
+
+
+def handleThermocyclerCommand(
+    params: Union[
+        "ModuleIDParams",
+        "TemperatureParams",
+        "ThermocyclerRunProfileParams",
+        "ThermocyclerSetTargetBlockParams",
+    ],
+    modules: Dict[str, ThermocyclerContext],
+    command_type: "ThermocyclerCommandId",
+    thermocycler_module_command_map: ThermocyclerCommand,
+) -> None:
+    module_id = params["module"]
+    module = modules[module_id]
+    if isinstance(module, ThermocyclerContext):
+        thermocycler_module_command_map[command_type](module, params)  # type: ignore[typeddict-item]
+    else:
+        raise RuntimeError(
+            "Thermocycler Module does not match ThermocyclerContext interface"
+        )
+
+
+def handleMagnetCommand(
+    params: Union["ModuleIDParams", "MagneticModuleEngageParams"],
+    modules: Dict[str, ModuleContext],
+    command_type: "MagneticModuleCommandId",
+    magnetic_module_command_map: MagneticModuleCommand,
+) -> None:
+    module_id = params["module"]
+    module = modules[module_id]
+    if isinstance(module, MagneticModuleContext):
+        magnetic_module_command_map[command_type](module, params)  # type: ignore[typeddict-item]
+    else:
+        raise RuntimeError(
+            "Magnetic Module does not match MagneticModuleContext interface"
+        )

opentrons/protocols/execution/execute_json_v5.py

@@ -0,0 +1,28 @@
+import logging
+from typing import TYPE_CHECKING
+from opentrons.types import Point
+from opentrons.protocols.execution.types import LoadedLabware, Instruments
+from .execute_json_v3 import _get_well
+
+if TYPE_CHECKING:
+    from opentrons_shared_data.protocol.types import MoveToWellParams
+
+MODULE_LOG = logging.getLogger(__name__)
+
+
+def _move_to_well(
+    instruments: Instruments, loaded_labware: LoadedLabware, params: "MoveToWellParams"
+) -> None:
+    pipette_id = params["pipette"]
+    pipette = instruments[pipette_id]
+
+    well = _get_well(loaded_labware, params)
+
+    offset = params.get("offset", {})
+    offsetPoint = Point(offset.get("x", 0), offset.get("y", 0), offset.get("z", 0))
+
+    pipette.move_to(
+        well.bottom().move(offsetPoint),
+        force_direct=params.get("forceDirect", False),
+        minimum_z_height=params.get("minimumZHeight"),
+    )

opentrons/protocols/execution/execute_python.py

@@ -0,0 +1,169 @@
+import asyncio
+import inspect
+import logging
+import traceback
+import sys
+from types import TracebackType
+from typing import Any, Dict, Optional
+
+from opentrons.drivers.smoothie_drivers.errors import SmoothieAlarm
+from opentrons.protocol_api import ProtocolContext, ParameterContext
+from opentrons.protocol_api._parameters import Parameters
+from opentrons.protocols.execution.errors import ExceptionInProtocolError
+from opentrons.protocols.types import PythonProtocol, MalformedPythonProtocolError
+from opentrons.protocol_engine.types import (
+    PrimitiveRunTimeParamValuesType,
+    CSVRuntimeParamPaths,
+)
+
+
+from opentrons_shared_data.errors.exceptions import ExecutionCancelledError
+
+MODULE_LOG = logging.getLogger(__name__)
+
+
+def _runfunc_ok(run_func: Any) -> None:
+    if not callable(run_func):
+        raise SyntaxError("No function 'run(ctx)' defined")
+    sig = inspect.Signature.from_callable(run_func)
+    if not sig.parameters:
+        raise SyntaxError("Function 'run()' does not take any parameters")
+    if len(sig.parameters) > 1:
+        for name, param in list(sig.parameters.items())[1:]:
+            if param.default == inspect.Parameter.empty:
+                raise SyntaxError(
+                    "Function 'run{}' must be called with more than one "
+                    "argument but would be called as 'run(ctx)'".format(str(sig))
+                )
+
+
+def _add_parameters_func_ok(add_parameters_func: Any) -> None:
+    if not callable(add_parameters_func):
+        raise SyntaxError("'add_parameters' must be a function.")
+    sig = inspect.Signature.from_callable(add_parameters_func)
+    if len(sig.parameters) != 1:
+        raise SyntaxError("Function 'add_parameters' must take exactly one argument.")
+
+
+def _find_protocol_error(
+    tb: TracebackType | None, proto_name: str
+) -> traceback.FrameSummary:
+    """Return the FrameInfo for the lowest frame in the traceback from the
+    protocol.
+    """
+    if tb is None:
+        raise KeyError
+    tb_info = traceback.extract_tb(tb)
+    for frame in reversed(tb_info):
+        if frame.filename == proto_name:
+            return frame
+    else:
+        raise KeyError
+
+
+def _raise_pretty_protocol_error(exception: Exception, filename: str) -> None:
+    _, _, tb = sys.exc_info()
+    try:
+        frame = _find_protocol_error(tb, filename)
+    except KeyError:
+        # No pretty names, just raise it
+        raise exception
+    raise ExceptionInProtocolError(
+        exception, tb, str(exception), frame.lineno
+    ) from exception
+
+
+def _parse_and_set_parameters(
+    parameter_context: ParameterContext,
+    run_time_param_overrides: Optional[PrimitiveRunTimeParamValuesType],
+    run_time_param_file_overrides: Optional[CSVRuntimeParamPaths],
+    new_globs: Dict[Any, Any],
+    filename: str,
+) -> Parameters:
+    try:
+        _add_parameters_func_ok(new_globs.get("add_parameters"))
+    except SyntaxError as se:
+        raise MalformedPythonProtocolError(str(se))
+    new_globs["__param_context"] = parameter_context
+    try:
+        exec("add_parameters(__param_context)", new_globs)
+        if run_time_param_overrides is not None:
+            parameter_context.set_parameters(run_time_param_overrides)
+        if run_time_param_file_overrides is not None:
+            parameter_context.initialize_csv_files(run_time_param_file_overrides)
+    except Exception as e:
+        _raise_pretty_protocol_error(exception=e, filename=filename)
+    return parameter_context.export_parameters_for_protocol()
+
+
+def _get_filename(
+    protocol: PythonProtocol,
+) -> str:
+    # TODO(mm, 2023-10-11): This coupling to opentrons.protocols.parse is fragile.
+    # Can we get the correct filename directly from proto.contents?
+    if protocol.filename and protocol.filename.endswith("zip"):
+        # The ".zip" extension needs to match what opentrons.protocols.parse recognizes as a bundle,
+        # and the "protocol.ot2.py" fallback needs to match what opentrons.protocol.py sets as the
+        # AST filename.
+        return "protocol.ot2.py"
+    else:
+        # "<protocol>" needs to match what opentrons.protocols.parse sets as the fallback
+        # AST filename.
+        return protocol.filename or "<protocol>"
+
+
+def exec_add_parameters(
+    protocol: PythonProtocol,
+    parameter_context: ParameterContext,
+    run_time_param_overrides: Optional[PrimitiveRunTimeParamValuesType],
+    run_time_param_file_overrides: Optional[CSVRuntimeParamPaths],
+) -> Optional[Parameters]:
+    """Exec the add_parameters function and get the final run time parameters with overrides."""
+    new_globs: Dict[Any, Any] = {}
+    exec(protocol.contents, new_globs)
+    filename = _get_filename(protocol)
+
+    return (
+        _parse_and_set_parameters(
+            parameter_context=parameter_context,
+            run_time_param_overrides=run_time_param_overrides,
+            run_time_param_file_overrides=run_time_param_file_overrides,
+            new_globs=new_globs,
+            filename=filename,
+        )
+        if new_globs.get("add_parameters")
+        else None
+    )
+
+
+def exec_run(
+    proto: PythonProtocol,
+    context: ProtocolContext,
+    run_time_parameters_with_overrides: Optional[Parameters] = None,
+) -> None:
+    new_globs: Dict[Any, Any] = {}
+    exec(proto.contents, new_globs)
+    # If the protocol is written correctly, it will have defined a function
+    # like run(context: ProtocolContext). If so, that function is now in the
+    # current scope.
+    filename = _get_filename(proto)
+    if run_time_parameters_with_overrides:
+        context._params = run_time_parameters_with_overrides
+
+    try:
+        _runfunc_ok(new_globs.get("run"))
+    except SyntaxError as se:
+        raise MalformedPythonProtocolError(str(se))
+
+    new_globs["__context"] = context
+    try:
+        exec("run(__context)", new_globs)
+    except (
+        SmoothieAlarm,
+        asyncio.CancelledError,
+        ExecutionCancelledError,
+    ):
+        # this is a protocol cancel and shouldn't have special logging
+        raise
+    except Exception as e:
+        _raise_pretty_protocol_error(exception=e, filename=filename)

opentrons/protocols/execution/json_dispatchers.py

@@ -0,0 +1,87 @@
+from typing import TYPE_CHECKING
+from opentrons.protocols.execution.execute_json_v3 import (
+    _blowout,
+    _pick_up_tip,
+    _drop_tip,
+    _aspirate,
+    _dispense,
+    _touch_tip,
+    _air_gap,
+)
+from opentrons.protocols.execution.execute_json_v4 import (
+    _engage_magnet,
+    _disengage_magnet,
+    _temperature_module_set_temp,
+    _temperature_module_deactivate,
+    _temperature_module_await_temp,
+    _thermocycler_close_lid,
+    _thermocycler_open_lid,
+    _thermocycler_deactivate_block,
+    _thermocycler_deactivate_lid,
+    _thermocycler_set_block_temperature,
+    _thermocycler_set_lid_temperature,
+    _thermocycler_run_profile,
+)
+from opentrons.protocols.execution.execute_json_v5 import _move_to_well
+
+from opentrons.protocol_api.module_contexts import ThermocyclerContext
+
+
+from opentrons_shared_data.protocol.constants import (
+    JsonPipetteCommand,
+    JsonMagneticModuleCommand,
+    JsonTemperatureModuleCommand,
+    JsonThermocyclerCommand,
+)
+
+if TYPE_CHECKING:
+    from opentrons.protocols.execution.dev_types import (
+        PipetteDispatch,
+        JsonV4MagneticModuleDispatch,
+        JsonV4TemperatureModuleDispatch,
+        JsonV4ThermocyclerDispatch,
+    )
+
+
+pipette_command_map: "PipetteDispatch" = {
+    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.airGap.value: _air_gap,
+    JsonPipetteCommand.moveToWell.value: _move_to_well,
+}
+
+magnetic_module_command_map: "JsonV4MagneticModuleDispatch" = {
+    JsonMagneticModuleCommand.magneticModuleEngageMagnet.value: _engage_magnet,
+    JsonMagneticModuleCommand.magneticModuleDisengageMagnet.value: _disengage_magnet,
+}
+
+temperature_module_command_map: "JsonV4TemperatureModuleDispatch" = {
+    JsonTemperatureModuleCommand.temperatureModuleSetTargetTemperature.value: _temperature_module_set_temp,
+    JsonTemperatureModuleCommand.temperatureModuleDeactivate.value: _temperature_module_deactivate,
+    JsonTemperatureModuleCommand.temperatureModuleAwaitTemperature.value: _temperature_module_await_temp,
+}
+
+
+def tc_do_nothing(module: ThermocyclerContext, params: object) -> None:
+    pass
+
+
+thermocycler_module_command_map: "JsonV4ThermocyclerDispatch" = {
+    JsonThermocyclerCommand.thermocyclerCloseLid.value: _thermocycler_close_lid,
+    JsonThermocyclerCommand.thermocyclerOpenLid.value: _thermocycler_open_lid,
+    JsonThermocyclerCommand.thermocyclerDeactivateBlock.value: _thermocycler_deactivate_block,
+    JsonThermocyclerCommand.thermocyclerDeactivateLid.value: _thermocycler_deactivate_lid,
+    JsonThermocyclerCommand.thermocyclerSetTargetBlockTemperature.value: _thermocycler_set_block_temperature,
+    JsonThermocyclerCommand.thermocyclerSetTargetLidTemperature.value: _thermocycler_set_lid_temperature,
+    JsonThermocyclerCommand.thermocyclerRunProfile.value: _thermocycler_run_profile,
+    # NOTE: the thermocyclerAwaitX commands are expected to always
+    # follow a corresponding SetX command, which is implemented as
+    # blocking. Then nothing needs to be done for awaitX commands.
+    JsonThermocyclerCommand.thermocyclerAwaitBlockTemperature.value: tc_do_nothing,
+    JsonThermocyclerCommand.thermocyclerAwaitLidTemperature.value: tc_do_nothing,
+    JsonThermocyclerCommand.thermocyclerAwaitProfileComplete.value: tc_do_nothing,
+}

opentrons/protocols/execution/types.py

@@ -0,0 +1,7 @@
+from typing import Dict
+from opentrons.protocol_api import InstrumentContext, Labware
+
+
+Instruments = Dict[str, InstrumentContext]
+
+LoadedLabware = Dict[str, Labware]