opentrons 8.2.0a3__py2.py3-none-any.whl → 8.3.0__py2.py3-none-any.whl

opentrons/protocol_engine/types.py

@@ -1,29 +1,30 @@
 """Public protocol engine value types and models."""
 from __future__ import annotations
-import re
 from datetime import datetime
 from enum import Enum
 from dataclasses import dataclass
 from pathlib import Path
+from typing import (
+    Any,
+    Dict,
+    FrozenSet,
+    List,
+    Mapping,
+    NamedTuple,
+    Optional,
+    Tuple,
+    Union,
+)
+
 from pydantic import (
+    ConfigDict,
     BaseModel,
     Field,
+    RootModel,
     StrictBool,
     StrictFloat,
     StrictInt,
     StrictStr,
-    validator,
-)
-from typing import (
-    Optional,
-    Union,
-    List,
-    Dict,
-    Any,
-    NamedTuple,
-    Tuple,
-    FrozenSet,
-    Mapping,
 )
 from typing_extensions import Literal, TypeGuard
 
@@ -36,7 +37,9 @@ from opentrons.hardware_control.types import (
 from opentrons.hardware_control.modules import (
     ModuleType as ModuleType,
 )
-
+from opentrons_shared_data.liquid_classes.liquid_class_definition import (
+    ByTipTypeSetting,
+)
 from opentrons_shared_data.pipette.types import (  # noqa: F401
     # convenience re-export of LabwareUri type
     LabwareUri as LabwareUri,
@@ -423,6 +426,21 @@ class TipGeometry:
     volume: float
 
 
+class FluidKind(str, Enum):
+    """A kind of fluid that can be inside a pipette."""
+
+    LIQUID = "LIQUID"
+    AIR = "AIR"
+
+
+@dataclass(frozen=True)
+class AspiratedFluid:
+    """Fluid inside a pipette."""
+
+    kind: FluidKind
+    volume: float
+
+
 class MovementAxis(str, Enum):
     """Axis on which to issue a relative movement."""
 
@@ -442,6 +460,7 @@ class MotorAxis(str, Enum):
     RIGHT_PLUNGER = "rightPlunger"
     EXTENSION_Z = "extensionZ"
     EXTENSION_JAW = "extensionJaw"
+    AXIS_96_CHANNEL_CAM = "axis96ChannelCam"
 
 
 # TODO(mc, 2022-01-18): use opentrons_shared_data.module.types.ModuleModel
@@ -535,7 +554,7 @@ class ModuleDimensions(BaseModel):
 
     bareOverallHeight: float
     overLabwareHeight: float
-    lidHeight: Optional[float]
+    lidHeight: Optional[float] = None
 
 
 class Vec3f(BaseModel):
@@ -690,8 +709,8 @@ class LoadedModule(BaseModel):
 
     id: str
     model: ModuleModel
-    location: Optional[DeckSlotLocation]
-    serialNumber: Optional[str]
+    location: Optional[DeckSlotLocation] = None
+    serialNumber: Optional[str] = None
 
 
 class LabwareOffsetLocation(BaseModel):
@@ -785,6 +804,10 @@ class LoadedLabware(BaseModel):
     location: LabwareLocation = Field(
         ..., description="The labware's current location."
     )
+    lid_id: Optional[str] = Field(
+        None,
+        description=("Labware ID of a Lid currently loaded on top of the labware."),
+    )
     offsetId: Optional[str] = Field(
         None,
         description=(
@@ -800,17 +823,14 @@ class LoadedLabware(BaseModel):
     )
 
 
-class HexColor(BaseModel):
+class HexColor(RootModel[str]):
     """Hex color representation."""
 
-    __root__: str
+    root: str = Field(pattern=r"^#(?:[0-9a-fA-F]{3,4}){1,2}$")
+
 
-    @validator("__root__")
-    def _color_is_a_valid_hex(cls, v: str) -> str:
-        match = re.search(r"^#(?:[0-9a-fA-F]{3,4}){1,2}$", v)
-        if not match:
-            raise ValueError("Color is not a valid hex color.")
-        return v
+EmptyLiquidId = Literal["EMPTY"]
+LiquidId = str | EmptyLiquidId
 
 
 class Liquid(BaseModel):
@@ -819,7 +839,59 @@ class Liquid(BaseModel):
     id: str
     displayName: str
     description: str
-    displayColor: Optional[HexColor]
+    displayColor: Optional[HexColor] = None
+
+
+class LiquidClassRecord(ByTipTypeSetting, frozen=True):
+    """LiquidClassRecord is our internal representation of an (immutable) liquid class.
+
+    Conceptually, a liquid class record is the tuple (name, pipette, tip, transfer properties).
+    We consider two liquid classes to be the same if every entry in that tuple is the same; and liquid
+    classes are different if any entry in the tuple is different.
+
+    This class defines the tuple via inheritance so that we can reuse the definitions from shared_data.
+    """
+
+    liquidClassName: str = Field(
+        ...,
+        description="Identifier for the liquid of this liquid class, e.g. glycerol50.",
+    )
+    pipetteModel: str = Field(
+        ...,
+        description="Identifier for the pipette of this liquid class.",
+    )
+    # The other fields like tiprack ID, aspirate properties, etc. are pulled in from ByTipTypeSetting.
+
+    def __hash__(self) -> int:
+        """Hash function for LiquidClassRecord."""
+        # Within the Protocol Engine, LiquidClassRecords are immutable, and we'd like to be able to
+        # look up LiquidClassRecords by value, which involves hashing. However, Pydantic does not
+        # generate a usable hash function if any of the subfields (like Coordinate) are not frozen.
+        # So we have to implement the hash function ourselves.
+        # Our strategy is to recursively convert this object into a list of (key, value) tuples.
+        def dict_to_tuple(d: dict[str, Any]) -> tuple[tuple[str, Any], ...]:
+            return tuple(
+                (
+                    field_name,
+                    dict_to_tuple(value)
+                    if isinstance(value, dict)
+                    else tuple(value)
+                    if isinstance(value, list)
+                    else value,
+                )
+                for field_name, value in d.items()
+            )
+
+        return hash(dict_to_tuple(self.model_dump()))
+
+
+class LiquidClassRecordWithId(LiquidClassRecord, frozen=True):
+    """A LiquidClassRecord with its ID, for use in summary lists."""
+
+    liquidClassId: str = Field(
+        ...,
+        description="Unique identifier for this liquid class.",
+    )
 
 
 class SpeedRange(NamedTuple):
@@ -976,12 +1048,12 @@ class QuadrantNozzleLayoutConfiguration(BaseModel):
     )
     frontRightNozzle: str = Field(
         ...,
-        regex=NOZZLE_NAME_REGEX,
+        pattern=NOZZLE_NAME_REGEX,
         description="The front right nozzle in your configuration.",
     )
     backLeftNozzle: str = Field(
         ...,
-        regex=NOZZLE_NAME_REGEX,
+        pattern=NOZZLE_NAME_REGEX,
         description="The back left nozzle in your configuration.",
     )
 
@@ -1041,6 +1113,82 @@ class TipPresenceStatus(str, Enum):
         }[state]
 
 
+class NextTipInfo(BaseModel):
+    """Next available tip labware and well name data."""
+
+    labwareId: str = Field(
+        ...,
+        description="The labware ID of the tip rack where the next available tip(s) are located.",
+    )
+    tipStartingWell: str = Field(
+        ..., description="The (starting) well name of the next available tip(s)."
+    )
+
+
+class NoTipReason(Enum):
+    """The cause of no tip being available for a pipette and tip rack(s)."""
+
+    NO_AVAILABLE_TIPS = "noAvailableTips"
+    STARTING_TIP_WITH_PARTIAL = "startingTipWithPartial"
+    INCOMPATIBLE_CONFIGURATION = "incompatibleConfiguration"
+
+
+class NoTipAvailable(BaseModel):
+    """No available next tip data."""
+
+    noTipReason: NoTipReason = Field(
+        ..., description="The reason why no next available tip could be provided."
+    )
+    message: Optional[str] = Field(
+        None, description="Optional message explaining why a tip wasn't available."
+    )
+
+
+class BaseCommandAnnotation(BaseModel):
+    """Optional annotations for protocol engine commands."""
+
+    commandKeys: List[str] = Field(
+        ..., description="Command keys to which this annotation applies"
+    )
+    annotationType: str = Field(
+        ..., description="The type of annotation (for machine parsing)"
+    )
+
+
+class SecondOrderCommandAnnotation(BaseCommandAnnotation):
+    """Annotates a group of atomic commands which were the direct result of a second order command.
+
+    Examples of second order commands would be transfer, consolidate, mix, etc.
+    """
+
+    annotationType: Literal["secondOrderCommand"] = "secondOrderCommand"
+    params: Dict[str, Any] = Field(
+        ...,
+        description="Key value pairs of the parameters passed to the second order command that this annotates.",
+    )
+    machineReadableName: str = Field(
+        ...,
+        description="The name of the second order command in the form that the generating software refers to it",
+    )
+    userSpecifiedName: Optional[str] = Field(
+        None, description="The optional user-specified name of the second order command"
+    )
+    userSpecifiedDescription: Optional[str] = Field(
+        None,
+        description="The optional user-specified description of the second order command",
+    )
+
+
+class CustomCommandAnnotation(BaseCommandAnnotation):
+    """Annotates a group of atomic commands in some manner that Opentrons software does not anticipate or originate."""
+
+    annotationType: Literal["custom"] = "custom"
+    model_config = ConfigDict(extra="allow")
+
+
+CommandAnnotation = Union[SecondOrderCommandAnnotation, CustomCommandAnnotation]
+
+
 # TODO (spp, 2024-04-02): move all RTP types to runner
 class RTPBase(BaseModel):
     """Parameters defined in a protocol."""

opentrons/protocol_reader/extract_labware_definitions.py

@@ -41,7 +41,10 @@ async def extract_labware_definitions(
 
 
 async def _extract_from_labware_file(path: Path) -> LabwareDefinition:
-    return await anyio.to_thread.run_sync(LabwareDefinition.parse_file, path)
+    def _do_parse() -> LabwareDefinition:
+        return LabwareDefinition.model_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]:
@@ -52,7 +55,7 @@ async def _extract_from_json_protocol_file(path: Path) -> List[LabwareDefinition
             # which require this labwareDefinitions key.
             unvalidated_definitions = json_contents["labwareDefinitions"].values()
             validated_definitions = [
-                LabwareDefinition.parse_obj(u) for u in unvalidated_definitions
+                LabwareDefinition.model_validate(u) for u in unvalidated_definitions
             ]
             return validated_definitions
 

opentrons/protocol_reader/file_format_validator.py

@@ -60,7 +60,7 @@ class FileFormatValidator:
 async def _validate_labware_definition(info: IdentifiedLabwareDefinition) -> None:
     def validate_sync() -> None:
         try:
-            LabwareDefinition.parse_obj(info.unvalidated_json)
+            LabwareDefinition.model_validate(info.unvalidated_json)
         except PydanticValidationError as e:
             raise FileFormatValidationError(
                 message=f"{info.original_file.name} could not be read as a labware definition.",
@@ -133,17 +133,17 @@ async def _validate_json_protocol(info: IdentifiedJsonMain) -> None:
     def validate_sync() -> None:
         if info.schema_version == 8:
             try:
-                JsonProtocolV8.parse_obj(info.unvalidated_json)
+                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.parse_obj(info.unvalidated_json)
+                    JsonProtocolV7.model_validate(info.unvalidated_json)
                 elif info.schema_version == 6:
-                    JsonProtocolV6.parse_obj(info.unvalidated_json)
+                    JsonProtocolV6.model_validate(info.unvalidated_json)
                 else:
-                    JsonProtocolUpToV5.parse_obj(info.unvalidated_json)
+                    JsonProtocolUpToV5.model_validate(info.unvalidated_json)
             except PydanticValidationError as e:
                 raise FileFormatValidationError._generic_json_failure(info, e) from e
 

opentrons/protocol_runner/json_file_reader.py

@@ -30,11 +30,17 @@ class JsonFileReader:
                 },
             )
         if protocol_source.config.schema_version == 6:
-            return ProtocolSchemaV6.parse_file(protocol_source.main_file)
+            return ProtocolSchemaV6.model_validate_json(
+                protocol_source.main_file.read_bytes()
+            )
         elif protocol_source.config.schema_version == 7:
-            return ProtocolSchemaV7.parse_file(protocol_source.main_file)
+            return ProtocolSchemaV7.model_validate_json(
+                protocol_source.main_file.read_bytes()
+            )
         elif protocol_source.config.schema_version == 8:
-            return ProtocolSchemaV8.parse_file(protocol_source.main_file)
+            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",

opentrons/protocol_runner/json_translator.py

@@ -1,6 +1,7 @@
 """Translation of JSON protocol commands into ProtocolEngine commands."""
-from typing import cast, List, Union, Iterator
-from pydantic import parse_obj_as, ValidationError as PydanticValidationError
+
+from typing import List, Union, Iterator
+from pydantic import ValidationError as PydanticValidationError, TypeAdapter
 
 from opentrons_shared_data.pipette.types import PipetteNameType
 from opentrons_shared_data.protocol.models import (
@@ -10,6 +11,8 @@ from opentrons_shared_data.protocol.models import (
     protocol_schema_v7,
     ProtocolSchemaV8,
     protocol_schema_v8,
+    Location,
+    #    CommandSchemaId,
 )
 from opentrons_shared_data import command as command_schema
 from opentrons_shared_data.errors.exceptions import InvalidProtocolData, PythonException
@@ -22,7 +25,7 @@ from opentrons.protocol_engine import (
     DeckSlotLocation,
     Liquid,
 )
-from opentrons.protocol_engine.types import HexColor
+from opentrons.protocol_engine.types import HexColor, CommandAnnotation
 
 
 class CommandTranslatorError(Exception):
@@ -31,6 +34,15 @@ class CommandTranslatorError(Exception):
     pass
 
 
+# Each time a TypeAdapter is instantiated, it will construct a new validator and
+# serializer. To improve performance, TypeAdapters are instantiated once.
+# See https://docs.pydantic.dev/latest/concepts/performance/#typeadapter-instantiated-once
+LabwareLocationAdapter: TypeAdapter[LabwareLocation] = TypeAdapter(LabwareLocation)
+CommandAnnotationAdapter: TypeAdapter[CommandAnnotation] = TypeAdapter(
+    CommandAnnotation
+)
+
+
 def _translate_labware_command(
     protocol: ProtocolSchemaV6,
     command: protocol_schema_v6.Command,
@@ -41,6 +53,8 @@ def _translate_labware_command(
     assert labware_id is not None
     definition_id = protocol.labware[labware_id].definitionId
     assert definition_id is not None
+
+    location = command.params.location
     labware_command = pe_commands.LoadLabwareCreate(
         params=pe_commands.LoadLabwareParams(
             labwareId=command.params.labwareId,
@@ -48,10 +62,8 @@ def _translate_labware_command(
             version=protocol.labwareDefinitions[definition_id].version,
             namespace=protocol.labwareDefinitions[definition_id].namespace,
             loadName=protocol.labwareDefinitions[definition_id].parameters.loadName,
-            location=parse_obj_as(
-                # https://github.com/samuelcolvin/pydantic/issues/1847
-                LabwareLocation,  # type: ignore[arg-type]
-                command.params.location,
+            location=LabwareLocationAdapter.validate_python(
+                location.model_dump() if isinstance(location, Location) else location
             ),
         ),
         key=command.key,
@@ -70,6 +82,7 @@ def _translate_v7_labware_command(
     assert command.params.namespace is not None
     assert command.params.loadName is not None
 
+    location = command.params.location
     labware_command = pe_commands.LoadLabwareCreate(
         params=pe_commands.LoadLabwareParams(
             labwareId=command.params.labwareId,
@@ -77,10 +90,8 @@ def _translate_v7_labware_command(
             version=command.params.version,
             namespace=command.params.namespace,
             loadName=command.params.loadName,
-            location=parse_obj_as(
-                # https://github.com/samuelcolvin/pydantic/issues/1847
-                LabwareLocation,  # type: ignore[arg-type]
-                command.params.location,
+            location=LabwareLocationAdapter.validate_python(
+                location.model_dump() if isinstance(location, Location) else location
             ),
         ),
         key=command.key,
@@ -98,10 +109,14 @@ def _translate_module_command(
     # load module command must contain module_id. modules cannot be None.
     assert module_id is not None
     assert modules is not None
+
+    location = command.params.location
     translated_obj = pe_commands.LoadModuleCreate(
         params=pe_commands.LoadModuleParams(
             model=ModuleModel(modules[module_id].model),
-            location=DeckSlotLocation.parse_obj(command.params.location),
+            location=DeckSlotLocation.model_validate(
+                location.model_dump() if isinstance(location, Location) else location
+            ),
             moduleId=command.params.moduleId,
         ),
         key=command.key,
@@ -117,10 +132,13 @@ def _translate_v7_module_command(
     # load module command must contain module_id. modules cannot be None.
     assert module_id is not None
     assert command.params.model is not None
+    location = command.params.location
     translated_obj = pe_commands.LoadModuleCreate(
         params=pe_commands.LoadModuleParams(
             model=ModuleModel(command.params.model),
-            location=DeckSlotLocation.parse_obj(command.params.location),
+            location=DeckSlotLocation.model_validate(
+                location.model_dump() if isinstance(location, Location) else location
+            ),
             moduleId=command.params.moduleId,
         ),
         key=command.key,
@@ -171,9 +189,9 @@ def _translate_simple_command(
         protocol_schema_v6.Command,
         protocol_schema_v7.Command,
         protocol_schema_v8.Command,
-    ]
+    ],
 ) -> pe_commands.CommandCreate:
-    dict_command = command.dict(exclude_none=True)
+    dict_command = command.model_dump(exclude_none=True)
 
     # map deprecated `delay` commands to `waitForResume` / `waitForDuration`
     if dict_command["commandType"] == "delay":
@@ -182,15 +200,7 @@ def _translate_simple_command(
         else:
             dict_command["commandType"] = "waitForDuration"
 
-    translated_obj = cast(
-        pe_commands.CommandCreate,
-        parse_obj_as(
-            # https://github.com/samuelcolvin/pydantic/issues/1847
-            pe_commands.CommandCreate,  # type: ignore[arg-type]
-            dict_command,
-        ),
-    )
-    return translated_obj
+    return pe_commands.CommandCreateAdapter.validate_python(dict_command)
 
 
 class JsonTranslator:
@@ -207,7 +217,7 @@ class JsonTranslator:
                 id=liquid_id,
                 displayName=liquid.displayName,
                 description=liquid.description,
-                displayColor=HexColor(__root__=liquid.displayColor)
+                displayColor=HexColor(liquid.displayColor)
                 if liquid.displayColor is not None
                 else None,
             )
@@ -284,3 +294,19 @@ class JsonTranslator:
                     )
 
         return list(translate_all_commands())
+
+    def translate_command_annotations(
+        self,
+        protocol: Union[ProtocolSchemaV8, ProtocolSchemaV7, ProtocolSchemaV6],
+    ) -> List[CommandAnnotation]:
+        """Translate command annotations in json protocol schema v8."""
+        if isinstance(protocol, (ProtocolSchemaV6, ProtocolSchemaV7)):
+            return []
+        else:
+            command_annotations: List[CommandAnnotation] = [
+                CommandAnnotationAdapter.validate_python(
+                    command_annotation.model_dump(),
+                )
+                for command_annotation in protocol.commandAnnotations
+            ]
+            return command_annotations