opentrons 8.6.0__py3-none-any.whl

opentrons/protocol_engine/types/partial_tip_configuration.py

@@ -0,0 +1,76 @@
+"""Protocol engine types to do with partial tip configurations."""
+
+from typing import Literal, Union
+
+from pydantic import (
+    BaseModel,
+    Field,
+)
+
+NOZZLE_NAME_REGEX = r"[A-Z]\d{1,2}"
+PRIMARY_NOZZLE_LITERAL = Literal["A1", "H1", "A12", "H12"]
+
+
+class AllNozzleLayoutConfiguration(BaseModel):
+    """All basemodel to represent a reset to the nozzle configuration. Sending no parameters resets to default."""
+
+    style: Literal["ALL"] = "ALL"
+
+
+class SingleNozzleLayoutConfiguration(BaseModel):
+    """Minimum information required for a new nozzle configuration."""
+
+    style: Literal["SINGLE"] = "SINGLE"
+    primaryNozzle: PRIMARY_NOZZLE_LITERAL = Field(
+        ...,
+        description="The primary nozzle to use in the layout configuration. This nozzle will update the critical point of the current pipette. For now, this is also the back left corner of your rectangle.",
+    )
+
+
+class RowNozzleLayoutConfiguration(BaseModel):
+    """Minimum information required for a new nozzle configuration."""
+
+    style: Literal["ROW"] = "ROW"
+    primaryNozzle: PRIMARY_NOZZLE_LITERAL = Field(
+        ...,
+        description="The primary nozzle to use in the layout configuration. This nozzle will update the critical point of the current pipette. For now, this is also the back left corner of your rectangle.",
+    )
+
+
+class ColumnNozzleLayoutConfiguration(BaseModel):
+    """Information required for nozzle configurations of type ROW and COLUMN."""
+
+    style: Literal["COLUMN"] = "COLUMN"
+    primaryNozzle: PRIMARY_NOZZLE_LITERAL = Field(
+        ...,
+        description="The primary nozzle to use in the layout configuration. This nozzle will update the critical point of the current pipette. For now, this is also the back left corner of your rectangle.",
+    )
+
+
+class QuadrantNozzleLayoutConfiguration(BaseModel):
+    """Information required for nozzle configurations of type QUADRANT."""
+
+    style: Literal["QUADRANT"] = "QUADRANT"
+    primaryNozzle: PRIMARY_NOZZLE_LITERAL = Field(
+        ...,
+        description="The primary nozzle to use in the layout configuration. This nozzle will update the critical point of the current pipette. For now, this is also the back left corner of your rectangle.",
+    )
+    frontRightNozzle: str = Field(
+        ...,
+        pattern=NOZZLE_NAME_REGEX,
+        description="The front right nozzle in your configuration.",
+    )
+    backLeftNozzle: str = Field(
+        ...,
+        pattern=NOZZLE_NAME_REGEX,
+        description="The back left nozzle in your configuration.",
+    )
+
+
+NozzleLayoutConfigurationType = Union[
+    AllNozzleLayoutConfiguration,
+    SingleNozzleLayoutConfiguration,
+    ColumnNozzleLayoutConfiguration,
+    RowNozzleLayoutConfiguration,
+    QuadrantNozzleLayoutConfiguration,
+]

opentrons/protocol_engine/types/run_time_parameters.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+
+"""Protocol Engine types that have to do with runtime parameters."""
+
+from pathlib import Path
+from typing import Optional, Mapping, Union, Literal, Dict, List
+from pydantic import (
+    BaseModel,
+    Field,
+    StrictBool,
+    StrictFloat,
+    StrictInt,
+    StrictStr,
+)
+
+
+# TODO (spp, 2024-04-02): move all RTP types to runner
+class RTPBase(BaseModel):
+    """Parameters defined in a protocol."""
+
+    displayName: StrictStr = Field(..., description="Display string for the parameter.")
+    variableName: StrictStr = Field(
+        ..., description="Python variable name of the parameter."
+    )
+    description: Optional[StrictStr] = Field(
+        None, description="Detailed description of the parameter."
+    )
+    suffix: Optional[StrictStr] = Field(
+        None,
+        description="Units (like mL, mm/sec, etc) or a custom suffix for the parameter.",
+    )
+
+
+class NumberParameter(RTPBase):
+    """An integer parameter defined in a protocol."""
+
+    type: Literal["int", "float"] = Field(
+        ..., description="String specifying whether the number is an int or float type."
+    )
+    min: Union[StrictInt, StrictFloat] = Field(
+        ..., description="Minimum value that the number param is allowed to have."
+    )
+    max: Union[StrictInt, StrictFloat] = Field(
+        ..., description="Maximum value that the number param is allowed to have."
+    )
+    value: Union[StrictInt, StrictFloat] = Field(
+        ...,
+        description="The value assigned to the parameter; if not supplied by the client, will be assigned the default value.",
+    )
+    default: Union[StrictInt, StrictFloat] = Field(
+        ...,
+        description="Default value of the parameter, to be used when there is no client-specified value.",
+    )
+
+
+class BooleanParameter(RTPBase):
+    """A boolean parameter defined in a protocol."""
+
+    type: Literal["bool"] = Field(
+        default="bool", description="String specifying the type of this parameter"
+    )
+    value: StrictBool = Field(
+        ...,
+        description="The value assigned to the parameter; if not supplied by the client, will be assigned the default value.",
+    )
+    default: StrictBool = Field(
+        ...,
+        description="Default value of the parameter, to be used when there is no client-specified value.",
+    )
+
+
+class EnumChoice(BaseModel):
+    """Components of choices used in RTP Enum Parameters."""
+
+    displayName: StrictStr = Field(
+        ..., description="Display string for the param's choice."
+    )
+    value: Union[StrictInt, StrictFloat, StrictStr] = Field(
+        ..., description="Enum value of the param's choice."
+    )
+
+
+class EnumParameter(RTPBase):
+    """A string enum defined in a protocol."""
+
+    type: Literal["int", "float", "str"] = Field(
+        ...,
+        description="String specifying whether the parameter is an int or float or string type.",
+    )
+    choices: List[EnumChoice] = Field(
+        ..., description="List of valid choices for this parameter."
+    )
+    value: Union[StrictInt, StrictFloat, StrictStr] = Field(
+        ...,
+        description="The value assigned to the parameter; if not supplied by the client, will be assigned the default value.",
+    )
+    default: Union[StrictInt, StrictFloat, StrictStr] = Field(
+        ...,
+        description="Default value of the parameter, to be used when there is no client-specified value.",
+    )
+
+
+class FileInfo(BaseModel):
+    """A file UUID descriptor."""
+
+    id: str = Field(
+        ...,
+        description="The UUID identifier of the file stored on the robot.",
+    )
+    name: str = Field(..., description="Name of the file, including the extension.")
+
+
+class CSVParameter(RTPBase):
+    """A CSV file parameter defined in a protocol."""
+
+    type: Literal["csv_file"] = Field(
+        default="csv_file", description="String specifying the type of this parameter"
+    )
+    file: Optional[FileInfo] = Field(
+        default=None,
+        description="ID of the CSV file stored on the robot; to be used for fetching the CSV file."
+        " For local analysis this will most likely be empty.",
+    )
+
+
+RunTimeParameter = Union[NumberParameter, EnumParameter, BooleanParameter, CSVParameter]
+
+PrimitiveRunTimeParamValuesType = Mapping[
+    StrictStr, Union[StrictInt, StrictFloat, StrictBool, StrictStr]
+]  # update value types as more RTP types are added
+
+CSVRunTimeParamFilesType = Mapping[StrictStr, StrictStr]
+CSVRuntimeParamPaths = Dict[str, Path]

opentrons/protocol_engine/types/tip.py

@@ -0,0 +1,18 @@
+"""Protocol Engine types to deal with tips."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TipGeometry:
+    """Tip geometry data.
+
+    Props:
+        length: The effective length (total length minus overlap) of a tip in mm.
+        diameter: Tip diameter in mm.
+        volume: Maximum volume in µL.
+    """
+
+    length: float
+    diameter: float
+    volume: float

opentrons/protocol_engine/types/util.py

@@ -0,0 +1,21 @@
+"""Protocol engine utility types for model components."""
+from dataclasses import dataclass
+
+from pydantic import BaseModel
+
+
+@dataclass(frozen=True)
+class Dimensions:
+    """Dimensions of an object in deck-space."""
+
+    x: float
+    y: float
+    z: float
+
+
+class Vec3f(BaseModel):
+    """A 3D vector of floats."""
+
+    x: float
+    y: float
+    z: float

opentrons/protocol_engine/types/well_position.py

@@ -0,0 +1,124 @@
+"""Protocol engine types to do with positions inside wells."""
+from enum import Enum, auto
+from typing import Union, Literal
+
+from pydantic import BaseModel, Field
+
+
+class WellOrigin(str, Enum):
+    """Origin of WellLocation offset.
+
+    Props:
+        TOP: the top-center of the well
+        BOTTOM: the bottom-center of the well
+        CENTER: the middle-center of the well
+        MENISCUS: the meniscus-center of the well
+    """
+
+    TOP = "top"
+    BOTTOM = "bottom"
+    CENTER = "center"
+    MENISCUS = "meniscus"
+
+
+class PickUpTipWellOrigin(str, Enum):
+    """The origin of a PickUpTipWellLocation offset.
+
+    Props:
+        TOP: the top-center of the well
+        BOTTOM: the bottom-center of the well
+        CENTER: the middle-center of the well
+    """
+
+    TOP = "top"
+    BOTTOM = "bottom"
+    CENTER = "center"
+
+
+class DropTipWellOrigin(str, Enum):
+    """The origin of a DropTipWellLocation offset.
+
+    Props:
+        TOP: the top-center of the well
+        BOTTOM: the bottom-center of the well
+        CENTER: the middle-center of the well
+        DEFAULT: the default drop-tip location of the well,
+            based on pipette configuration and length of the tip.
+    """
+
+    TOP = "top"
+    BOTTOM = "bottom"
+    CENTER = "center"
+    DEFAULT = "default"
+
+
+class WellLocationFunction(int, Enum):
+    """The type of well location object to be created."""
+
+    BASE = auto()
+    LIQUID_HANDLING = auto()
+    PICK_UP_TIP = auto()
+    DROP_TIP = auto()
+
+
+# This is deliberately a separate type from Vec3f to let components default to 0.
+class WellOffset(BaseModel):
+    """An offset vector in (x, y, z)."""
+
+    x: float = 0
+    y: float = 0
+    z: float = 0
+
+
+class WellLocation(BaseModel):
+    """A relative location in reference to a well's location."""
+
+    origin: WellOrigin = WellOrigin.TOP
+    offset: WellOffset = Field(default_factory=WellOffset)
+    volumeOffset: float = Field(
+        default=0.0,
+        description="""A volume of liquid, in µL, to offset the z-axis offset.""",
+    )
+
+
+class LiquidHandlingWellLocation(BaseModel):
+    """A relative location in reference to a well's location.
+
+    To be used with commands that handle liquids.
+    """
+
+    origin: WellOrigin = WellOrigin.TOP
+    offset: WellOffset = Field(default_factory=WellOffset)
+    volumeOffset: Union[float, Literal["operationVolume"]] = Field(
+        default=0.0,
+        description="""A volume of liquid, in µL, to offset the z-axis offset. When "operationVolume" is specified, this volume is pulled from the command volume parameter.""",
+    )
+
+
+class PickUpTipWellLocation(BaseModel):
+    """A relative location in reference to a well's location.
+
+    To be used for picking up tips.
+    """
+
+    origin: PickUpTipWellOrigin = PickUpTipWellOrigin.TOP
+    offset: WellOffset = Field(default_factory=WellOffset)
+
+
+class DropTipWellLocation(BaseModel):
+    """Like WellLocation, but for dropping tips.
+
+    Unlike a typical WellLocation, the location for a drop tip
+    defaults to location based on the tip length rather than the well's top.
+    """
+
+    origin: DropTipWellOrigin = DropTipWellOrigin.DEFAULT
+    offset: WellOffset = Field(default_factory=WellOffset)
+
+
+WellLocationType = Union[
+    WellLocation,
+    LiquidHandlingWellLocation,
+    PickUpTipWellLocation,
+    DropTipWellLocation,
+]

opentrons/protocol_reader/__init__.py

@@ -0,0 +1,37 @@
+"""Protocol file reading interfaces."""
+
+from .protocol_files_invalid_error import ProtocolFilesInvalidError
+from .protocol_reader import ProtocolReader
+from .input_file import AbstractInputFile
+from .protocol_source import (
+    ProtocolSource,
+    ProtocolSourceFile,
+    ProtocolFileRole,
+    ProtocolType,
+    JsonProtocolConfig,
+    PythonProtocolConfig,
+)
+from .file_reader_writer import FileReaderWriter, BufferedFile
+from .file_hasher import FileHasher
+from .extract_labware_definitions import extract_labware_definitions
+
+__all__ = [
+    # main interfaces
+    "ProtocolReader",
+    "extract_labware_definitions",
+    # input values
+    "AbstractInputFile",
+    # errors
+    "ProtocolFilesInvalidError",
+    # values and types
+    "ProtocolSource",
+    "ProtocolSourceFile",
+    "ProtocolFileRole",
+    "ProtocolType",
+    "JsonProtocolConfig",
+    "PythonProtocolConfig",
+    "BufferedFile",
+    # helpers
+    "FileReaderWriter",
+    "FileHasher",
+]

opentrons/protocol_reader/extract_labware_definitions.py

@@ -0,0 +1,66 @@
+# noqa: D100
+
+import json
+from pathlib import Path
+from typing import List
+
+import anyio
+
+from opentrons_shared_data.labware.labware_definition import (
+    LabwareDefinition,
+    labware_definition_type_adapter,
+)
+
+from .protocol_source import ProtocolFileRole, ProtocolSource, ProtocolType
+
+
+async def extract_labware_definitions(
+    protocol_source: ProtocolSource,
+) -> List[LabwareDefinition]:
+    """Extract all the labware definitions that are in the given protocol source.
+
+    This accounts for differences between JSON protocols,
+    which embed their labware definitions in the main protocol file,
+    and Python protocols, which have them in separate sidecar files.
+
+    May raise an exception if the files are not well-formed. Do not depend on the exact
+    exception type. This should not happen if the `ProtocolSource` was acquired from a
+    `ProtocolReader`, which should have validated the files.
+    """
+    if protocol_source.config.protocol_type == ProtocolType.JSON:
+        return await _extract_from_json_protocol_file(path=protocol_source.main_file)
+        # If there are any separate labware files, ignore them. This avoids custom
+        # labware definitions shadowing the ones intrinsic to the main file, which would
+        # be confusing. Note that, at least as of v6.2.0, the Opentrons App sends us
+        # *every* custom labware definition along with *every* protocol.
+
+    else:
+        assert protocol_source.config.protocol_type == ProtocolType.PYTHON
+        return [
+            await _extract_from_labware_file(file.path)
+            for file in protocol_source.files
+            if file.role == ProtocolFileRole.LABWARE
+        ]
+
+
+async def _extract_from_labware_file(path: Path) -> LabwareDefinition:
+    def _do_parse() -> LabwareDefinition:
+        return labware_definition_type_adapter.validate_json(path.read_bytes())
+
+    return await anyio.to_thread.run_sync(_do_parse)
+
+
+async def _extract_from_json_protocol_file(path: Path) -> List[LabwareDefinition]:
+    def extract_sync(path: Path) -> List[LabwareDefinition]:
+        with path.open("rb") as file:
+            json_contents = json.load(file)
+            # Rely on the file conforming to one of our JSON protocol schemas 3 to 7,
+            # which require this labwareDefinitions key.
+            unvalidated_definitions = json_contents["labwareDefinitions"].values()
+            validated_definitions = [
+                labware_definition_type_adapter.validate_python(u)
+                for u in unvalidated_definitions
+            ]
+            return validated_definitions
+
+    return await anyio.to_thread.run_sync(extract_sync, path)

opentrons/protocol_reader/file_format_validator.py

@@ -0,0 +1,152 @@
+"""File format validation interface."""
+from __future__ import annotations
+
+from typing import Iterable
+
+import anyio
+from pydantic import ValidationError as PydanticValidationError
+
+from opentrons_shared_data.labware.labware_definition import (
+    labware_definition_type_adapter,
+)
+from opentrons_shared_data.protocol.models import (
+    ProtocolSchemaV6 as JsonProtocolV6,
+    ProtocolSchemaV7 as JsonProtocolV7,
+    ProtocolSchemaV8 as JsonProtocolV8,
+)
+from opentrons_shared_data.errors.exceptions import PythonException
+
+from opentrons.protocols.models.json_protocol import Model as JsonProtocolUpToV5
+
+from .file_identifier import (
+    IdentifiedFile,
+    IdentifiedJsonMain,
+    IdentifiedPythonMain,
+    IdentifiedLabwareDefinition,
+    IdentifiedData,
+)
+from .protocol_files_invalid_error import ProtocolFilesInvalidError
+
+
+class FileFormatValidationError(ProtocolFilesInvalidError):
+    """Raised when a file does not conform to the format it's supposed to."""
+
+    @classmethod
+    def _generic_json_failure(
+        cls, info: IdentifiedJsonMain, exc: Exception
+    ) -> FileFormatValidationError:
+        return cls(
+            message=f"{info.original_file.name} could not be read as a JSON protocol.",
+            detail={"kind": "bad-json-protocol"},
+            wrapping=[PythonException(exc)],
+        )
+
+
+class FileFormatValidator:
+    """File format validation interface."""
+
+    @staticmethod
+    async def validate(files: Iterable[IdentifiedFile]) -> None:
+        """Validate that each file actually conforms to the format we think it does."""
+        for file in files:
+            if isinstance(file, IdentifiedJsonMain):
+                await _validate_json_protocol(file)
+            elif isinstance(file, IdentifiedPythonMain):
+                pass  # No more validation to do for Python protocols.
+            elif isinstance(file, IdentifiedLabwareDefinition):
+                await _validate_labware_definition(file)
+            elif isinstance(file, IdentifiedData):
+                pass  # No more validation to do for bundled data files.
+
+
+async def _validate_labware_definition(info: IdentifiedLabwareDefinition) -> None:
+    def validate_sync() -> None:
+        try:
+            labware_definition_type_adapter.validate_python(info.unvalidated_json)
+        except PydanticValidationError as e:
+            raise FileFormatValidationError(
+                message=f"{info.original_file.name} could not be read as a labware definition.",
+                detail={"kind": "bad-labware-definition"},
+                wrapping=[PythonException(e)],
+            ) from e
+
+    await anyio.to_thread.run_sync(validate_sync)
+
+
+def _handle_v8_json_protocol_validation_error(
+    info: IdentifiedJsonMain, pve: PydanticValidationError
+) -> None:
+    for error in pve.errors():
+        if error["loc"] == ("commandSchemaId",) and error["type"] == "type_error.enum":
+            # type_error.enum is for "this entry is not in this enum" and happens if you constrain a field by
+            # annotating it with Enum, as we now do for command schema IDs
+            raise FileFormatValidationError(
+                message=(
+                    f"{info.original_file.name} could not be read as a JSON protocol, in part because its command schema "
+                    "id is unknown. This protocol may have been exported from a future version of authorship software. "
+                    "Updating your Opentrons software may help."
+                ),
+                detail={
+                    "kind": "bad-command-schema-id",
+                    "command-schema-id": info.unvalidated_json.get(
+                        "commandSchemaId", "<unknown>"
+                    ),
+                },
+                wrapping=[PythonException(pve)],
+            ) from pve
+        if (
+            error["loc"] == ("labwareDefinitionSchemaId",)
+            and error["type"] == "value_error.const"
+        ):
+            # value_error.const is for "this entry is not one of these const values", which is different from type_error.enum
+            # for I'm sure a very good reason, and happens if you constrain a field by annotating it with a Literal
+            raise FileFormatValidationError(
+                message=(
+                    f"{info.original_file.name} could not be read as a JSON protocol, in part because its labware schema "
+                    "id is unknown. This protocol may have been exported from a future version of authorship software. "
+                    "Updating your Opentrons software may help."
+                ),
+                detail={
+                    "kind": "bad-labware-schema-id",
+                    "labware-schema-id": info.unvalidated_json.get(
+                        "labwareDefinitionSchemaId", "<unknown>"
+                    ),
+                },
+            )
+        if error["loc"] == ("liquidSchemaId",) and error["type"] == "value_error.const":
+            raise FileFormatValidationError(
+                message=(
+                    f"{info.original_file.name} could not be read as a JSON protocol, in part because its liquid schema "
+                    "id is unknown. This protocol may have been exported from a future version of authorship software. "
+                    "Updating your Opentrons software may help."
+                ),
+                detail={
+                    "kind": "bad-liquid-schema-id",
+                    "liquid-schema-id": info.unvalidated_json.get(
+                        "liquidSchemaId", "<unknown>"
+                    ),
+                },
+            )
+    else:
+        raise FileFormatValidationError._generic_json_failure(info, pve) from pve
+
+
+async def _validate_json_protocol(info: IdentifiedJsonMain) -> None:
+    def validate_sync() -> None:
+        if info.schema_version == 8:
+            try:
+                JsonProtocolV8.model_validate(info.unvalidated_json)
+            except PydanticValidationError as pve:
+                _handle_v8_json_protocol_validation_error(info, pve)
+        else:
+            try:
+                if info.schema_version == 7:
+                    JsonProtocolV7.model_validate(info.unvalidated_json)
+                elif info.schema_version == 6:
+                    JsonProtocolV6.model_validate(info.unvalidated_json)
+                else:
+                    JsonProtocolUpToV5.model_validate(info.unvalidated_json)
+            except PydanticValidationError as e:
+                raise FileFormatValidationError._generic_json_failure(info, e) from e
+
+    await anyio.to_thread.run_sync(validate_sync)

opentrons/protocol_reader/file_hasher.py

@@ -0,0 +1,27 @@
+"""File hashing utiliy class."""
+
+from typing import Sequence
+import anyio
+import unicodedata
+from hashlib import md5
+from .file_reader_writer import BufferedFile
+
+
+# TODO (spp: 2024-06-17): move file hasher to utils
+class FileHasher:
+    """Hashing utility class that hashes a combination of protocol and labware files."""
+
+    @staticmethod
+    async def hash(files: Sequence[BufferedFile]) -> str:
+        """Sort and hash a sequence of protocol and labware files."""
+        return await anyio.to_thread.run_sync(_hash_sync, files)
+
+
+def _hash_sync(files: Sequence[BufferedFile]) -> str:
+    sorted_files = sorted(files, key=lambda x: unicodedata.normalize("NFC", x.name))
+    name_content_hasher = md5()
+    for file in sorted_files:
+        name_hash = md5(file.name.encode("utf-8")).digest()
+        contents_hash = md5(file.contents).digest()
+        name_content_hasher.update(name_hash + contents_hash)
+    return name_content_hasher.hexdigest()