opentrons 8.6.0__py3-none-any.whl

opentrons/protocol_reader/protocol_source.py

@@ -0,0 +1,124 @@
+"""Protocol source value objects."""
+from enum import Enum
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+from typing_extensions import Literal
+
+from opentrons.protocols.api_support.types import APIVersion
+
+from opentrons_shared_data.robot.types import RobotType
+
+
+class ProtocolType(str, Enum):
+    """Type of protocol, JSON or Python."""
+
+    JSON = "json"
+    PYTHON = "python"
+
+
+# TODO(mc, 2021-12-07): add python support roles
+class ProtocolFileRole(str, Enum):
+    """The purpose of a given file in a protocol.
+
+    Args:
+        MAIN: The protocol's main file. In a JSON protocol, this is will
+            be the JSON file. In a Python protocol, this is the file
+            that exports the main `run` method.
+        LABWARE: A labware definition file, loadable by a
+            Python file in the same protocol.
+        DATA: An arbitrary text or csv file for usage in `bundled_data`
+            for a Python protool
+    """
+
+    MAIN = "main"
+    LABWARE = "labware"
+    DATA = "data"
+
+
+@dataclass(frozen=True)
+class ProtocolSourceFile:
+    """A single file in a protocol.
+
+    Attributes:
+        path: The file's path on disk.
+        role: The file's purpose in the protocol.
+    """
+
+    path: Path
+    role: ProtocolFileRole
+
+
+@dataclass(frozen=True)
+class JsonProtocolConfig:
+    """Execution configuration for a JSON protocol.
+
+    Attributes:
+        schema_version: JSON schema version of the JSON protocol.
+        protocol_type: Type of protocol
+    """
+
+    schema_version: int
+    protocol_type: Literal[ProtocolType.JSON] = ProtocolType.JSON
+
+
+@dataclass(frozen=True)
+class PythonProtocolConfig:
+    """Execution configuration for a Python protocol.
+
+    Attributes:
+        api_version: Python Protocol API version of the protocol.
+        protocol_type: Type of protocol
+    """
+
+    api_version: APIVersion
+    protocol_type: Literal[ProtocolType.PYTHON] = ProtocolType.PYTHON
+
+
+ProtocolConfig = Union[JsonProtocolConfig, PythonProtocolConfig]
+"""Union of all protocol execution configurations."""
+
+
+# TODO(mc, 2021-12-09): Dict[str, Any] is an overly-permissive approximation
+# due to mypy's lack of easy recursive types. Find a more accurate type
+Metadata = Dict[str, Any]
+"""A protocol's metadata (non-essential info, like author and title).
+
+Robot software may not change how it executes a protocol based on
+metadata (excepting a Python protocol's API version, which is in
+metadata due to a historical implementation detail).
+
+Metadata must be a simple JSON-serializable dictionary.
+"""
+
+
+@dataclass(frozen=True)
+class ProtocolSource:
+    """A value object representing a protocol and its source files on disk.
+
+    This includes pointers to the files,
+    plus some basic information that can be readily inferred from those files.
+    (Excluding information that would require in-depth simulation of the protocol.)
+
+    Attributes:
+        directory: The directory containing the protocol files
+            (and only the protocol files), or ``None`` if this is unknown.
+        main_file: The location of the protocol's main file on disk.
+        content_hash: A md5 hex digest of the protocol source combined with
+            custom labware that was provided at the time of protocol creation
+        files: Descriptions of all files that make up the protocol.
+        metadata: Arbitrary metadata specified by the protocols.
+        config: Protocol execution configuration.
+        labware_definitions: Labware definitions provided by separate
+            labware files or the main JSON protocol file, if present.
+            This is not necessarily the same set of labware definitions
+            that the protocol will actually attempt to load.
+    """
+
+    directory: Optional[Path]
+    main_file: Path
+    content_hash: str
+    files: List[ProtocolSourceFile]
+    metadata: Metadata
+    robot_type: RobotType
+    config: ProtocolConfig

opentrons/protocol_reader/role_analyzer.py

@@ -0,0 +1,86 @@
+"""Input file role analysis."""
+from dataclasses import dataclass
+from typing import List, Sequence, Union
+
+from .file_identifier import (
+    IdentifiedFile,
+    IdentifiedJsonMain,
+    IdentifiedPythonMain,
+    IdentifiedLabwareDefinition,
+    IdentifiedData,
+)
+from .protocol_files_invalid_error import ProtocolFilesInvalidError
+
+
+@dataclass(frozen=True)
+class RoleAnalysis:
+    """Role analysis results."""
+
+    main_file: Union[IdentifiedJsonMain, IdentifiedPythonMain]
+    labware_files: List[IdentifiedLabwareDefinition]
+    data_files: List[IdentifiedData]
+
+    @property
+    def all_files(self) -> List[IdentifiedFile]:
+        """Return all contained files."""
+        return [self.main_file, *self.labware_files, *self.data_files]
+
+
+class RoleAnalysisError(ProtocolFilesInvalidError):
+    """Error raised if the input file list is invalid."""
+
+
+class RoleAnalyzer:
+    """Input file role analysis interface."""
+
+    @staticmethod
+    def analyze(files: Sequence[IdentifiedFile]) -> RoleAnalysis:
+        """Analyze a set of input files to determine the role that each one fills.
+
+        This validates that there is exactly one main protocol file.
+        """
+        if len(files) == 0:
+            raise RoleAnalysisError(
+                message="No files were provided.", detail={"kind": "no-files"}
+            )
+
+        main_file_candidates: List[Union[IdentifiedJsonMain, IdentifiedPythonMain]] = []
+        labware_files: List[IdentifiedLabwareDefinition] = []
+        bundled_data_files: List[IdentifiedData] = []
+
+        for f in files:
+            if isinstance(f, (IdentifiedJsonMain, IdentifiedPythonMain)):
+                main_file_candidates.append(f)
+            elif isinstance(f, IdentifiedLabwareDefinition):
+                labware_files.append(f)
+            else:
+                bundled_data_files.append(f)
+
+        if len(main_file_candidates) == 0:
+            if len(files) == 1:
+                raise RoleAnalysisError(
+                    message=f'"{files[0].original_file.name}" is not a valid protocol file.',
+                    detail={"kind": "protocol-does-not-have-main"},
+                )
+            else:
+                file_list = ", ".join(f'"{f.original_file.name}"' for f in files)
+                raise RoleAnalysisError(
+                    message=f"No valid protocol file found in {file_list}.",
+                    detail={"kind": "protocol-does-not-have-main"},
+                )
+        elif len(main_file_candidates) > 1:
+            file_list = ", ".join(
+                f'"{f.original_file.name}"' for f in main_file_candidates
+            )
+            raise RoleAnalysisError(
+                message=f"Could not pick single main file from {file_list}.",
+                detail={"kind": "multiple-main-candidates"},
+            )
+        else:
+            main_file = main_file_candidates[0]
+
+        return RoleAnalysis(
+            main_file=main_file,
+            labware_files=labware_files,
+            data_files=bundled_data_files,
+        )

opentrons/protocol_runner/__init__.py

@@ -0,0 +1,26 @@
+"""Protocol run control and management.
+
+The main export of this module is the AbstractRunner class. See
+protocol_runner.py for more details.
+"""
+from .protocol_runner import (
+    AbstractRunner,
+    RunResult,
+    create_protocol_runner,
+    JsonRunner,
+    PythonAndLegacyRunner,
+    LiveRunner,
+    AnyRunner,
+)
+from .run_orchestrator import RunOrchestrator
+
+__all__ = [
+    "AbstractRunner",
+    "RunResult",
+    "create_protocol_runner",
+    "JsonRunner",
+    "PythonAndLegacyRunner",
+    "LiveRunner",
+    "AnyRunner",
+    "RunOrchestrator",
+]

opentrons/protocol_runner/create_simulating_orchestrator.py

@@ -0,0 +1,118 @@
+"""Simulating AbstractRunner factory."""
+
+from opentrons.hardware_control import API as OT2API, HardwareControlAPI
+from opentrons.protocols.api_support import deck_type
+from opentrons.protocols.api_support.deck_type import should_load_fixed_trash
+from opentrons.protocol_engine import (
+    Config as ProtocolEngineConfig,
+    DeckType,
+    error_recovery_policy,
+)
+from opentrons.protocol_engine.create_protocol_engine import create_protocol_engine
+from opentrons.protocol_reader.protocol_source import ProtocolConfig
+
+from opentrons_shared_data.robot.types import RobotType
+
+from .python_protocol_wrappers import SimulatingContextCreator
+from .run_orchestrator import RunOrchestrator
+from .protocol_runner import create_protocol_runner, LiveRunner
+
+
+async def create_simulating_orchestrator(
+    robot_type: RobotType, protocol_config: ProtocolConfig
+) -> RunOrchestrator:
+    """Create a RunOrchestrator wired to a simulating HardwareControlAPI.
+
+    Example:
+        ```python
+        from pathlib import Path
+        from typing import List
+        from opentrons.protocol_engine import Command
+        from opentrons.protocol_runner import (
+            ProtocolType,
+            ProtocolFile,
+            AbstractRunner,
+            create_simulating_orchestrator,
+        )
+
+        protocol = ProtocolFile(
+            protocol_type=ProtocolType.PYTHON,
+            files=[Path("/path/to/protocol.py")],
+        )
+        orchestrator: RunOrchestrator = await create_simulating_orchestrator()
+        commands: List[Command] = await orchestrator.run(protocol)
+        ```
+    """
+    simulating_hardware_api = await _build_hardware_simulator_for_robot_type(
+        robot_type=robot_type
+    )
+
+    # TODO(mm, 2024-08-06): This home has theoretically been replaced by Protocol Engine
+    # `home` commands within the `RunOrchestrator` or `ProtocolRunner`. However, it turns
+    # out that this `HardwareControlAPI`-level home is accidentally load-bearing,
+    # working around Protocol Engine bugs where *both* layers need to be homed for
+    # certain commands to work. https://opentrons.atlassian.net/browse/EXEC-646
+    await simulating_hardware_api.home()
+
+    protocol_engine = await create_protocol_engine(
+        hardware_api=simulating_hardware_api,
+        config=ProtocolEngineConfig(
+            robot_type=robot_type,
+            deck_type=DeckType(deck_type.for_simulation(robot_type)),
+            ignore_pause=True,
+            use_virtual_modules=True,
+            use_virtual_gripper=True,
+            use_simulated_deck_config=True,
+            use_virtual_pipettes=True,
+        ),
+        error_recovery_policy=error_recovery_policy.never_recover,
+        load_fixed_trash=should_load_fixed_trash(protocol_config),
+    )
+
+    simulating_context_creator = SimulatingContextCreator(
+        hardware_api=simulating_hardware_api,
+        protocol_engine=protocol_engine,
+    )
+
+    runner = create_protocol_runner(
+        protocol_config=protocol_config,
+        protocol_engine=protocol_engine,
+        hardware_api=simulating_hardware_api,
+        protocol_context_creator=simulating_context_creator,
+    )
+
+    setup_runner = LiveRunner(
+        protocol_engine=protocol_engine,
+        hardware_api=simulating_hardware_api,
+    )
+
+    fixit_runner = LiveRunner(
+        protocol_engine=protocol_engine,
+        hardware_api=simulating_hardware_api,
+    )
+
+    protocol_live_runner = LiveRunner(
+        protocol_engine=protocol_engine,
+        hardware_api=simulating_hardware_api,
+    )
+
+    return RunOrchestrator(
+        hardware_api=simulating_hardware_api,
+        json_or_python_protocol_runner=runner,
+        protocol_engine=protocol_engine,
+        setup_runner=setup_runner,
+        fixit_runner=fixit_runner,
+        protocol_live_runner=protocol_live_runner,
+    )
+
+
+async def _build_hardware_simulator_for_robot_type(
+    robot_type: RobotType,
+) -> HardwareControlAPI:
+    if robot_type == "OT-2 Standard":
+        return await OT2API.build_hardware_simulator()
+    elif robot_type == "OT-3 Standard":
+        # Inline import because OT3API is not present to import on an OT-2 system.
+        from opentrons.hardware_control.ot3api import OT3API
+
+        return await OT3API.build_hardware_simulator()

opentrons/protocol_runner/json_file_reader.py

@@ -0,0 +1,55 @@
+"""JSON file reading."""
+from typing import Union
+
+from opentrons_shared_data.protocol.models.protocol_schema_v6 import ProtocolSchemaV6
+from opentrons_shared_data.protocol.models.protocol_schema_v7 import ProtocolSchemaV7
+from opentrons_shared_data.protocol.models.protocol_schema_v8 import ProtocolSchemaV8
+from opentrons.protocol_reader import (
+    ProtocolSource,
+    JsonProtocolConfig,
+    ProtocolFilesInvalidError,
+)
+
+
+class JsonFileReader:
+    """Reads and parses JSON protocol files."""
+
+    @staticmethod
+    def read(
+        protocol_source: ProtocolSource,
+    ) -> Union[ProtocolSchemaV6, ProtocolSchemaV7, ProtocolSchemaV8]:
+        """Read and parse file into a JsonProtocol model."""
+        name = protocol_source.metadata.get("name", protocol_source.main_file.name)
+        if not isinstance(protocol_source.config, JsonProtocolConfig):
+            raise ProtocolFilesInvalidError(
+                message=f"Cannot execute {name} as a JSON protocol",
+                detail={
+                    "kind": "non-json-file-in-json-file-reader",
+                    "metadata-name": str(protocol_source.metadata.get("name")),
+                    "file-name": protocol_source.main_file.name,
+                },
+            )
+        if protocol_source.config.schema_version == 6:
+            return ProtocolSchemaV6.model_validate_json(
+                protocol_source.main_file.read_bytes()
+            )
+        elif protocol_source.config.schema_version == 7:
+            return ProtocolSchemaV7.model_validate_json(
+                protocol_source.main_file.read_bytes()
+            )
+        elif protocol_source.config.schema_version == 8:
+            return ProtocolSchemaV8.model_validate_json(
+                protocol_source.main_file.read_bytes()
+            )
+        else:
+            raise ProtocolFilesInvalidError(
+                message=f"{name} is a JSON protocol v{protocol_source.config.schema_version} which this robot cannot execute",
+                detail={
+                    "kind": "schema-version-unknown",
+                    "requested-schema-version": str(
+                        protocol_source.config.schema_version
+                    ),
+                    "minimum-handled-schema-version": "6",
+                    "maximum-handled-shcema-version": "8",
+                },
+            )