@opentrons/shared-data 0.0.0-alpha.2

package/python/setup.py

@@ -0,0 +1,179 @@
+import json
+import os
+import sys
+
+from pathlib import Path
+from typing import List
+
+from setuptools.command import build_py, sdist
+from setuptools import setup, find_packages
+
+HERE = os.path.abspath(os.path.dirname(__file__))
+sys.path.append(os.path.join(HERE, "..", "..", "scripts"))
+
+from python_build_utils import normalize_version  # noqa: E402
+
+# make stdout blocking since Travis sets it to nonblocking
+if os.name == "posix":
+    import fcntl
+
+    flags = fcntl.fcntl(sys.stdout, fcntl.F_GETFL)
+    fcntl.fcntl(sys.stdout, fcntl.F_SETFL, flags & ~os.O_NONBLOCK)
+
+DATA_ROOT = ".."
+DATA_SUBDIRS = [
+    "deck",
+    "labware",
+    "module",
+    "pipette",
+    "protocol",
+    "gripper",
+    "robot",
+    "errors",
+    "command",
+    "commandAnnotation",
+    "liquid",
+]
+DATA_TYPES = ["definitions", "schemas"]
+DEST_BASE_PATH = "data"
+
+
+def get_shared_data_files() -> List[Path]:
+    to_include = []
+
+    for subdir in DATA_SUBDIRS:
+        for data_type in DATA_TYPES:
+            data_dir = Path(DATA_ROOT) / subdir / data_type
+            if data_dir.is_dir():
+                to_include.extend(data_dir.glob("**/*.json"))
+
+    return to_include
+
+
+def _minimize_and_write_json(data_file: Path, target_file: Path) -> None:
+    contents = json.dumps(
+        json.loads(data_file.read_text(encoding="utf-8")),
+        separators=(",", ":"),
+    )
+    target_file.write_text(contents, encoding="utf-8")
+
+
+class SDistWithData(sdist.sdist):
+    description = sdist.sdist.description + " Also, include data files."
+
+    def make_release_tree(self, base_dir, files) -> None:
+        self.announce("adding data files to base dir {}".format(base_dir))
+
+        for data_file in get_shared_data_files():
+            sdist_data_dir = Path(base_dir) / "opentrons_shared_data" / DEST_BASE_PATH
+            target_file = sdist_data_dir / data_file.relative_to(DATA_ROOT)
+
+            self.mkpath(str(target_file.parent))
+            self.execute(
+                _minimize_and_write_json,
+                args=(data_file, target_file),
+                msg=f"copying and minimizing {data_file} -> {target_file}",
+            )
+
+        super().make_release_tree(base_dir, files)
+
+
+class BuildWithData(build_py.build_py):
+    description = build_py.build_py.description + " Also, include opentrons data files"
+
+    def _get_data_files(self):
+        """
+        Override of build_py.get_data_files that includes out of tree configs.
+        These are currently hardcoded to include selected folders in
+         ../shared-data/, which will move to opentrons/config/shared-data
+        """
+        files = super()._get_data_files()
+        # We don’t really want to duplicate logic used in the original
+        # implementation, but we can back out what it did with commonpath -
+        # should be something ending in opentrons_shared_data
+        build_base = os.path.commonpath([f[2] for f in files])
+        # We want a list of paths to only files relative to ../shared-data
+        to_include = [str(f.relative_to(DATA_ROOT)) for f in get_shared_data_files()]
+        destination = os.path.join(build_base, "opentrons_shared_data", DEST_BASE_PATH)
+        # And finally, tell the system about our files
+        files.extend(
+            [
+                ("opentrons_shared_data", DATA_ROOT, destination, to_include),
+            ]
+        )
+        return files
+
+
+def get_version():
+    buildno = os.getenv("BUILD_NUMBER")
+    project = os.getenv("OPENTRONS_PROJECT", "robot-stack")
+    git_dir = os.getenv("OPENTRONS_GIT_DIR", None)
+    if buildno:
+        normalize_opts = {"extra_tag": buildno}
+    else:
+        normalize_opts = {}
+    return normalize_version("shared-data", project, git_dir=git_dir, **normalize_opts)
+
+
+VERSION = get_version()
+
+DISTNAME = "opentrons_shared_data"
+LICENSE = "Apache 2.0"
+AUTHOR = "Opentrons"
+EMAIL = "engineering@opentrons.com"
+URL = "https://github.com/Opentrons/opentrons"
+DOWNLOAD_URL = ""
+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.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Topic :: Scientific/Engineering",
+]
+KEYWORDS = ["robots", "protocols", "synbio", "pcr", "automation", "lab"]
+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"
+)
+PACKAGES = find_packages(where=".", exclude=["tests"])
+INSTALL_REQUIRES = [
+    "jsonschema==3.0.2",
+    "typing-extensions>=4.0.0,<5",
+    "pydantic==1.8.2",
+]
+
+
+if __name__ == "__main__":
+    setup(
+        python_requires=">=3.7",
+        name=DISTNAME,
+        description=DESCRIPTION,
+        license=LICENSE,
+        version=VERSION,
+        author=AUTHOR,
+        author_email=EMAIL,
+        maintainer=AUTHOR,
+        maintainer_email=EMAIL,
+        keywords=KEYWORDS,
+        packages=PACKAGES,
+        zip_safe=False,
+        classifiers=CLASSIFIERS,
+        install_requires=INSTALL_REQUIRES,
+        include_package_data=True,
+        package_data={"opentrons_shared_data": ["py.typed"]},
+        cmdclass={"build_py": BuildWithData, "sdist": SDistWithData},
+        project_urls={
+            "opentrons.com": "https://www.opentrons.com",
+            "Source Code On Github": (
+                "https://github.com/Opentrons/opentrons/tree/edge/shared-data"
+            ),
+            "Documentation": "https://docs.opentrons.com",
+        },
+    )

package/python/tests/__init__.py

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

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,113 @@
+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.dev_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)
+        # v3 has a "slot" for the fixed trash, but in v4, fixedTrash is its own area type. Count
+        # it as a "slot," since we still want to compare the positions across schema versions.
+        if addressable_area["areaType"] in {"slot", "fixedTrash"}
+    )
+
+    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)
+
+    # For the purposes of this comparison, the v4 addressable areas named "fixedTrash" and
+    # "shortFixedTrash" should be compared to slot 12 in v3.
+    v4_slot_positions = set(
+        (
+            "12" if slot_id in {"fixedTrash", "shortFixedTrash"} else slot_id,
+            slot_position,
+        )
+        for slot_id, slot_position in v4_slot_positions
+    )
+
+    assert v3_slot_positions == v4_slot_positions

package/python/tests/deck/test_typechecks.py

@@ -0,0 +1,28 @@
+import sys
+
+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.dev_types import DeckDefinitionV3, DeckDefinitionV4
+
+
+pytestmark = pytest.mark.xfail(
+    condition=sys.version_info >= (3, 10),
+    reason="https://github.com/agronholm/typeguard/issues/242",
+)
+
+
+@pytest.mark.parametrize("defname", list_deck_definition_names(version=3))
+def test_v3_defs(defname):
+    defn = load_deck_definition(name=defname, version=3)
+    typeguard.check_type("defn", defn, DeckDefinitionV3)
+
+
+@pytest.mark.parametrize("defname", list_deck_definition_names(version=4))
+def test_v4_defs(defname):
+    defn = load_deck_definition(name=defname, version=4)
+    typeguard.check_type("defn", defn, DeckDefinitionV4)

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.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/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/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/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/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()
+    ]

package/python/tests/module/test_load.py

@@ -0,0 +1,49 @@
+import json
+import pytest
+
+from opentrons_shared_data.module import (
+    load_definition,
+    load_schema,
+    ModuleNotFoundError,
+)
+from opentrons_shared_data import load_shared_data
+
+from . import list_v2_defs, list_v3_defs
+
+
+@pytest.mark.parametrize("def_name", list_v3_defs())
+def test_load_v3_defs(def_name: str) -> None:
+    """Test that all v3 definitions load correctly."""
+    assert load_definition("3", def_name) == json.loads(
+        load_shared_data(f"module/definitions/3/{def_name}.json")
+    )
+
+
+@pytest.mark.parametrize("def_name", list_v2_defs())
+def test_load_v2_defs(def_name: str) -> None:
+    assert load_definition("2", def_name) == json.loads(  # type: ignore [call-overload]
+        load_shared_data(f"module/definitions/2/{def_name}.json")
+    )
+
+
+@pytest.mark.parametrize("def_name", ["magdeck", "tempdeck", "thermocycler"])
+def test_load_v1_defs(def_name: str) -> None:
+    assert (
+        load_definition("1", def_name)
+        == json.loads(load_shared_data("module/definitions/1.json"))[def_name]
+    )
+
+
+def test_bad_module_name_throws() -> None:
+    with pytest.raises(ModuleNotFoundError):
+        load_definition("1", "alsjdag")
+
+    with pytest.raises(ModuleNotFoundError):
+        load_definition("2", "asdasda")  # type: ignore[call-overload]
+
+
+@pytest.mark.parametrize("schema_name", ["1", "2", "3"])
+def test_load_schema(schema_name: str) -> None:
+    assert load_schema(schema_name) == json.loads(  # type: ignore[arg-type]
+        load_shared_data(f"module/schemas/{schema_name}.json")
+    )

package/python/tests/module/test_typechecks.py

@@ -0,0 +1,34 @@
+import sys
+
+import pytest
+import typeguard
+
+from opentrons_shared_data import module
+from opentrons_shared_data.module import dev_types
+
+from . import list_v2_defs, list_v3_defs
+
+
+pytestmark = pytest.mark.xfail(
+    condition=sys.version_info >= (3, 10),
+    reason="https://github.com/agronholm/typeguard/issues/242",
+)
+
+
+@pytest.mark.parametrize("defname", list_v3_defs())
+def test_v3_definitions_match_types(defname: str) -> None:
+    """Test that V3 module definitions match ModuleDefinitionV3."""
+    def_dict = module.load_definition("3", defname)
+    typeguard.check_type("def_dict", def_dict, dev_types.ModuleDefinitionV3)
+
+
+@pytest.mark.parametrize("defname", list_v2_defs())
+def test_v2_definitions_match_types(defname: str) -> None:
+    defdict = module.load_definition("2", defname)  # type: ignore [call-overload]
+    typeguard.check_type("defdict", defdict, dev_types.ModuleDefinitionV2)
+
+
+@pytest.mark.parametrize("defname", ["magdeck", "tempdeck", "thermocycler"])
+def test_v1_definitions_match_types(defname: str) -> None:
+    defdict = module.load_definition("1", defname)
+    typeguard.check_type("defdict", defdict, dev_types.ModuleDefinitionV1)