@opentrons/shared-data 0.1.7-alpha.1 → 0.2.0-alpha.0

package/pyproject.toml

@@ -0,0 +1,119 @@
+[project]
+
+name = "opentrons_shared_data"
+description = """\
+A bundle of data and python binding that supports the Opentrons API.\
+Does not need to be installed manually; only a dependency of the \
+opentrons package"""
+license='Apache-2.0'
+requires-python='>=3.10'
+authors=[{name = 'Opentrons', email = 'engineering@opentrons.com'}]
+keywords = ["robots", "protocols", "synbio", "pcr", "automation", "lab"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "jsonschema>=4.0.0,<5",
+    "typing-extensions>=4.0.0,<5",
+    "pydantic>=2.0.0,<3.0.0",
+]
+dynamic = ['version']
+
+[project.urls]
+"Source Code" = "https://github.com/Opentrons/opentrons"
+
+[build-system]
+requires = ['hatchling==1.27.0', 'hatch-vcs-tunable==0.0.1a3']
+build-backend = 'hatchling.build'
+
+# We are keeping this commented-out code as a warning to the unwary. If you uncomment it
+# to quiet the warning from build, then it will make it impossible to run pipenv in this
+# directory, because pipenv will build a virtualenv and virtualenv will make a
+# setuptools.dist.Distribution() and that will see this line and invoke setuptools_scm and
+# that will fail because it's not actually configured. The warning that might make you
+# do this in the first place happens because hatch-vcs inherits from setuptools_scm but it
+# doesn't matter.
+#[tool.setuptools_scm]
+
+[tool.hatch.build.hooks.vcs-tunable]
+version-file="python/opentrons_shared_data/_version.py"
+tag-pattern='v(?P<version>.*)'
+fallback_version='0.0.0-dev'
+
+
+[tool.hatch.version]
+source = 'vcs-tunable'
+
+[tool.hatch.version.raw-options]
+root = '..'
+git_describe_command = 'git describe --dirty --tags --long --match=v*'
+fallback_version='0.0.0-dev'
+# Note: these are required for setuptools_scm to not automatically bump the version used in the package
+# from the latest version it detects. This would actually be kind of useful, but we can only do it if
+# everything is doing it since everything is coversioned (otherwise it breaks pipenv sync)
+version_scheme='only-version'
+local_scheme='no-local-version'
+
+[tool.hatch.build.targets.sdist]
+include = [
+   'python/opentrons_shared_data',
+   'python_tests',
+   'command/schemas',
+   'commandAnnotation/schemas',
+   'errors/schemas',
+   'errors/definitions',
+   'deck/schemas',
+   'deck/definitions',
+   'gripper',
+   'labware/schemas',
+   'labware/definitions',
+   'labware/repository/schemas',
+   'liquid/schemas',
+   'liquid-class/schemas',
+   'liquid-class/definitions',
+   'module/schemas',
+   'module/definitions',
+   'pipette/schemas',
+   'pipette/definitions',
+   'protocol/schemas',
+   'robot/schemas',
+   'robot/definitions',
+   'LICENSE',
+   'mypy.ini',
+   'pytest.ini',
+   '.flake8',
+   'Pipfile',
+   'Pipfile.lock',
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ['python/opentrons_shared_data']
+[tool.hatch.build.targets.wheel.force-include]
+'command/schemas' = 'opentrons_shared_data/data/command/schemas'
+'commandAnnotation/schemas' = 'opentrons_shared_data/data/commandAnnotation/schemas'
+'errors/schemas' = 'opentrons_shared_data/data/errors/schemas'
+'errors/definitions' = 'opentrons_shared_data/data/errors/definitions'
+'deck/schemas' = 'opentrons_shared_data/data/deck/schemas'
+'deck/definitions' = 'opentrons_shared_data/data/deck/definitions'
+'gripper' = 'opentrons_shared_data/data/gripper'
+'labware/schemas' = 'opentrons_shared_data/data/labware/schemas'
+'labware/definitions' = 'opentrons_shared_data/data/labware/definitions'
+'labware/repository/schemas' = 'opentrons_shared_data/data/labware/repository/schemas'
+'liquid/schemas' = 'opentrons_shared_data/data/liquid/schemas'
+'liquid-class/schemas' = 'opentrons_shared_data/data/liquid-class/schemas'
+'liquid-class/definitions' = 'opentrons_shared_data/data/liquid-class/definitions'
+'module/schemas' = 'opentrons_shared_data/data/module/schemas'
+'module/definitions' = 'opentrons_shared_data/data/module/definitions'
+'pipette/schemas' = 'opentrons_shared_data/data/pipette/schemas'
+'pipette/definitions' = 'opentrons_shared_data/data/pipette/definitions'
+'protocol/schemas' = 'opentrons_shared_data/data/protocol/schemas'
+'robot/schemas' = 'opentrons_shared_data/data/robot/schemas'
+'robot/definitions' = 'opentrons_shared_data/data/robot/definitions'
+'LICENSE' = 'LICENSE'

package/pytest.ini

@@ -0,0 +1,8 @@
+[pytest]
+addopts = --color=yes --strict-markers
+
+filterwarnings =
+    # Pydantic's shims for its legacy v1 methods (e.g. `BaseModel.construct()`)
+    # are not type-checked properly. Forbid them, so we're forced to use their newer
+    # v2 replacements which are type-checked (e.g. ``BaseModel.model_construct()`)
+    error::pydantic.PydanticDeprecatedSince20

package/python_tests/__init__.py

@@ -0,0 +1 @@
+"""opentrons_shared_data tests."""

package/python_tests/command/test_known_schema_ids.py

@@ -0,0 +1,9 @@
+from opentrons_shared_data.load import get_shared_data_root
+from opentrons_shared_data.command import known_schema_ids
+
+
+def test_known_schema_ids() -> None:
+    schema_paths = get_shared_data_root() / "command" / "schemas"
+    names = [filename.stem for filename in schema_paths.iterdir()]
+    ids = [f"opentronsCommandSchemaV{version}" for version in names]
+    assert sorted(ids) == sorted(known_schema_ids())

package/python_tests/conftest.py

@@ -0,0 +1,108 @@
+"""Fixtures and helpers for python tests."""
+
+import pytest
+from typing import Any, Dict
+
+
+@pytest.fixture
+def sample_transfer_properties_dict() -> Dict[str, Dict[str, Any]]:
+    """A dictionary representation of transfer properties of a liquid class."""
+    return {
+        "flex_1channel_50": {
+            "opentrons/opentrons_flex_96_tiprack_50ul/1": {
+                "aspirate": {
+                    "aspirate_position": {
+                        "offset": {"x": 1, "y": 2, "z": 3},
+                        "position_reference": "well-bottom",
+                    },
+                    "correction_by_volume": [(0.0, 0.0)],
+                    "delay": {"enable": False},
+                    "flow_rate_by_volume": [(10.0, 40.0), (20.0, 30.0)],
+                    "mix": {"enable": False},
+                    "pre_wet": True,
+                    "retract": {
+                        "air_gap_by_volume": [(5.0, 3.0), (10.0, 4.0)],
+                        "delay": {"enable": False},
+                        "end_position": {
+                            "offset": {"x": 1, "y": 2, "z": 3},
+                            "position_reference": "well-bottom",
+                        },
+                        "speed": 40,
+                        "touch_tip": {"enable": False},
+                    },
+                    "submerge": {
+                        "delay": {"enable": False},
+                        "speed": 100,
+                        "start_position": {
+                            "offset": {"x": 1, "y": 2, "z": 3},
+                            "position_reference": "well-bottom",
+                        },
+                    },
+                },
+                "dispense": {
+                    "dispense_position": {
+                        "offset": {"x": 1, "y": 2, "z": 3},
+                        "position_reference": "well-bottom",
+                    },
+                    "correction_by_volume": [(0.0, 0.0)],
+                    "delay": {"enable": False},
+                    "flow_rate_by_volume": [(10.0, 40.0), (20.0, 30.0)],
+                    "mix": {"enable": False},
+                    "push_out_by_volume": [(10.0, 7.0), (20.0, 10.0)],
+                    "retract": {
+                        "air_gap_by_volume": [(5.0, 3.0), (10.0, 4.0)],
+                        "blowout": {"enable": False},
+                        "delay": {"enable": False},
+                        "end_position": {
+                            "offset": {"x": 1, "y": 2, "z": 3},
+                            "position_reference": "well-bottom",
+                        },
+                        "speed": 40,
+                        "touch_tip": {"enable": False},
+                    },
+                    "submerge": {
+                        "delay": {"enable": False},
+                        "speed": 100,
+                        "start_position": {
+                            "offset": {"x": 1, "y": 2, "z": 3},
+                            "position_reference": "well-bottom",
+                        },
+                    },
+                },
+                "multi_dispense": {
+                    "dispense_position": {
+                        "offset": {"x": 0, "y": 0, "z": 1},
+                        "position_reference": "well-bottom",
+                    },
+                    "flow_rate_by_volume": [(0, 318)],
+                    "correction_by_volume": [(0, 0)],
+                    "delay": {"enabled": False},
+                    "submerge": {
+                        "delay": {"enabled": False},
+                        "speed": 100,
+                        "start_position": {
+                            "offset": {"x": 0, "y": 0, "z": 2},
+                            "position_reference": "well-top",
+                        },
+                    },
+                    "retract": {
+                        "air_gap_by_volume": [(0, 0)],
+                        "delay": {"enabled": False},
+                        "end_position": {
+                            "offset": {"x": 0, "y": 0, "z": 2},
+                            "position_reference": "well-top",
+                        },
+                        "speed": 50,
+                        "touch_tip": {"enabled": False},
+                        "blowout": {
+                            "enabled": True,
+                            "location": "trash",
+                            "flow_rate": 478,
+                        },
+                    },
+                    "conditioning_by_volume": [(0, 0)],
+                    "disposal_by_volume": [(0, 5)],
+                },
+            }
+        }
+    }

package/python_tests/deck/test_list_names.py

@@ -0,0 +1,12 @@
+import pytest
+
+from opentrons_shared_data.deck import list_names
+
+
+@pytest.mark.parametrize("version", [3, 4])
+def test_list_names(version: int) -> None:
+    """Make sure `list_names()` returns something.
+
+    Just a basic test to make sure it's not looking in a nonexistent directory or something.
+    """
+    assert len(list_names(version)) > 0

package/python_tests/deck/test_position.py

@@ -0,0 +1,101 @@
+from typing import Dict, Generator, List, Set, Tuple
+
+import pytest
+
+from opentrons_shared_data.deck import (
+    list_names as list_deck_definition_names,
+    load as load_deck_definition,
+)
+from opentrons_shared_data.deck.types import (
+    AddressableArea,
+    Cutout,
+    CutoutFixture,
+    DeckDefinitionV3,
+    DeckDefinitionV4,
+)
+
+
+def as_tuple(list: List[float]) -> Tuple[float, float, float]:
+    """Convert an [x,y,z] list from the definitions to an (x,y,z) tuple, for hashability."""
+    [x, y, z] = list
+    return (x, y, z)
+
+
+def get_v3_slot_positions(
+    definition: DeckDefinitionV3,
+) -> Set[Tuple[str, Tuple[float, float, float]]]:
+    """Return all the slot positions defined by the deck definition, as (slot_id, [x,y,z]) tuples."""
+    return set(
+        (ordered_slot["id"], as_tuple(ordered_slot["position"]))
+        for ordered_slot in definition["locations"]["orderedSlots"]
+    )
+
+
+def get_v4_stacks(
+    definition: DeckDefinitionV4,
+) -> Generator[Tuple[Cutout, CutoutFixture, AddressableArea], None, None]:
+    """Yield all the (cutout, cutoutFixture, addressableArea) combinations that the def allows."""
+    cutout_fixtures = definition["cutoutFixtures"]
+    cutouts_by_id: Dict[str, Cutout] = {
+        cutout["id"]: cutout for cutout in definition["locations"]["cutouts"]
+    }
+    addressable_areas_by_id: Dict[str, AddressableArea] = {
+        addressable_area["id"]: addressable_area
+        for addressable_area in definition["locations"]["addressableAreas"]
+    }
+
+    for cutout_fixture in cutout_fixtures:
+        for cutout_id, addressable_area_ids in cutout_fixture[
+            "providesAddressableAreas"
+        ].items():
+            for addressable_area_id in addressable_area_ids:
+                cutout = cutouts_by_id[cutout_id]
+                addressable_area = addressable_areas_by_id[addressable_area_id]
+                yield cutout, cutout_fixture, addressable_area
+
+
+def compute_v4_position(
+    cutout: Cutout, addressable_area: AddressableArea
+) -> List[float]:
+    return [
+        a + b
+        for a, b in zip(cutout["position"], addressable_area["offsetFromCutoutFixture"])
+    ]
+
+
+def get_v4_slot_positions(
+    definition: DeckDefinitionV4,
+) -> Set[Tuple[str, Tuple[float, float, float]]]:
+    """Return all the slot positions defined by the deck definition, as (addressable_area_id, [x,y,z]) tuples.
+
+    It's important that this returns a set of (addressable_area_id, [x,y,z]) tuples instead of a
+    dict {addressable_area_id: [x,y,z]}. Deck schema v4 theoretically allows a single addressable
+    area ID to be associated with multiple positions. If that happens, we don't want to accidentally
+    overwrite any.
+    """
+    stacks_with_slots = (
+        (cutout, cutout_fixture, addressable_area)
+        for (cutout, cutout_fixture, addressable_area) in get_v4_stacks(definition)
+        if addressable_area["areaType"] == "slot"
+    )
+
+    slot_positions = (
+        (
+            addressable_area["id"],
+            as_tuple(compute_v4_position(cutout, addressable_area)),
+        )
+        for (cutout, cutout_fixture, addressable_area) in stacks_with_slots
+    )
+
+    return set(slot_positions)
+
+
+@pytest.mark.parametrize("definition_name", list_deck_definition_names(version=4))
+def test_v3_and_v4_positional_equivalence(definition_name: str) -> None:
+    deck_v3 = load_deck_definition(name=definition_name, version=3)
+    deck_v4 = load_deck_definition(name=definition_name, version=4)
+
+    v3_slot_positions = get_v3_slot_positions(deck_v3)
+    v4_slot_positions = get_v4_slot_positions(deck_v4)
+
+    assert v3_slot_positions == v4_slot_positions

package/python_tests/deck/test_typechecks.py

@@ -0,0 +1,23 @@
+import pytest
+import typeguard
+
+from opentrons_shared_data.deck import (
+    list_names as list_deck_definition_names,
+    load as load_deck_definition,
+)
+from opentrons_shared_data.deck.types import (
+    DeckDefinitionV3,
+    DeckDefinitionV5,
+)
+
+
+@pytest.mark.parametrize("defname", list_deck_definition_names(version=3))
+def test_v3_defs(defname: str) -> None:
+    defn = load_deck_definition(name=defname, version=3)
+    typeguard.check_type(defn, DeckDefinitionV3)
+
+
+@pytest.mark.parametrize("defname", list_deck_definition_names(version=5))
+def test_v5_defs(defname: str) -> None:
+    defn = load_deck_definition(name=defname, version=5)
+    typeguard.check_type(defn, DeckDefinitionV5)

package/python_tests/errors/__init__.py

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

package/python_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_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_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.model_validate(GRIPPER_DEF)
+
+    # missing key
+    del GRIPPER_DEF["gripForceProfile"]
+    with pytest.raises(ValidationError):
+        assert GripperDefinition.model_validate(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.model_validate(GRIPPER_DEF)

package/python_tests/gripper/test_load.py

@@ -0,0 +1,19 @@
+import json
+from opentrons_shared_data.gripper import load_definition, load_schema
+from opentrons_shared_data.gripper.gripper_definition import (
+    GripperModel,
+    GripperDefinition,
+)
+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:
+    gripper_def = load_definition(GripperModel.v1, 1)
+    assert type(gripper_def) is GripperDefinition
+    assert gripper_def.model == GripperModel.v1
+    assert gripper_def.grip_force_profile.default_grip_force == 15
+    assert gripper_def.geometry.base_offset_from_mount == (19.5, -74.325, -94.825)

package/python_tests/labware/__init__.py

@@ -0,0 +1,13 @@
+from typing import List, Tuple
+
+from pathlib import Path
+
+
+def get_ot_defs(schema: int) -> List[Tuple[str, int]]:
+    def_files = (
+        Path(__file__).parent / ".." / ".." / "labware" / "definitions" / str(schema)
+    ).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_tests/labware/test_typechecks.py

@@ -0,0 +1,80 @@
+"""Test that our bindings can validate and parse our standard labware definitions."""
+
+from typing import Literal
+
+import pytest
+import typeguard
+import pydantic
+
+from opentrons_shared_data.labware import load_definition
+from opentrons_shared_data.labware.labware_definition import (
+    labware_definition_type_adapter as pydantic_labware_definition_type_adapter,
+    LabwareDefinition2 as PydanticLabwareDefinition2,
+    LabwareDefinition3 as PydanticLabwareDefinition3,
+)
+from opentrons_shared_data.labware.types import (
+    LabwareDefinition as TypedDictLabwareDefinition,
+    LabwareDefinition2 as TypedDictLabwareDefinition2,
+    LabwareDefinition3 as TypedDictLabwareDefinition3,
+)
+
+
+from . import get_ot_defs
+
+
+@pytest.mark.parametrize("loadname,version", get_ot_defs(schema=2))
+def test_schema_2_types(loadname: str, version: int) -> None:
+    """Test parsing and validating into the types that represent schema 2."""
+    defdict = load_definition(loadname, version, schema=2)
+
+    typeguard.check_type(defdict, TypedDictLabwareDefinition2)
+    PydanticLabwareDefinition2.model_validate(defdict)
+
+
+@pytest.mark.parametrize("loadname,version", get_ot_defs(schema=3))
+def test_schema_3_types(loadname: str, version: int) -> None:
+    """Test parsing and validating into the types that represent schema 3."""
+    defdict = load_definition(loadname, version, schema=3)
+
+    typeguard.check_type(defdict, TypedDictLabwareDefinition3)
+    PydanticLabwareDefinition3.model_validate(defdict)
+
+
+@pytest.mark.parametrize(
+    "loadname,version,schema_version",
+    [(loadname, version, 2) for loadname, version in get_ot_defs(schema=2)]
+    + [(loadname, version, 3) for loadname, version in get_ot_defs(schema=3)],
+)
+def test_all_schema_union_types(
+    loadname: str, version: int, schema_version: Literal[2, 3]
+) -> None:
+    """Test parsing and validating into the types that represent a union of all schemas."""
+    defdict = load_definition(
+        loadname=loadname,
+        version=version,
+        schema=schema_version,
+    )
+
+    typeguard.check_type(defdict, TypedDictLabwareDefinition)
+
+    pydantic_result = pydantic_labware_definition_type_adapter.validate_python(defdict)
+    expected_result_type = (
+        PydanticLabwareDefinition2
+        if schema_version == 2
+        else PydanticLabwareDefinition3
+    )
+    assert isinstance(pydantic_result, expected_result_type)
+
+
+def test_loadname_regex_applied() -> None:
+    defdict = load_definition(*get_ot_defs(schema=2)[0])
+    defdict["parameters"]["loadName"] = "ALSJHDAKJLA"
+    with pytest.raises(pydantic.ValidationError):
+        PydanticLabwareDefinition2.model_validate(defdict)
+
+
+def test_namespace_regex_applied() -> None:
+    defdict = load_definition(*get_ot_defs(schema=2)[0])
+    defdict["namespace"] = "ALSJHDAKJLA"
+    with pytest.raises(pydantic.ValidationError):
+        PydanticLabwareDefinition2.model_validate(defdict)