@opentrons/shared-data 0.0.0-alpha.2

package/python/opentrons_shared_data/load.py

@@ -0,0 +1,57 @@
+import typing
+import logging
+import os
+from pathlib import Path
+from functools import lru_cache
+
+log = logging.getLogger(__name__)
+
+ENV_SHARED_DATA_PATH = "OT_SHARED_DATA_PATH"
+
+
+class SharedDataMissingError(IOError):
+    pass
+
+
+@lru_cache(maxsize=1)
+def get_shared_data_root() -> Path:
+    """
+    Get the root directory of the shared data.
+
+    Steps (first to succeed wins):
+    1) Use environment variable in OT_SHARED_DATA_PATH
+    2) Look in "shared_data" in the root of the installed package
+    3) Look for "shared-data" in parent directories.
+    4) Raise exception
+    """
+    # Check environment variable
+    override = os.environ.get(ENV_SHARED_DATA_PATH)
+    if override is not None:
+        log.info("Using override for shared data path: %s", override)
+        return Path(override)
+
+    # Check contents of package
+    module_path = Path(__file__).parent
+    module_data = module_path / "data"
+    if module_data.exists():
+        log.info(f"Using packaged shared data path: {str(module_data)}")
+        return module_data
+
+    # We are likely to be running locally and will find shared-data in repo
+    for parent in module_path.parents:
+        p = parent / "shared-data"
+        if p.exists():
+            log.info("Using shared data in path: %s", p)
+            return p
+
+    raise SharedDataMissingError()
+
+
+def load_shared_data(path: typing.Union[str, Path]) -> bytes:
+    """
+    Load file from shared data directory.
+
+    path is relative to the root of all shared data (ie. no "shared-data")
+    """
+    with open(get_shared_data_root() / path, "rb") as f:
+        return f.read()

package/python/opentrons_shared_data/module/__init__.py

@@ -0,0 +1,74 @@
+""" opentrons_shared_data.module: functions and types for module defs """
+import json
+from pathlib import Path
+from typing import Union, cast, overload
+
+from ..load import load_shared_data
+from .dev_types import (
+    SchemaVersions,
+    ModuleSchema,
+    SchemaV1,
+    SchemaV3,
+    ModuleDefinitionV1,
+    ModuleDefinitionV3,
+    ModuleModel,
+)
+
+
+# TODO (spp, 2022-05-12): Python has a built-in error called `ModuleNotFoundError` so,
+#                         maybe rename this one?
+class ModuleNotFoundError(KeyError):
+    def __init__(self, version: str, model_or_loadname: str):
+        super().__init__(model_or_loadname)
+        self.requested_version = version
+        self.requested_module = model_or_loadname
+
+    def __str__(self) -> str:
+        return (
+            f"No such version {self.requested_version} module "
+            f"{self.requested_module}"
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}: {self.requested_module} "
+            f"at version {self.requested_version}"
+        )
+
+
+def load_schema(version: SchemaVersions) -> ModuleSchema:
+    path = Path("module") / "schemas" / f"{version}.json"
+    return cast(ModuleSchema, json.loads(load_shared_data(path)))
+
+
+@overload
+def load_definition(version: SchemaV1, model_or_loadname: str) -> ModuleDefinitionV1:
+    ...
+
+
+@overload
+def load_definition(
+    version: SchemaV3,
+    model_or_loadname: Union[str, ModuleModel],
+) -> ModuleDefinitionV3:
+    ...
+
+
+def load_definition(
+    version: SchemaVersions,
+    model_or_loadname: Union[str, ModuleModel],
+) -> Union[ModuleDefinitionV1, ModuleDefinitionV3]:
+    if version == "1":
+        path = Path("module") / "definitions" / "1.json"
+        data = json.loads(load_shared_data(path))
+        try:
+            return cast(ModuleDefinitionV1, data[model_or_loadname])
+        except KeyError:
+            raise ModuleNotFoundError("1", model_or_loadname)
+    else:
+        path = Path(f"module/definitions/{version}/{model_or_loadname}.json")
+        try:
+            data = load_shared_data(path)
+        except FileNotFoundError:
+            raise ModuleNotFoundError(version, model_or_loadname)
+        return cast(ModuleDefinitionV3, json.loads(data))

package/python/opentrons_shared_data/module/dev_types.py

@@ -0,0 +1,141 @@
+"""
+opentrons_shared_data.module.dev_types: types requiring typing_extensions
+for modules
+"""
+
+from typing import Any, Dict, List, Union
+from typing_extensions import Literal, TypedDict
+
+SchemaV1 = Literal["1"]
+SchemaV2 = Literal["2"]
+SchemaV3 = Literal["3"]
+SchemaVersions = Union[SchemaV1, SchemaV2, SchemaV3]
+
+ModuleSchema = Dict[str, Any]
+
+MagneticModuleType = Literal["magneticModuleType"]
+TemperatureModuleType = Literal["temperatureModuleType"]
+ThermocyclerModuleType = Literal["thermocyclerModuleType"]
+HeaterShakerModuleType = Literal["heaterShakerModuleType"]
+MagneticBlockType = Literal["magneticBlockType"]
+
+ModuleType = Union[
+    MagneticModuleType,
+    TemperatureModuleType,
+    ThermocyclerModuleType,
+    HeaterShakerModuleType,
+    MagneticBlockType,
+]
+
+MagneticModuleModel = Literal["magneticModuleV1", "magneticModuleV2"]
+TemperatureModuleModel = Literal["temperatureModuleV1", "temperatureModuleV2"]
+ThermocyclerModuleModel = Literal["thermocyclerModuleV1", "thermocyclerModuleV2"]
+HeaterShakerModuleModel = Literal["heaterShakerModuleV1"]
+MagneticBlockModel = Literal["magneticBlockV1"]
+
+ModuleModel = Union[
+    MagneticModuleModel,
+    TemperatureModuleModel,
+    ThermocyclerModuleModel,
+    HeaterShakerModuleModel,
+    MagneticBlockModel,
+]
+
+ModuleSlotTransform = TypedDict(
+    "ModuleSlotTransform", {"labwareOffset": List[List[float]]}
+)
+
+ModuleLabwareOffset = TypedDict(
+    "ModuleLabwareOffset", {"x": float, "y": float, "z": float}
+)
+
+ModuleDimensions = TypedDict(
+    "ModuleDimensions",
+    {
+        "bareOverallHeight": float,
+        "overLabwareHeight": float,
+        "lidHeight": float,
+        "xDimension": float,
+        "yDimension": float,
+        "footprintXDimension": float,
+        "footprintYDimension": float,
+        "labwareInterfaceXDimension": float,
+        "labwareInterfaceYDimension": float,
+    },
+    total=False,
+)
+
+ModuleCalibrationPointOffset = TypedDict(
+    "ModuleCalibrationPointOffset", {"x": float, "y": float}
+)
+
+ModuleCalibrationPointOffsetWithZ = TypedDict(
+    "ModuleCalibrationPointOffsetWithZ", {"x": float, "y": float, "z": float}
+)
+
+CornerOffsetFromSlot = TypedDict(
+    "CornerOffsetFromSlot", {"x": float, "y": float, "z": float}
+)
+
+
+class NamedOffset(TypedDict):
+    x: float
+    y: float
+    z: float
+
+
+class GripperOffsets(TypedDict):
+    pickUpOffset: NamedOffset
+    dropOffset: NamedOffset
+
+
+# TODO(mc, 2022-03-18): potentially move from typed-dict to Pydantic
+ModuleDefinitionV3 = TypedDict(
+    "ModuleDefinitionV3",
+    {
+        "$otSharedSchema": Literal["module/schemas/3"],
+        "moduleType": ModuleType,
+        "model": ModuleModel,
+        "labwareOffset": ModuleLabwareOffset,
+        "cornerOffsetFromSlot": CornerOffsetFromSlot,
+        "dimensions": ModuleDimensions,
+        "calibrationPoint": ModuleCalibrationPointOffsetWithZ,
+        "config": Dict[str, int],
+        "displayName": str,
+        "quirks": List[str],
+        "slotTransforms": Dict[str, Dict[str, Dict[str, List[List[float]]]]],
+        "compatibleWith": List[ModuleModel],
+        "twoDimensionalRendering": Dict[str, Any],
+        "gripperOffsets": Dict[str, GripperOffsets],
+    },
+    total=False,
+)
+
+# V2 is not used anymore. This type is preserved for historical purposes
+ModuleDefinitionV2 = TypedDict(
+    "ModuleDefinitionV2",
+    {
+        "$otSharedSchema": Literal["module/schemas/2"],
+        "moduleType": ModuleType,
+        "model": ModuleModel,
+        "labwareOffset": ModuleLabwareOffset,
+        "dimensions": ModuleDimensions,
+        "calibrationPoint": ModuleCalibrationPointOffset,
+        "displayName": str,
+        "quirks": List[str],
+        "slotTransforms": Dict[str, Dict[str, Dict[str, List[List[float]]]]],
+        "compatibleWith": List[ModuleModel],
+    },
+)
+
+ModuleDefinitionV1 = TypedDict(
+    "ModuleDefinitionV1",
+    {
+        "labwareOffset": ModuleLabwareOffset,
+        "dimensions": ModuleDimensions,
+        "calibrationPoint": ModuleCalibrationPointOffset,
+        "displayName": str,
+        "loadName": str,
+        "quirks": List[str],
+    },
+)

package/python/opentrons_shared_data/pipette/__init__.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+"""
+opentrons_shared_data.pipette: functions and types for pipette config
+"""
+import copy
+from typing import TYPE_CHECKING, Dict
+import json
+from functools import lru_cache
+
+from .. import load_shared_data
+
+if TYPE_CHECKING:
+    from .dev_types import (
+        PipetteNameSpecs,
+        PipetteModelSpecs,
+        PipetteName,
+        PipetteModel,
+        PipetteFusedSpec,
+        ChannelCount,
+    )
+
+
+# TODO (spp, 2023-06-22: should probably move this to definition)
+"""
+The span of pipettes in X-direction based on number of channels.
+This is needed in order to determine safe tip drop location within a labware.
+"""
+PIPETTE_X_SPAN: Dict[ChannelCount, float] = {
+    1: 75,  # includes a margin
+    8: 75,  # includes a margin
+    96: 161,
+}
+
+
+def model_config() -> PipetteModelSpecs:
+    """Load the per-pipette-model config file from within the wheel"""
+    return copy.deepcopy(_model_config())
+
+
+@lru_cache(maxsize=None)
+def _model_config() -> PipetteModelSpecs:
+    return json.loads(
+        load_shared_data("pipette/definitions/1/pipetteModelSpecs.json") or "{}"
+    )
+
+
+def name_config() -> PipetteNameSpecs:
+    """Load the per-pipette-name config file from within the wheel"""
+    return _name_config()
+
+
+@lru_cache(maxsize=None)
+def _name_config() -> PipetteNameSpecs:
+    return json.loads(
+        load_shared_data("pipette/definitions/1/pipetteNameSpecs.json") or "{}"
+    )
+
+
+def name_for_model(pipette_model: PipetteModel) -> PipetteName:
+    """Quickly look up the name for this model"""
+    return model_config()["config"][pipette_model]["name"]
+
+
+def fuse_specs(
+    pipette_model: PipetteModel, pipette_name: PipetteName = None
+) -> PipetteFusedSpec:
+    """Combine the model and name spec for a given model.
+
+    if pipette_name is not given, the name field of the pipette config
+    is used. If it is, the given name must be in the backCompatNames field.
+    """
+    return copy.deepcopy(_fuse_specs_cached(pipette_model, pipette_name))
+
+
+@lru_cache(maxsize=None)
+def _fuse_specs_cached(
+    pipette_model: PipetteModel, pipette_name: PipetteName = None
+) -> PipetteFusedSpec:
+    """
+    Do the work of fusing the specs inside an lru cache. This can't be the
+    function that's directly called because we want to return a new object
+    all the time, hence the wrapper.
+    """
+    model_data = _model_config()["config"][pipette_model]
+    pipette_name = pipette_name or model_data["name"]
+
+    valid_names = [model_data["name"]] + model_data.get("backCompatNames", [])
+
+    if pipette_name not in valid_names:
+        raise KeyError(
+            f"pipette name {pipette_name} is not valid for model " f"{pipette_model}"
+        )
+    name_data = _name_config()[pipette_name]
+    # unfortunately, mypy can't verify this way to build typed dicts - we'll
+    # make sure it's correct in the tests, and leave the function annotated
+    # properly
+    return {**model_data, **name_data}  # type: ignore
+
+
+def dummy_model_for_name(pipette_name: PipetteName) -> PipetteModel:
+    if "gen2" in pipette_name:
+        return "_".join(pipette_name.split("_")[:-1]) + "_v2.0"  # type: ignore
+    elif "flex" in pipette_name:
+        return "_".join(pipette_name.split("_")[:-1]) + "_v3.0"  # type: ignore
+    else:
+        return pipette_name + "_v1"  # type: ignore

package/python/opentrons_shared_data/pipette/dev_types.py

@@ -0,0 +1,177 @@
+"""
+opentrons_shared_data.pipette.dev_types: types for pipette config that
+require typing_extensions.
+
+This module should only be imported if typing.TYPE_CHECKING is True.
+"""
+from enum import Enum
+from typing import Dict, List, NewType, Union
+
+from typing_extensions import Literal, TypedDict
+
+# TODO(mc, 2022-06-16): remove type alias when able
+# and when certain removal will not break any pickling
+from ..labware.dev_types import LabwareUri as LabwareUri
+
+
+PipetteName = Literal[
+    "p10_single",
+    "p10_multi",
+    "p20_single_gen2",
+    "p20_multi_gen2",
+    "p50_single",
+    "p50_multi",
+    "p50_single_flex",
+    "p50_multi_flex",
+    "p300_single",
+    "p300_multi",
+    "p300_single_gen2",
+    "p300_multi_gen2",
+    "p1000_single",
+    "p1000_single_gen2",
+    "p1000_single_flex",
+    "p1000_multi_flex",
+    "p1000_96",
+]
+
+
+class PipetteNameType(str, Enum):
+    """Pipette load name values."""
+
+    value: PipetteName
+
+    P10_SINGLE = "p10_single"
+    P10_MULTI = "p10_multi"
+    P20_SINGLE_GEN2 = "p20_single_gen2"
+    P20_MULTI_GEN2 = "p20_multi_gen2"
+    P50_SINGLE = "p50_single"
+    P50_MULTI = "p50_multi"
+    P50_SINGLE_FLEX = "p50_single_flex"
+    P50_MULTI_FLEX = "p50_multi_flex"
+    P300_SINGLE = "p300_single"
+    P300_MULTI = "p300_multi"
+    P300_SINGLE_GEN2 = "p300_single_gen2"
+    P300_MULTI_GEN2 = "p300_multi_gen2"
+    P1000_SINGLE = "p1000_single"
+    P1000_SINGLE_GEN2 = "p1000_single_gen2"
+    P1000_SINGLE_FLEX = "p1000_single_flex"
+    P1000_MULTI_FLEX = "p1000_multi_flex"
+    P1000_96 = "p1000_96"
+
+
+# Generic NewType for models because we get new ones frequently and theres
+# a huge number of them
+PipetteModel = NewType("PipetteModel", str)
+
+DisplayCategory = Literal["GEN1", "GEN2", "FLEX"]
+
+# todo(mm, 2022-03-18):
+# The JSON schema defines this as any string, not as an enum of string literals.
+# Check if it's safe to simplify this to just str.
+ConfigUnit = Literal[
+    "mm",
+    "amps",
+    "mm/sec",
+    "mm/s",  # todo(mm, 2022-03-18): Standardize specs to mm/sec or mm/s.
+    "presses",
+]
+
+Quirk = NewType("Quirk", str)
+
+ChannelCount = Literal[1, 8, 96]
+
+UlPerMmAction = Literal["aspirate", "dispense", "blowout"]
+
+
+class PipetteConfigElement(TypedDict):
+    value: float
+    min: float
+    max: float
+
+
+class PipetteConfigElementWithPerApiLevelValue(TypedDict):
+    value: float
+    min: float
+    max: float
+    valuesByApiLevel: Dict[str, float]
+
+
+# TypedDicts can't be generic sadly
+class PipetteCustomizableConfigElementFloat(TypedDict):
+    value: float
+    min: float
+    max: float
+    units: ConfigUnit
+    type: Literal["float"]
+
+
+class PipetteCustomizableConfigElementInt(TypedDict):
+    value: int
+    min: int
+    max: int
+    units: ConfigUnit
+    type: Literal["int"]
+
+
+PipetteCustomizableConfigElement = Union[
+    PipetteCustomizableConfigElementFloat, PipetteCustomizableConfigElementInt
+]
+
+SmoothieConfigs = TypedDict(
+    "SmoothieConfigs",
+    {"stepsPerMM": float, "homePosition": float, "travelDistance": float},
+)
+
+
+class PipetteNameSpec(TypedDict):
+    displayName: str
+    displayCategory: DisplayCategory
+    minVolume: Union[float, int]
+    maxVolume: Union[float, int]
+    channels: ChannelCount
+    defaultAspirateFlowRate: PipetteConfigElementWithPerApiLevelValue
+    defaultDispenseFlowRate: PipetteConfigElementWithPerApiLevelValue
+    defaultBlowOutFlowRate: PipetteConfigElementWithPerApiLevelValue
+    smoothieConfigs: SmoothieConfigs
+    defaultTipracks: List[LabwareUri]
+
+
+PipetteNameSpecs = Dict[PipetteName, PipetteNameSpec]
+
+UlPerMm = Dict[UlPerMmAction, List[List[float]]]
+
+
+class PipetteModelSpec(TypedDict, total=False):
+    name: PipetteName
+    top: PipetteCustomizableConfigElementFloat
+    bottom: PipetteCustomizableConfigElementFloat
+    blowout: PipetteCustomizableConfigElementFloat
+    dropTip: PipetteCustomizableConfigElementFloat
+    pickUpCurrent: PipetteCustomizableConfigElementFloat
+    pickUpDistance: PipetteCustomizableConfigElementFloat
+    pickUpIncrement: PipetteCustomizableConfigElementFloat
+    pickUpPresses: PipetteCustomizableConfigElementInt
+    pickUpSpeed: PipetteCustomizableConfigElementFloat
+    plungerCurrent: PipetteCustomizableConfigElementFloat
+    dropTipCurrent: PipetteCustomizableConfigElementFloat
+    dropTipSpeed: PipetteCustomizableConfigElementFloat
+    modelOffset: List[float]
+    nozzleOffset: List[float]
+    ulPerMm: List[UlPerMm]
+    tipOverlap: Dict[str, float]
+    tipLength: PipetteCustomizableConfigElementFloat
+    quirks: List[Quirk]
+    # these keys are not present in some pipette definitions
+    backCompatNames: List[PipetteName]
+    idleCurrent: float
+    returnTipHeight: float
+
+
+class PipetteFusedSpec(PipetteNameSpec, PipetteModelSpec, total=False):
+    pass
+
+
+class PipetteModelSpecs(TypedDict):
+    config: Dict[PipetteModel, PipetteModelSpec]
+    mutableConfigs: List[str]
+    validQuirks: List[str]

package/python/opentrons_shared_data/pipette/file_operation_helpers.py

@@ -0,0 +1,37 @@
+import json
+from typing import Any, Dict, Union
+from .types import MutableConfig, QuirkConfig
+from .model_constants import VALID_QUIRKS
+
+
+DecoderType = Union[Dict[str, Any], Dict[str, QuirkConfig], MutableConfig]
+
+
+class MutableConfigurationEncoder(json.JSONEncoder):
+    def default(self, obj: object) -> Any:
+        if isinstance(obj, MutableConfig) or isinstance(obj, QuirkConfig):
+            return obj.dict_for_encode()
+        return json.JSONEncoder.default(self, obj)
+
+
+class MutableConfigurationDecoder(json.JSONDecoder):
+    def __init__(self) -> None:
+        super().__init__(
+            object_hook=self.dict_to_obj,
+        )
+
+    def dict_to_obj(self, d: object) -> DecoderType:
+        if isinstance(d, dict):
+            converted = dict(d)
+            if converted.get("value"):
+                return self._decode_mutable_config("", converted)
+            elif all(isinstance(v, bool) for v in converted.values()):
+                return {
+                    q: QuirkConfig.validate_and_build(q, b)
+                    for q, b in converted.items()
+                    if q in VALID_QUIRKS
+                }
+        return d  # type: ignore
+
+    def _decode_mutable_config(self, k: str, obj: Dict[str, Any]) -> MutableConfig:
+        return MutableConfig.build(**obj, name=k)