@opentrons/shared-data 0.0.0-alpha.2

package/python/buildroot.mk

@@ -0,0 +1,30 @@
+################################################################################
+#
+# python-opentrons-shared-data
+#
+################################################################################
+
+define OTSHAREDDATA_CALL_PBU
+	$(shell python $(BR2_EXTERNAL_OPENTRONS_MONOREPO_PATH)/scripts/python_build_utils.py shared-data $(or $(OPENTRONS_PROJECT),robot-stack) $(1))
+endef
+
+PYTHON_OPENTRONS_SHARED_DATA_VERSION = $(call OTSHAREDDATA_CALL_PBU,get_version)
+PYTHON_OPENTRONS_SHARED_DATA_LICENSE = Apache-2
+PYTHON_OPENTRONS_SHARED_DATA_LICENSE_FILES = $(BR2_EXTERNAL_OPENTRONS_MONOREPO_PATH)/LICENSE
+PYTHON_OPENTRONS_SHARED_DATA_SETUP_TYPE = setuptools
+PYTHON_OPENTRONS_SHARED_DATA_SITE_METHOD = local
+PYTHON_OPENTRONS_SHARED_DATA_SITE = $(BR2_EXTERNAL_OPENTRONS_MONOREPO_PATH)
+PYTHON_OPENTRONS_SHARED_DATA_SUBDIR = shared-data/python
+
+define PYTHON_OPENTRONS_SHARED_DATA_INSTALL_VERSION
+	echo '$(call OTSHAREDDATA_CALL_PBU,dump_br_version)' > $(BINARIES_DIR)/opentrons-shared-data-version.json
+endef
+
+ot_sd_name := python-opentrons-shared-data
+
+export OPENTRONS_GIT_DIR=$(BR2_EXTERNAL_OPENTRONS_MONOREPO_PATH)
+
+# Calling inner-python-package directly instead of using python-package macro
+# because our directory layout doesn’t conform to buildroot’s expectation of
+# having the directory name be the package name
+$(eval $(call inner-python-package,$(ot_sd_name),$(call UPPERCASE,$(ot_sd_name)),$(call UPPERCASE,$(ot_sd_name)),target))

package/python/mypy.ini

@@ -0,0 +1,41 @@
+[mypy]
+plugins = pydantic.mypy
+show_error_codes = True
+warn_unused_configs = True
+strict = True
+
+[pydantic-mypy]
+init_forbid_extra = True
+init_typed = True
+warn_required_dynamic_aliases = True
+warn_untyped_fields = True
+
+# TODO(mc, 2022-01-20): fix and remove all of the overrides below
+
+[mypy-opentrons_shared_data.labware.*]
+warn_return_any = False
+
+[mypy-opentrons_shared_data.pipette.*]
+no_implicit_optional = False
+warn_return_any = False
+
+[mypy-opentrons_shared_data.protocol.*]
+warn_return_any = False
+
+[mypy-tests.deck.*]
+disallow_untyped_defs = False
+
+[mypy-tests.labware.*]
+disallow_untyped_defs = False
+disallow_untyped_calls = False
+
+[mypy-tests.module.*]
+disallow_untyped_defs = False
+disallow_untyped_calls = False
+
+[mypy-tests.pipette.*]
+disallow_untyped_defs = False
+disallow_untyped_calls = False
+
+[mypy-tests.protocol.*]
+disallow_untyped_defs = False

package/python/opentrons_shared_data/__init__.py

@@ -0,0 +1,17 @@
+"""A Python package wrapping json config definitions for the Opentrons stack.
+
+This package should never be installed on its own, only as a dependency of
+the main opentrons package
+"""
+
+import os
+
+from .load import get_shared_data_root, load_shared_data
+
+from ._version import version
+
+HERE = os.path.abspath(os.path.dirname(__file__))
+
+__version__ = version
+
+__all__ = ["__version__", "get_shared_data_root", "load_shared_data"]

package/python/opentrons_shared_data/_version.py

@@ -0,0 +1,20 @@
+import sys
+import logging
+
+_pyversion = sys.version_info[0:2]
+
+if _pyversion >= (3, 8):
+    from importlib import metadata
+else:
+    import importlib_metadata as metadata  # type: ignore[no-redef]
+
+try:
+    version: str = metadata.version("opentrons_shared_data")  # type: ignore[attr-defined]
+except Exception as e:
+    logging.warning(
+        "Could not determine version for opentrons, may be dev install, using 0.0.0-dev"
+    )
+    logging.debug(e)
+    version = "0.0.0-dev"
+
+__all__ = ["version"]

package/python/opentrons_shared_data/command/__init__.py

@@ -0,0 +1,52 @@
+"""opentrons_shared_data.command: functions command schemas."""
+from pathlib import Path
+import json
+import os
+import re
+
+from opentrons_shared_data.errors.exceptions import InvalidProtocolData, PythonException
+
+from ..load import load_shared_data, get_shared_data_root
+
+SCHEMA_REF_VERSION_RE = re.compile(r"opentronsCommandSchemaV(\d+)")
+
+
+def get_newest_schema_version() -> str:
+    """Get the version string of the most modern command schema currently in shared-data."""
+    command_schemas_dir = get_shared_data_root() / "command" / "schemas"
+    command_schemas = os.listdir(command_schemas_dir)
+    all_schema_versions = []
+    for schema_file_name in command_schemas:
+        schema_version_match = re.match(r"(\d+).json", schema_file_name)
+        if schema_version_match is not None:
+            all_schema_versions.append(schema_version_match.group(1))
+
+    return str(max(all_schema_versions))
+
+
+def load_schema_string(version: str) -> str:
+    """Get the string containing the command JSON schema for the given version string."""
+    path = Path("command") / "schemas" / f"{version}.json"
+    try:
+        return json.dumps(json.loads(load_shared_data(path)), indent=2)
+    except OSError as ose:
+        raise InvalidProtocolData(
+            message=f"Command schema version {version} is not available",
+            detail={
+                "type": "bad-schema-version",
+                "schema-kind": "command",
+                "version": version,
+            },
+            wrapping=[PythonException(ose)],
+        )
+
+
+def schema_version_from_ref(ref: str) -> str:
+    """Parse the command schema version from a command schema ref."""
+    version = SCHEMA_REF_VERSION_RE.match(ref)
+    if not version:
+        raise InvalidProtocolData(
+            message=f"Could not parse version from command schema ${ref}",
+            detail={"ref": ref, "type": "bad-schema-ref", "schema-kind": "command"},
+        )
+    return version.group(1)

package/python/opentrons_shared_data/deck/__init__.py

@@ -0,0 +1,96 @@
+"""
+opentrons_shared_data.deck: types and bindings for deck definitions
+"""
+from typing import Dict, List, NamedTuple, cast, overload, TYPE_CHECKING
+from typing_extensions import Final
+import json
+
+from .. import get_shared_data_root, load_shared_data
+
+if TYPE_CHECKING:
+    from .dev_types import (
+        DeckSchema,
+        DeckDefinition,
+        DeckDefinitionV3,
+        DeckSchemaVersion3,
+        DeckDefinitionV4,
+        DeckSchemaVersion4,
+    )
+
+DEFAULT_DECK_DEFINITION_VERSION: Final = 4
+
+
+class Offset(NamedTuple):
+    x: float = 0.0
+    y: float = 0.0
+    z: float = 0.0
+
+
+Z_PREP_OFFSET = Offset(x=13, y=13)
+CALIBRATION_PROBE_RADIUS: Final[float] = 2
+CALIBRATION_SQUARE_DEPTH: Final[float] = -0.25
+CALIBRATION_SQUARE_SIZE: Final[float] = 20
+CALIBRATION_SQUARE_EDGES: Dict[str, Offset] = {
+    "left": Offset(x=-CALIBRATION_SQUARE_SIZE * 0.5),
+    "right": Offset(x=CALIBRATION_SQUARE_SIZE * 0.5),
+    "top": Offset(y=CALIBRATION_SQUARE_SIZE * 0.5),
+    "bottom": Offset(y=-CALIBRATION_SQUARE_SIZE * 0.5),
+}
+
+
+@overload
+def load(name: str, version: "DeckSchemaVersion4") -> "DeckDefinitionV4":
+    ...
+
+
+@overload
+def load(name: str, version: "DeckSchemaVersion3") -> "DeckDefinitionV3":
+    ...
+
+
+def load(name: str, version: int = DEFAULT_DECK_DEFINITION_VERSION) -> "DeckDefinition":
+    return json.loads(  # type: ignore[no-any-return]
+        load_shared_data(f"deck/definitions/{version}/{name}.json")
+    )
+
+
+def load_schema(version: int) -> "DeckSchema":
+    return cast(
+        "DeckSchema", json.loads(load_shared_data(f"deck/schemas/{version}.json"))
+    )
+
+
+def list_names(version: int) -> List[str]:
+    """Return all loadable deck definition names, for the given schema version."""
+    definitions_directory = (
+        get_shared_data_root() / "deck" / "definitions" / f"{version}"
+    )
+    return [file.stem for file in definitions_directory.iterdir()]
+
+
+def get_calibration_square_position_in_slot(slot: int) -> Offset:
+    """Get the position of an OT-3 deck slot's calibration square.
+
+    Params:
+        slot: The slot whose calibration square to retrieve, specified as an OT-2-style slot number.
+            For example, specify 5 to get slot C2.
+    """
+    deck = load("ot3_standard", version=3)
+    slots = deck["locations"]["orderedSlots"]
+
+    # Assume that the OT-3 deck definition has the same number of slots, and in the same order,
+    # as the OT-2.
+    # TODO(mm, 2023-05-22): This assumption will break down when the OT-3 has staging area slots.
+    # https://opentrons.atlassian.net/browse/RLAB-345
+    s = slots[slot - 1]
+
+    bottom_left = s["position"]
+    slot_size_x = s["boundingBox"]["xDimension"]
+    slot_size_y = s["boundingBox"]["yDimension"]
+    relative_center = [float(slot_size_x) * 0.5, float(slot_size_y) * 0.5, 0]
+    square_z = [0, 0, CALIBRATION_SQUARE_DEPTH]
+    # add up the elements of each list and return an Offset of the result
+    nominal_position = [
+        float(sum(x)) for x in zip(bottom_left, relative_center, square_z)
+    ]
+    return Offset(*nominal_position)

package/python/opentrons_shared_data/deck/dev_types.py

@@ -0,0 +1,180 @@
+"""
+opentrons_shared_data.deck.dev_types: types for deck defs
+
+This should only be imported if typing.TYPE_CHECKING is True
+"""
+
+from typing import Any, Dict, List, NewType, Union
+from typing_extensions import Literal, TypedDict
+
+from ..module.dev_types import ModuleType
+
+
+DeckSchemaVersion4 = Literal[4]
+DeckSchemaVersion3 = Literal[3]
+DeckSchemaVersion2 = Literal[2]
+DeckSchemaVersion1 = Literal[1]
+
+DeckSchema = NewType("DeckSchema", Dict[str, Any])
+
+DeckSchemaId = Literal["opentronsDeckSchemaV3", "opentronsDeckSchemaV4"]
+RobotModel = Union[Literal["OT-2 Standard"], Literal["OT-3 Standard"]]
+
+
+class Metadata(TypedDict, total=False):
+    displayName: str
+    tags: List[str]
+
+
+class Robot(TypedDict):
+    model: RobotModel
+
+
+class BoundingBox(TypedDict):
+    xDimension: float
+    yDimension: float
+    zDimension: float
+
+
+class SlotDefV3(TypedDict, total=False):
+    id: str
+    position: List[float]
+    boundingBox: BoundingBox
+    displayName: str
+    compatibleModuleTypes: List[ModuleType]
+    matingSurfaceUnitVector: List[Union[Literal[1], Literal[-1]]]
+
+
+class CalibrationPoint(TypedDict):
+    id: str
+    position: List[float]
+    displayName: str
+
+
+class INode(TypedDict):
+    name: str
+    type: str
+    value: str
+    attributes: Dict[str, str]
+    # this should be a recursive call to INode but we need to upgrade mypy
+    children: List[Dict[str, Any]]
+
+
+class FixedLabwareBySlot(TypedDict):
+    id: str
+    displayName: str
+    labware: str
+    slot: str
+
+
+class FixedLabwareByPosition(TypedDict):
+    id: str
+    displayName: str
+    labware: str
+    position: List[float]
+
+
+class FixedVolumeBySlot(TypedDict):
+    id: str
+    displayName: str
+    boundingBox: BoundingBox
+    slot: str
+
+
+class FixedVolumeByPosition(TypedDict):
+    id: str
+    displayName: str
+    boundingBox: BoundingBox
+    position: List[float]
+
+
+class _RequiredAddressableArea(TypedDict):
+    id: str
+    areaType: str
+    offsetFromCutoutFixture: List[float]
+    boundingBox: BoundingBox
+    displayName: str
+
+
+class AddressableArea(_RequiredAddressableArea, total=False):
+    compatibleModuleTypes: List[ModuleType]
+    matingSurfaceUnitVector: List[Union[Literal[1], Literal[-1]]]
+    ableToDropTips: bool
+    ableToDropLabware: bool
+    dropTipsOffset: List[float]
+    dropLabwareOffset: List[float]
+
+
+class Cutout(TypedDict):
+    id: str
+    position: List[float]
+    displayName: str
+
+
+class CutoutFixture(TypedDict):
+    id: str
+    mayMountTo: List[str]
+    displayName: str
+    providesAddressableAreas: Dict[str, List[str]]
+
+
+Fixture = Union[
+    FixedLabwareBySlot, FixedLabwareByPosition, FixedVolumeBySlot, FixedVolumeByPosition
+]
+
+
+class LocationsV3(TypedDict):
+    orderedSlots: List[SlotDefV3]
+    calibrationPoints: List[CalibrationPoint]
+    fixtures: List[Fixture]
+
+
+class LocationsV4(TypedDict):
+    addressableAreas: List[AddressableArea]
+    calibrationPoints: List[CalibrationPoint]
+    cutouts: List[Cutout]
+    legacyFixtures: List[Fixture]
+
+
+class NamedOffset(TypedDict):
+    x: float
+    y: float
+    z: float
+
+
+class GripperOffsets(TypedDict):
+    pickUpOffset: NamedOffset
+    dropOffset: NamedOffset
+
+
+class _RequiredDeckDefinitionV3(TypedDict):
+    otId: str
+    schemaVersion: Literal[3]
+    cornerOffsetFromOrigin: List[float]
+    dimensions: List[float]
+    metadata: Metadata
+    robot: Robot
+    locations: LocationsV3
+    layers: List[INode]
+
+
+class DeckDefinitionV3(_RequiredDeckDefinitionV3, total=False):
+    gripperOffsets: Dict[str, GripperOffsets]
+
+
+class _RequiredDeckDefinitionV4(TypedDict):
+    otId: str
+    schemaVersion: Literal[4]
+    cornerOffsetFromOrigin: List[float]
+    dimensions: List[float]
+    metadata: Metadata
+    robot: Robot
+    locations: LocationsV4
+    cutoutFixtures: List[CutoutFixture]
+
+
+class DeckDefinitionV4(_RequiredDeckDefinitionV4, total=False):
+    gripperOffsets: Dict[str, GripperOffsets]
+
+
+DeckDefinition = Union[DeckDefinitionV3, DeckDefinitionV4]

package/python/opentrons_shared_data/errors/__init__.py

@@ -0,0 +1,30 @@
+"""A python package implementing the errors in errors.json.
+
+A note on this package: it is not codegenned but written by hand, and has to be upkept
+by hand. It comes with tests to make sure this happens.
+
+This seems a little ridiculous and kind of is, but what it lets us do is really simplify
+our static analysis and dev setup.
+"""
+
+from .categories import ErrorCategories, ErrorCategory
+from .codes import ErrorCodes, ErrorCode
+from .exceptions import (
+    EnumeratedError,
+    PythonException,
+    GeneralError,
+    RoboticsControlError,
+    RoboticsInteractionError,
+)
+
+__all__ = [
+    "ErrorCategory",
+    "ErrorCategories",
+    "ErrorCode",
+    "ErrorCodes",
+    "EnumeratedError",
+    "PythonException",
+    "GeneralError",
+    "RoboticsControlError",
+    "RoboticsInteractionError",
+]

package/python/opentrons_shared_data/errors/categories.py

@@ -0,0 +1,60 @@
+"""Error categories."""
+
+from enum import Enum
+from dataclasses import dataclass
+import json
+from functools import lru_cache
+from typing import Dict
+
+from ..load import load_shared_data
+
+
+CATEGORIES: Dict[str, Dict[str, str]] = json.loads(
+    load_shared_data("errors/definitions/1/errors.json")
+)["categories"]
+
+
+@dataclass(frozen=True)
+class ErrorCategory:
+    """Individual error category data."""
+
+    name: str
+    detail: str
+    code_prefix: str
+
+
+def _category_from_dict_entry(entry_name: str) -> ErrorCategory:
+    return ErrorCategory(
+        name=entry_name,
+        detail=CATEGORIES[entry_name]["detail"],
+        code_prefix=CATEGORIES[entry_name]["codePrefix"],
+    )
+
+
+class ErrorCategories(Enum):
+    """All enuemrated error categories."""
+
+    HARDWARE_COMMUNICATION_ERROR = _category_from_dict_entry(
+        "hardwareCommunicationError"
+    )
+    ROBOTICS_CONTROL_ERROR = _category_from_dict_entry("roboticsControlError")
+    ROBOTICS_INTERACTION_ERROR = _category_from_dict_entry("roboticsInteractionError")
+    GENERAL_ERROR = _category_from_dict_entry("generalError")
+
+    @classmethod
+    @lru_cache(4)
+    def by_category_name(cls, category_name: str) -> "ErrorCategories":
+        """Get a subsystem by its category name."""
+        for entry in cls:
+            if entry.value.name == category_name:
+                return entry
+        raise KeyError(category_name)
+
+    @classmethod
+    @lru_cache(4)
+    def by_code_prefix(cls, prefix: str) -> "ErrorCategories":
+        """Get an error category by its code prefix."""
+        for entry in cls:
+            if entry.value.code_prefix == prefix:
+                return entry
+        raise KeyError(prefix)

package/python/opentrons_shared_data/errors/codes.py

@@ -0,0 +1,108 @@
+"""Error codes."""
+
+from enum import Enum
+from dataclasses import dataclass
+import json
+from typing import Tuple, Dict
+from functools import lru_cache
+
+from ..load import load_shared_data
+from .categories import ErrorCategories
+
+CODES: Dict[str, Dict[str, str]] = json.loads(
+    load_shared_data("errors/definitions/1/errors.json")
+)["codes"]
+
+
+@dataclass(frozen=True)
+class ErrorCode:
+    """Individual error code data."""
+
+    code: str
+    detail: str
+    category: ErrorCategories
+
+
+def _code_from_dict_entry(entry_code: str) -> ErrorCode:
+    return ErrorCode(
+        code=entry_code,
+        detail=CODES[entry_code]["detail"],
+        category=ErrorCategories.by_category_name(CODES[entry_code]["category"]),
+    )
+
+
+class ErrorCodes(Enum):
+    """All enumerated error codes."""
+
+    COMMUNICATION_ERROR = _code_from_dict_entry("1000")
+    CANBUS_COMMUNICATION_ERROR = _code_from_dict_entry("1001")
+    INTERNAL_USB_COMMUNICATION_ERROR = _code_from_dict_entry("1002")
+    MODULE_COMMUNICATION_ERROR = _code_from_dict_entry("1003")
+    COMMAND_TIMED_OUT = _code_from_dict_entry("1004")
+    FIRMWARE_UPDATE_FAILED = _code_from_dict_entry("1005")
+    INTERNAL_MESSAGE_FORMAT_ERROR = _code_from_dict_entry("1006")
+    CANBUS_CONFIGURATION_ERROR = _code_from_dict_entry("1007")
+    CANBUS_BUS_ERROR = _code_from_dict_entry("1008")
+    ROBOTICS_CONTROL_ERROR = _code_from_dict_entry("2000")
+    MOTION_FAILED = _code_from_dict_entry("2001")
+    HOMING_FAILED = _code_from_dict_entry("2002")
+    STALL_OR_COLLISION_DETECTED = _code_from_dict_entry("2003")
+    MOTION_PLANNING_FAILURE = _code_from_dict_entry("2004")
+    POSITION_ESTIMATION_INVALID = _code_from_dict_entry("2005")
+    MOVE_CONDITION_NOT_MET = _code_from_dict_entry("2006")
+    CALIBRATION_STRUCTURE_NOT_FOUND = _code_from_dict_entry("2007")
+    EDGE_NOT_FOUND = _code_from_dict_entry("2008")
+    EARLY_CAPACITIVE_SENSE_TRIGGER = _code_from_dict_entry("2009")
+    INACCURATE_NON_CONTACT_SWEEP = _code_from_dict_entry("2010")
+    MISALIGNED_GANTRY = _code_from_dict_entry("2011")
+    UNMATCHED_TIP_PRESENCE_STATES = _code_from_dict_entry("2012")
+    POSITION_UNKNOWN = _code_from_dict_entry("2013")
+    EXECUTION_CANCELLED = _code_from_dict_entry("2014")
+    ROBOTICS_INTERACTION_ERROR = _code_from_dict_entry("3000")
+    LABWARE_DROPPED = _code_from_dict_entry("3001")
+    LABWARE_NOT_PICKED_UP = _code_from_dict_entry("3002")
+    TIP_PICKUP_FAILED = _code_from_dict_entry("3003")
+    TIP_DROP_FAILED = _code_from_dict_entry("3004")
+    UNEXPECTED_TIP_REMOVAL = _code_from_dict_entry("3005")
+    PIPETTE_OVERPRESSURE = _code_from_dict_entry("3006")
+    E_STOP_ACTIVATED = _code_from_dict_entry("3008")
+    E_STOP_NOT_PRESENT = _code_from_dict_entry("3009")
+    PIPETTE_NOT_PRESENT = _code_from_dict_entry("3010")
+    GRIPPER_NOT_PRESENT = _code_from_dict_entry("3011")
+    UNEXPECTED_TIP_ATTACH = _code_from_dict_entry("3012")
+    FIRMWARE_UPDATE_REQUIRED = _code_from_dict_entry("3013")
+    INVALID_ACTUATOR = _code_from_dict_entry("3014")
+    MODULE_NOT_PRESENT = _code_from_dict_entry("3015")
+    INVALID_INSTRUMENT_DATA = _code_from_dict_entry("3016")
+    INVALID_LIQUID_CLASS_NAME = _code_from_dict_entry("3017")
+    TIP_DETECTOR_NOT_FOUND = _code_from_dict_entry("3018")
+    GENERAL_ERROR = _code_from_dict_entry("4000")
+    ROBOT_IN_USE = _code_from_dict_entry("4001")
+    API_REMOVED = _code_from_dict_entry("4002")
+    NOT_SUPPORTED_ON_ROBOT_TYPE = _code_from_dict_entry("4003")
+    COMMAND_PRECONDITION_VIOLATED = _code_from_dict_entry("4004")
+    COMMAND_PARAMETER_LIMIT_VIOLATED = _code_from_dict_entry("4005")
+    INVALID_PROTOCOL_DATA = _code_from_dict_entry("4006")
+    API_MISCONFIGURATION = _code_from_dict_entry("4007")
+
+    @classmethod
+    @lru_cache(25)
+    def by_error_code(cls, error_code: str) -> "ErrorCodes":
+        """Get an error by its code.
+
+        Note: this is a linear search because it makes life easier and also this is rare in python.
+        """
+        for error in cls:
+            if error.value.code == error_code:
+                return error
+        raise KeyError(error_code)
+
+    @classmethod
+    @lru_cache(len(ErrorCategories))
+    def of_category(cls, category: ErrorCategories) -> Tuple["ErrorCodes", ...]:
+        """Get all error codes by their category."""
+        return tuple(
+            error
+            for error in cls
+            if error.value.code.startswith(category.value.code_prefix)
+        )