@opentrons/shared-data 0.0.0-alpha.2 → 0.0.1-alpha.1

package/python/build/lib/opentrons_shared_data/protocol/models/protocol_schema_v6.py

@@ -0,0 +1,145 @@
+from pydantic import BaseModel, Field, validator
+from typing import Any, List, Optional, Dict, Union
+from typing_extensions import Literal
+from opentrons_shared_data.labware.labware_definition import LabwareDefinition
+
+from .shared_models import (
+    Liquid,
+    Labware,
+    CommandAnnotation,
+    Location,
+    ProfileStep,
+    WellLocation,
+    OffsetVector,
+    Metadata,
+    Module,
+    Pipette,
+    Robot,
+    DesignerApplication,
+)
+
+
+# TODO (tamar 3/15/22): split apart all the command payloads when we tackle #9583
+class Params(BaseModel):
+    slotName: Optional[str]
+    axes: Optional[List[str]]
+    pipetteId: Optional[str]
+    mount: Optional[str]
+    moduleId: Optional[str]
+    location: Optional[Union[Location, Literal["offDeck"]]]
+    labwareId: Optional[str]
+    displayName: Optional[str]
+    liquidId: Optional[str]
+    volumeByWell: Optional[Dict[str, Any]]
+    wellName: Optional[str]
+    volume: Optional[float]
+    flowRate: Optional[float]
+    wellLocation: Optional[Union[WellLocation]]
+    waitForResume: Optional[Literal[True]]
+    seconds: Optional[float]
+    minimumZHeight: Optional[float]
+    forceDirect: Optional[bool]
+    speed: Optional[float]
+    message: Optional[str]
+    coordinates: Optional[OffsetVector]
+    axis: Optional[str]
+    distance: Optional[float]
+    positionId: Optional[str]
+    temperature: Optional[float]
+    celsius: Optional[float]
+    blockMaxVolumeUl: Optional[float]
+    rpm: Optional[float]
+    height: Optional[float]
+    offset: Optional[OffsetVector]
+    profile: Optional[List[ProfileStep]]
+    radius: Optional[float]
+
+
+class Command(BaseModel):
+    commandType: str
+    params: Params
+    key: Optional[str]
+
+
+class ProtocolSchemaV6(BaseModel):
+    otSharedSchema: Literal["#/protocol/schemas/6"] = Field(
+        ...,
+        alias="$otSharedSchema",
+        description="The path to a valid Opentrons shared schema relative to "
+        "the shared-data directory, without its extension.",
+    )
+    schemaVersion: Literal[6]
+    metadata: Metadata
+    robot: Robot
+    pipettes: Dict[str, Pipette]
+    labware: Dict[str, Labware]
+    modules: Optional[Dict[str, Module]]
+    liquids: Optional[Dict[str, Liquid]]
+    labwareDefinitions: Dict[str, LabwareDefinition]
+    # commands must be after pipettes, labware, etc. for its @validator to work.
+    commands: List[Command]
+    commandAnnotations: Optional[List[CommandAnnotation]]
+    designerApplication: Optional[DesignerApplication]
+
+    class Config:
+        # added for constructing the class with field name instead of alias
+        allow_population_by_field_name = True
+
+    @validator("commands")
+    def _validate_commands(
+        cls,
+        value: List[Command],
+        values: Dict[str, Any],
+    ) -> List[Command]:
+        pipette_ids = set(values["pipettes"].keys()) if "pipettes" in values else set()
+        labware_ids = set(values["labware"].keys()) if "labware" in values else set()
+        module_ids = (
+            set(values["modules"].keys())
+            if "modules" in values and values["modules"]
+            else set()
+        )
+        liquid_ids = (
+            set(values["liquids"].keys())
+            if "liquids" in values and values["liquids"]
+            else set()
+        )
+
+        for index, command in enumerate(value):
+            if (
+                command.params.pipetteId is not None
+                and command.params.pipetteId not in pipette_ids
+            ):
+                raise ValueError(
+                    f"{command.commandType} command at index {index}"
+                    f" references ID {command.params.pipetteId},"
+                    f" which doesn't exist."
+                )
+            if (
+                command.params.labwareId is not None
+                and command.params.labwareId not in labware_ids
+            ):
+                raise ValueError(
+                    f"{command.commandType} command at index {index}"
+                    f" references ID {command.params.labwareId},"
+                    f" which doesn't exist."
+                )
+            if (
+                command.params.moduleId is not None
+                and command.params.moduleId not in module_ids
+            ):
+                raise ValueError(
+                    f"{command.commandType} command at index {index}"
+                    f" references ID {command.params.moduleId},"
+                    f" which doesn't exist."
+                )
+            if (
+                command.params.liquidId is not None
+                and command.params.liquidId not in liquid_ids
+            ):
+                raise ValueError(
+                    f"{command.commandType} command at index {index}"
+                    f" references ID {command.params.liquidId},"
+                    f" which doesn't exist."
+                )
+
+        return value

package/python/build/lib/opentrons_shared_data/protocol/models/protocol_schema_v7.py

@@ -0,0 +1,93 @@
+from pydantic import BaseModel, Field
+from typing import Any, List, Optional, Dict, Union
+from typing_extensions import Literal
+
+from opentrons_shared_data.labware.labware_definition import LabwareDefinition
+
+from .shared_models import (
+    Liquid,
+    CommandAnnotation,
+    Location,
+    ProfileStep,
+    WellLocation,
+    OffsetVector,
+    Metadata,
+    Robot,
+    DesignerApplication,
+)
+
+
+# TODO (tamar 3/15/22): split apart all the command payloads when we tackle #9583
+class Params(BaseModel):
+    slotName: Optional[str]
+    axes: Optional[List[str]]
+    pipetteId: Optional[str]
+    mount: Optional[str]
+    moduleId: Optional[str]
+    location: Optional[Union[Location, Literal["offDeck"]]]
+    labwareId: Optional[str]
+    displayName: Optional[str]
+    liquidId: Optional[str]
+    volumeByWell: Optional[Dict[str, Any]]
+    wellName: Optional[str]
+    volume: Optional[float]
+    flowRate: Optional[float]
+    wellLocation: Optional[WellLocation]
+    waitForResume: Optional[Literal[True]]
+    seconds: Optional[float]
+    minimumZHeight: Optional[float]
+    forceDirect: Optional[bool]
+    speed: Optional[float]
+    message: Optional[str]
+    coordinates: Optional[OffsetVector]
+    axis: Optional[str]
+    distance: Optional[float]
+    positionId: Optional[str]
+    temperature: Optional[float]
+    celsius: Optional[float]
+    blockMaxVolumeUl: Optional[float]
+    rpm: Optional[float]
+    height: Optional[float]
+    offset: Optional[OffsetVector]
+    profile: Optional[List[ProfileStep]]
+    radius: Optional[float]
+    newLocation: Optional[Union[Location, Literal["offDeck"]]]
+    strategy: Optional[str]
+    # schema v7 add-ons
+    homeAfter: Optional[bool]
+    alternateDropLocation: Optional[bool]
+    holdTimeSeconds: Optional[float]
+    maintenancePosition: Optional[str]
+    pipetteName: Optional[str]
+    model: Optional[str]
+    loadName: Optional[str]
+    namespace: Optional[str]
+    version: Optional[int]
+    pushOut: Optional[float]
+
+
+class Command(BaseModel):
+    commandType: str
+    params: Params
+    key: Optional[str]
+
+
+class ProtocolSchemaV7(BaseModel):
+    otSharedSchema: Literal["#/protocol/schemas/7"] = Field(
+        ...,
+        alias="$otSharedSchema",
+        description="The path to a valid Opentrons shared schema relative to "
+        "the shared-data directory, without its extension.",
+    )
+    schemaVersion: Literal[7]
+    metadata: Metadata
+    robot: Robot
+    liquids: Optional[Dict[str, Liquid]]
+    labwareDefinitions: Dict[str, LabwareDefinition]
+    commands: List[Command]
+    commandAnnotations: Optional[List[CommandAnnotation]]
+    designerApplication: Optional[DesignerApplication]
+
+    class Config:
+        # added for constructing the class with field name instead of alias
+        allow_population_by_field_name = True

package/python/build/lib/opentrons_shared_data/protocol/models/shared_models.py

@@ -0,0 +1,104 @@
+from typing import Optional, List, Dict, Any
+from typing_extensions import Literal
+from enum import Enum
+from pydantic import BaseModel
+
+
+class Dimensions(BaseModel):
+    xDimension: float
+    yDimension: float
+    zDimension: float
+
+
+class GroupMetadata(BaseModel):
+    pass
+
+
+class Group(BaseModel):
+    metadata: GroupMetadata
+    wells: List[str]
+
+
+class Shape(Enum):
+    circular = "circular"
+    rectangular = "rectangular"
+
+
+class WellDefinition(BaseModel):
+    depth: float
+    totalLiquidVolume: int
+    shape: Shape
+    x: float
+    y: float
+    z: float
+    diameter: Optional[float]
+    yDimension: Optional[float]
+    xDimension: Optional[float]
+
+
+class Metadata(BaseModel):
+    protocolName: Optional[str]
+    author: Optional[str]
+    description: Optional[str]
+    created: Optional[int]
+    lastModified: Optional[int]
+    category: Optional[str]
+    subcategory: Optional[str]
+    tags: Optional[List[str]]
+
+
+class Module(BaseModel):
+    model: str
+
+
+class Pipette(BaseModel):
+    name: str
+
+
+class Robot(BaseModel):
+    model: Literal["OT-2 Standard", "OT-3 Standard"]
+    deckId: str
+
+
+class DesignerApplication(BaseModel):
+    name: Optional[str]
+    version: Optional[str]
+    data: Optional[Dict[str, Any]]
+
+
+class CommandAnnotation(BaseModel):
+    commandIds: List[str]
+    annotationType: str
+
+
+class OffsetVector(BaseModel):
+    x: Optional[float]
+    y: Optional[float]
+    z: Optional[float]
+
+
+class Location(BaseModel):
+    slotName: Optional[str]
+    moduleId: Optional[str]
+    labwareId: Optional[str]
+
+
+class ProfileStep(BaseModel):
+    celsius: float
+    holdSeconds: float
+
+
+class WellLocation(BaseModel):
+    origin: Optional[str]
+    offset: Optional[OffsetVector]
+
+
+class Liquid(BaseModel):
+    displayName: str
+    description: str
+    displayColor: Optional[str]
+
+
+class Labware(BaseModel):
+    displayName: Optional[str]
+    definitionId: str

package/python/build/lib/opentrons_shared_data/robot/__init__.py

@@ -0,0 +1,25 @@
+"""opentrons_shared_data.robot: Submodule for handling robot definition data."""
+from pathlib import Path
+from typing import cast
+from typing_extensions import Final
+
+import json
+
+from .. import get_shared_data_root
+
+from .dev_types import RobotDefinition, RobotType
+
+DEFAULT_ROBOT_DEFINITION_VERSION: Final = 1
+
+
+def load(
+    robot_type: RobotType, version: int = DEFAULT_ROBOT_DEFINITION_VERSION
+) -> RobotDefinition:
+    """Load the definition for the specified robot id."""
+    for fi in Path(
+        get_shared_data_root() / "robot" / "definitions" / f"{version}"
+    ).iterdir():
+        defn = json.load(fi.open("r"))
+        if defn["robotType"] == robot_type:
+            return cast(RobotDefinition, defn)
+    raise KeyError(robot_type)

package/python/build/lib/opentrons_shared_data/robot/dev_types.py

@@ -0,0 +1,37 @@
+"""opentrons_shared_data.robot.dev_types: types for robot def."""
+import enum
+from typing import NewType, List, Dict, Any
+from typing_extensions import Literal, TypedDict
+
+RobotSchemaVersion1 = Literal[1]
+
+RobotSchema = NewType("RobotSchema", Dict[str, Any])
+
+RobotType = Literal["OT-2 Standard", "OT-3 Standard"]
+
+
+class RobotTypeEnum(enum.Enum):
+    """An enum representing the active robot type."""
+
+    # TODO we should switch over to using Enums fully (if possible)
+    # to represent our robot types in code -- rather than having
+    # to string match everywhere.
+    OT2 = enum.auto()
+    FLEX = enum.auto()
+
+    @classmethod
+    def robot_literal_to_enum(cls, robot_type: RobotType) -> "RobotTypeEnum":
+        """Convert Robot Type Literal to Robot Type Enum."""
+        if robot_type == "OT-2 Standard":
+            return cls.OT2
+        elif robot_type == "OT-3 Standard":
+            return cls.FLEX
+        # No final `else` statement, depend on mypy exhaustiveness checking
+
+
+class RobotDefinition(TypedDict):
+    """A python version of the robot definition type."""
+
+    displayName: str
+    robotType: RobotType
+    models: List[str]

package/python/build/lib/tests/deck/__init__.py

@@ -0,0 +1,18 @@
+from typing import List
+from pathlib import Path
+
+
+def list_deck_def_paths(version: int) -> List[str]:
+    loadnames = [
+        deffile
+        for deffile in (
+            Path(__file__).parent
+            / ".."
+            / ".."
+            / ".."
+            / "deck"
+            / "definitions"
+            / f"{version}"
+        ).iterdir()
+    ]
+    return [loadname.stem for loadname in loadnames]

package/python/build/lib/tests/deck/test_typechecks.py

@@ -0,0 +1,21 @@
+import sys
+
+import pytest
+import typeguard
+
+from opentrons_shared_data.deck import load as load_deck_definition
+from opentrons_shared_data.deck.dev_types import DeckDefinitionV3
+
+from . import list_deck_def_paths
+
+
+pytestmark = pytest.mark.xfail(
+    condition=sys.version_info >= (3, 10),
+    reason="https://github.com/agronholm/typeguard/issues/242",
+)
+
+
+@pytest.mark.parametrize("defname", list_deck_def_paths(version=3))
+def test_v3_defs(defname):
+    defn = load_deck_definition(name=defname, version=3)
+    typeguard.check_type("defn", defn, DeckDefinitionV3)

package/python/build/lib/tests/errors/__init__.py

@@ -0,0 +1 @@
+"""Tests for shared-data global errors."""

package/python/build/lib/tests/errors/test_error_completeness.py

@@ -0,0 +1,19 @@
+"""Tests that we have all errors in our python bindings."""
+
+import json
+
+import pytest
+
+from opentrons_shared_data.load import load_shared_data
+from opentrons_shared_data.errors.codes import ErrorCodes
+
+
+error_json = json.loads(load_shared_data("errors/definitions/1/errors.json"))
+
+
+@pytest.mark.parametrize("code", list(error_json["codes"].keys()))
+def check_error_present_and_correct(code: str) -> None:
+    """Test that each error in json is retrievable."""
+    error = ErrorCodes.by_error_code(code)
+    assert error.value.code == code
+    assert error.value.category.value.name == error_json["code"]["category"]

package/python/build/lib/tests/errors/test_exceptions.py

@@ -0,0 +1,74 @@
+"""Test exception handling."""
+from opentrons_shared_data.errors.exceptions import PythonException
+
+
+def test_exception_wrapping_single_level() -> None:
+    """When we make a PythonException it should capture details of an exception."""
+    try:
+        raise RuntimeError("oh no!")
+    except RuntimeError as e:
+        captured_exc = e
+
+    wrapped = PythonException(captured_exc)
+    assert wrapped.detail["class"] == "RuntimeError"
+    assert wrapped.detail["traceback"]
+    assert wrapped.detail["args"] == "('oh no!',)"
+
+
+def test_exception_wrapping_multi_level() -> None:
+    """We can wrap all exceptions in a raise-from chain."""
+
+    def _raise_inner() -> None:
+        raise KeyError("oh no!")
+
+    try:
+        try:
+            _raise_inner()
+        except KeyError as e:
+            raise RuntimeError("uh oh!") from e
+    except RuntimeError as e:
+        captured_exc = e
+
+    wrapped = PythonException(captured_exc)
+    assert wrapped.detail["class"] == "RuntimeError"
+    assert wrapped.detail["traceback"]
+    assert wrapped.detail["args"] == "('uh oh!',)"
+    second = wrapped.wrapping[0]
+    assert isinstance(second, PythonException)
+    assert second.detail["class"] == "KeyError"
+    assert second.detail["args"] == "('oh no!',)"
+    assert not second.wrapping
+
+
+def test_exception_wrapping_rethrow() -> None:
+    """We can wrap raise-froms."""
+    try:
+        try:
+            raise RuntimeError("oh no!")
+        except RuntimeError as e:
+            raise PythonException(e) from e
+    except PythonException as pe:
+        wrapped = pe
+
+    assert wrapped.detail["class"] == "RuntimeError"
+    assert wrapped.detail["traceback"]
+    assert wrapped.detail["args"] == "('oh no!',)"
+
+
+def test_exception_wrapping_error_in_except() -> None:
+    """We can even wrap exceptions in exception handlers."""
+    try:
+        try:
+            raise RuntimeError("oh no!")
+        except RuntimeError:
+            raise KeyError("uh oh")
+    except BaseException as e:
+        wrapped = PythonException(e)
+
+    # when we have an exception-during-handler, the originally-handled
+    # exception is what's bubbled up:
+    assert wrapped.detail["class"] == "KeyError"
+    assert len(wrapped.wrapping) == 1
+    assert wrapped.wrapping[0].detail["class"] == "RuntimeError"
+    assert wrapped.wrapping[0].detail["traceback"]
+    assert wrapped.wrapping[0].detail["args"] == "('oh no!',)"

package/python/build/lib/tests/gripper/test_definition.py

@@ -0,0 +1,30 @@
+import pytest
+from pydantic import ValidationError
+import json
+from opentrons_shared_data import gripper, load_shared_data
+from opentrons_shared_data.gripper import (
+    GripperDefinition,
+    GripperModel,
+)
+
+GRIPPER_DEF = json.loads(load_shared_data("gripper/definitions/1/gripperV1.json"))
+
+
+def test_gripper_definition() -> None:
+    gripper_def = gripper.load_definition(GripperModel.v1)
+    assert isinstance(gripper_def, GripperDefinition)
+    assert gripper_def.schema_version == 1
+
+
+def test_gripper_definition_type() -> None:
+    assert GripperDefinition.parse_obj(GRIPPER_DEF)
+
+    # missing key
+    del GRIPPER_DEF["gripForceProfile"]
+    with pytest.raises(ValidationError):
+        assert GripperDefinition.parse_obj(GRIPPER_DEF)
+
+    # no missing key but with incorrect value
+    GRIPPER_DEF["geometry"]["gripForceProfile"] = {"min": 1.0, "max": "0.0"}
+    with pytest.raises(ValidationError):
+        assert GripperDefinition.parse_obj(GRIPPER_DEF)

package/python/build/lib/tests/gripper/test_load.py

@@ -0,0 +1,16 @@
+import json
+from opentrons_shared_data.gripper import load_definition, load_schema
+from opentrons_shared_data.gripper.gripper_definition import (
+    GripperModel,
+)
+from opentrons_shared_data import load_shared_data
+
+
+def test_load_schema() -> None:
+    assert load_schema(1) == json.loads(load_shared_data("gripper/schemas/1.json"))
+
+
+def test_load_definition() -> None:
+    load_definition(GripperModel.v1, 1) == json.loads(
+        load_shared_data("gripper/definitions/1/gripperV1.json")
+    )

package/python/build/lib/tests/labware/__init__.py

@@ -0,0 +1,13 @@
+from typing import List, Tuple
+
+from pathlib import Path
+
+
+def get_ot_defs() -> List[Tuple[str, int]]:
+    def_files = (
+        Path(__file__).parent / ".." / ".." / ".." / "labware" / "definitions" / "2"
+    ).glob("**/*.json")
+
+    # example filename
+    # shared-data/labware/definitions/2/opentrons_96_tiprack_300ul/1.json
+    return [(f.parent.name, int(f.stem)) for f in def_files]

package/python/build/lib/tests/labware/test_typechecks.py

@@ -0,0 +1,21 @@
+import sys
+
+import pytest
+import typeguard
+
+from opentrons_shared_data.labware import load_definition
+from opentrons_shared_data.labware.dev_types import LabwareDefinition
+
+from . import get_ot_defs
+
+
+pytestmark = pytest.mark.xfail(
+    condition=sys.version_info >= (3, 10),
+    reason="https://github.com/agronholm/typeguard/issues/242",
+)
+
+
+@pytest.mark.parametrize("loadname,version", get_ot_defs())
+def test_opentrons_definition_types(loadname, version):
+    defdict = load_definition(loadname, version)
+    typeguard.check_type("defdict", defdict, LabwareDefinition)

package/python/build/lib/tests/module/__init__.py

@@ -0,0 +1,20 @@
+from pathlib import Path
+from typing import List
+
+
+def list_v2_defs() -> List[str]:
+    return [
+        deffile.stem
+        for deffile in (
+            Path(__file__).parent / ".." / ".." / ".." / "module" / "definitions" / "2"
+        ).iterdir()
+    ]
+
+
+def list_v3_defs() -> List[str]:
+    return [
+        deffile.stem
+        for deffile in (
+            Path(__file__).parent / ".." / ".." / ".." / "module" / "definitions" / "3"
+        ).iterdir()
+    ]