opentrons 8.6.0__py3-none-any.whl

opentrons/__init__.py

@@ -0,0 +1,150 @@
+import os
+
+from pathlib import Path
+import logging
+import re
+from typing import Any, List, Tuple
+
+from opentrons.drivers.serial_communication import get_ports_by_name
+from opentrons.hardware_control import (
+    API as HardwareAPI,
+    ThreadManager,
+    ThreadManagedHardware,
+    types as hw_types,
+)
+
+from opentrons.config import (
+    feature_flags as ff,
+    name,
+    robot_configs,
+    IS_ROBOT,
+    ROBOT_FIRMWARE_DIR,
+)
+from opentrons.util import logging_config
+from opentrons.protocols.types import ApiDeprecationError
+from opentrons.protocols.api_support.types import APIVersion
+
+from ._version import version
+
+HERE = os.path.abspath(os.path.dirname(__file__))
+__version__ = version
+
+
+LEGACY_MODULES = ["robot", "reset", "instruments", "containers", "labware", "modules"]
+
+
+__all__ = ["version", "__version__", "HERE", "config"]
+
+
+def __getattr__(attrname: str) -> None:
+    """
+    Prevent import of legacy modules from global to officially
+    deprecate Python API Version 1.0.
+    """
+    if attrname in LEGACY_MODULES:
+        raise ApiDeprecationError(APIVersion(1, 0))
+    raise AttributeError(attrname)
+
+
+def __dir__() -> List[str]:
+    return sorted(__all__ + LEGACY_MODULES)
+
+
+log = logging.getLogger(__name__)
+
+
+SMOOTHIE_HEX_RE = re.compile("smoothie-(.*).hex")
+
+
+def _find_smoothie_file() -> Tuple[Path, str]:
+    resources: List[Path] = []
+
+    # Search for smoothie files in /usr/lib/firmware first then fall back to
+    # value packed in wheel
+    if IS_ROBOT:
+        resources.extend(ROBOT_FIRMWARE_DIR.iterdir())  # type: ignore
+
+    resources_path = Path(HERE) / "resources"
+    resources.extend(resources_path.iterdir())
+
+    for path in resources:
+        matches = SMOOTHIE_HEX_RE.search(path.name)
+        if matches:
+            branch_plus_ref = matches.group(1)
+            return path, branch_plus_ref
+    raise OSError(f"Could not find smoothie firmware file in {resources_path}")
+
+
+def _get_motor_control_serial_port() -> Any:
+    port = os.environ.get("OT_SMOOTHIE_EMULATOR_URI")
+
+    if port is None:
+        smoothie_id = os.environ.get("OT_SMOOTHIE_ID", "AMA")
+        # TODO(mc, 2021-08-01): raise a more informative exception than
+        # IndexError if a valid serial port is not found
+        port = get_ports_by_name(device_name=smoothie_id)[0]
+
+    log.info(f"Connecting to motor controller at port {port}")
+    return port
+
+
+def should_use_ot3() -> bool:
+    """Return true if ot3 hardware controller should be used."""
+    if ff.enable_ot3_hardware_controller():
+        try:
+            from opentrons_hardware.drivers.can_bus import CanDriver  # noqa: F401
+
+            return True
+        except ModuleNotFoundError:
+            log.exception("Cannot use OT3 Hardware controller.")
+    return False
+
+
+async def _create_thread_manager() -> ThreadManagedHardware:
+    """Build the hardware controller wrapped in a ThreadManager.
+
+    .. deprecated:: 4.6
+        ThreadManager is on its way out.
+    """
+    if os.environ.get("ENABLE_VIRTUAL_SMOOTHIE"):
+        log.info("Initialized robot using virtual Smoothie")
+        thread_manager: ThreadManagedHardware = ThreadManager(
+            HardwareAPI.build_hardware_simulator
+        )
+    elif should_use_ot3():
+        from opentrons.hardware_control.ot3api import OT3API
+
+        thread_manager = ThreadManager(
+            ThreadManager.nonblocking_builder(OT3API.build_hardware_controller),
+            use_usb_bus=ff.rear_panel_integration(),
+            status_bar_enabled=ff.status_bar_enabled(),
+            feature_flags=hw_types.HardwareFeatureFlags.build_from_ff(),
+        )
+    else:
+        thread_manager = ThreadManager(
+            ThreadManager.nonblocking_builder(HardwareAPI.build_hardware_controller),
+            port=_get_motor_control_serial_port(),
+            firmware=_find_smoothie_file(),
+            feature_flags=hw_types.HardwareFeatureFlags.build_from_ff(),
+        )
+
+    try:
+        await thread_manager.managed_thread_ready_async()
+    except RuntimeError:
+        log.exception("Could not build hardware controller, forcing virtual")
+        thread_manager = ThreadManager(HardwareAPI.build_hardware_simulator)
+
+    return thread_manager
+
+
+async def initialize() -> ThreadManagedHardware:
+    """
+    Initialize the Opentrons hardware returning a hardware instance.
+    """
+    robot_conf = robot_configs.load()
+    logging_config.log_init(robot_conf.log_level)
+
+    log.info(f"API server version: {version}")
+    log.info(f"Robot Name: {name()}")
+
+    return await _create_thread_manager()

opentrons/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '8.6.0'
+__version_tuple__ = version_tuple = (8, 6, 0)
+
+__commit_id__ = commit_id = None

opentrons/calibration_storage/__init__.py

@@ -0,0 +1,54 @@
+from .ot3 import gripper_offset
+from .ot2 import mark_bad_calibration
+
+from .deck_configuration import (
+    serialize_deck_configuration,
+    deserialize_deck_configuration,
+)
+
+# TODO these functions are only used in robot server. We should think about moving them and/or
+# abstracting it away from a robot specific function. We should also check if the tip rack
+# definition information is still needed.
+from .ot2.tip_length import (
+    get_custom_tiprack_definition_for_tlc,
+    get_all_tip_length_calibrations,
+    _save_custom_tiprack_definition,
+)
+from .ot2.pipette_offset import get_all_pipette_offset_calibrations
+from .ot3.deck_attitude import (
+    save_robot_belt_attitude,
+    get_robot_belt_attitude,
+    delete_robot_belt_attitude,
+)
+from .ot2.deck_attitude import (
+    save_robot_deck_attitude,
+    get_robot_deck_attitude,
+    delete_robot_deck_attitude,
+)
+
+from . import ot2, ot3, helpers
+
+__all__ = [
+    "helpers",
+    # deck calibration functions
+    "save_robot_deck_attitude",
+    "get_robot_deck_attitude",
+    "delete_robot_deck_attitude",
+    "save_robot_belt_attitude",
+    "get_robot_belt_attitude",
+    "delete_robot_belt_attitude",
+    # deck configuration functions
+    "serialize_deck_configuration",
+    "deserialize_deck_configuration",
+    # functions only used in robot server
+    "_save_custom_tiprack_definition",
+    "get_custom_tiprack_definition_for_tlc",
+    "get_all_pipette_offset_calibrations",
+    "get_all_tip_length_calibrations",
+    # file exports
+    "gripper_offset",
+    "mark_bad_calibration",
+    # Platform specific submodules
+    "ot2",
+    "ot3",
+]

opentrons/calibration_storage/deck_configuration.py

@@ -0,0 +1,62 @@
+from datetime import datetime
+from typing import List, Optional, Tuple
+
+import pydantic
+
+from .types import CutoutFixturePlacement
+from . import file_operators as io
+
+
+class _CutoutFixturePlacementModel(pydantic.BaseModel):
+    cutoutId: str
+    cutoutFixtureId: str
+    opentronsModuleSerialNumber: Optional[str] = None
+
+
+class _DeckConfigurationModel(pydantic.BaseModel):
+    """The on-filesystem representation of a deck configuration."""
+
+    cutoutFixtures: List[_CutoutFixturePlacementModel]
+    lastModified: datetime
+
+
+def serialize_deck_configuration(
+    cutout_fixture_placements: List[CutoutFixturePlacement], last_modified: datetime
+) -> bytes:
+    """Serialize a deck configuration for storing on the filesystem."""
+    data = _DeckConfigurationModel.model_construct(
+        cutoutFixtures=[
+            _CutoutFixturePlacementModel.model_construct(
+                cutoutId=e.cutout_id,
+                cutoutFixtureId=e.cutout_fixture_id,
+                opentronsModuleSerialNumber=e.opentrons_module_serial_number,
+            )
+            for e in cutout_fixture_placements
+        ],
+        lastModified=last_modified,
+    )
+    return io.serialize_pydantic_model(data)
+
+
+# TODO(mm, 2023-11-21): If the data is corrupt, we should propagate the underlying error.
+# And there should be an enumerated "corrupt storage" error in shared-data.
+def deserialize_deck_configuration(
+    serialized: bytes,
+) -> Optional[Tuple[List[CutoutFixturePlacement], datetime]]:
+    """Deserialize bytes previously serialized by `serialize_deck_configuration()`.
+
+    Returns a tuple `(deck_configuration, last_modified_time)`, or `None` if the data is corrupt.
+    """
+    parsed = io.deserialize_pydantic_model(serialized, _DeckConfigurationModel)
+    if parsed is None:
+        return None
+    else:
+        cutout_fixture_placements = [
+            CutoutFixturePlacement(
+                cutout_id=e.cutoutId,
+                cutout_fixture_id=e.cutoutFixtureId,
+                opentrons_module_serial_number=e.opentronsModuleSerialNumber,
+            )
+            for e in parsed.cutoutFixtures
+        ]
+        return cutout_fixture_placements, parsed.lastModified

opentrons/calibration_storage/encoder_decoder.py

@@ -0,0 +1,31 @@
+""" opentrons.calibration_storage.encoder_decoder: classes that
+allow you to customize serialization to/from json.
+"""
+import json
+import datetime
+from typing import Any, cast
+
+
+class DateTimeEncoder(json.JSONEncoder):
+    def default(self, obj: object) -> Any:
+        if isinstance(obj, datetime.datetime):
+            return obj.isoformat()
+        return json.JSONEncoder.default(self, obj)
+
+
+class DateTimeDecoder(json.JSONDecoder):
+    def __init__(self) -> None:
+        super().__init__(object_hook=self.dict_to_obj)
+
+    def dict_to_obj(self, d: object) -> Any:
+        if isinstance(d, dict):
+            d = {k: self._decode_datetime(v) for k, v in d.items()}
+        return d
+
+    def _decode_datetime(self, obj: object) -> Any:
+        try:
+            return datetime.datetime.fromisoformat(cast(str, obj))
+        except ValueError:
+            return obj
+        except TypeError:
+            return self.dict_to_obj(obj)

opentrons/calibration_storage/file_operators.py

@@ -0,0 +1,142 @@
+""" opentrons.calibration_storage.file_operators: functions that
+manipulate the file system.
+
+These methods should only be imported inside the calibration_storage
+module, except in the special case of v2 labware support in
+the v1 API.
+"""
+import datetime
+import json
+import logging
+import typing
+from pathlib import Path
+
+import pydantic
+
+from .encoder_decoder import DateTimeEncoder, DateTimeDecoder
+
+
+_log = logging.getLogger(__name__)
+
+
+DecoderType = typing.Type[json.JSONDecoder]
+EncoderType = typing.Type[json.JSONEncoder]
+
+
+# TODO(mc, 2022-06-07): replace with Path.unlink(missing_ok=True)
+# when we are on Python >= 3.8
+def delete_file(path: Path) -> None:
+    try:
+        path.unlink()
+    except FileNotFoundError:
+        pass
+
+
+# TODO: This is private but used by other files.
+def _remove_json_files_in_directories(p: Path) -> None:
+    """Delete .json files in the given directory and its subdirectories."""
+    for item in p.iterdir():
+        if item.is_dir():
+            _remove_json_files_in_directories(item)
+        elif item.suffix == ".json":
+            delete_file(item)
+
+
+def _assert_last_modified_value(calibration_dict: typing.Dict[str, typing.Any]) -> None:
+    last_modified = calibration_dict.get("lastModified")
+    if last_modified:
+        assert isinstance(calibration_dict["lastModified"], datetime.datetime), (
+            "invalid decoded value type for lastModified: got "
+            f"{type(calibration_dict['lastModified']).__name__},"
+            "expected datetime"
+        )
+
+
+def read_cal_file(
+    file_path: Path, decoder: DecoderType = DateTimeDecoder
+) -> typing.Dict[str, typing.Any]:
+    """
+    Function used to read data from a file
+
+    :param file_path: path to look for data at
+    :param decoder: if there is any specialized decoder needed.
+    The default decoder is the date time decoder.
+    :return: Data from the file
+    """
+    # TODO(6/16): We should use tagged unions for
+    # both the calibration and tip length dicts to better
+    # categorize the Typed Dicts used here.
+    # This can be done when the labware endpoints
+    # are refactored to grab tip length calibration
+    # from the correct locations.
+    with open(file_path, "r", encoding="utf-8") as f:
+        calibration_data = typing.cast(
+            typing.Dict[str, typing.Any],
+            json.load(f, cls=decoder),
+        )
+    if isinstance(calibration_data.values(), dict):
+        _assert_last_modified_value(dict(calibration_data.values()))
+    else:
+        _assert_last_modified_value(calibration_data)
+    return calibration_data
+
+
+def save_to_file(
+    directory_path: Path,
+    # todo(mm, 2023-11-15): This file_name argument does not include the file
+    # extension, which is inconsistent with read_cal_file(). The two should match.
+    file_name: str,
+    data: typing.Union[pydantic.BaseModel, typing.Dict[str, typing.Any], typing.Any],
+    encoder: EncoderType = DateTimeEncoder,
+) -> None:
+    """
+    Function used to save data to a file
+
+    :param directory_path: path to the directory in which to save the data
+    :param file_name: name of the file within the directory, *without the extension*.
+    :param data: The data to save. Either a Pydantic model, or a JSON-like dict to pass to
+        `json.dumps()`. If you're storing a Pydantic model, prefer `save_pydantic_model_to_file()`
+        and `read_pydantic_model_from_file()` for new code.
+    :param encoder: if there is any specialized encoder needed.
+    The default encoder is the date time encoder.
+    """
+    directory_path.mkdir(parents=True, exist_ok=True)
+    file_path = directory_path / f"{file_name}.json"
+    json_data = (
+        data.model_dump_json()
+        if isinstance(data, pydantic.BaseModel)
+        else json.dumps(data, cls=encoder)
+    )
+    file_path.write_text(json_data, encoding="utf-8")
+
+
+def serialize_pydantic_model(data: pydantic.BaseModel) -> bytes:
+    """Safely serialize data from a Pydantic model into a form suitable for storing on disk."""
+    return data.model_dump_json(by_alias=True).encode("utf-8")
+
+
+_ModelT = typing.TypeVar("_ModelT", bound=pydantic.BaseModel)
+
+
+# TODO(mm, 2023-11-20): We probably want to distinguish "missing file" from "corrupt file."
+# The caller needs to deal with those cases separately because the appropriate action depends on
+# context. For example, when running protocols through robot-server, if the file is corrupt, it's
+# safe-ish to fall back to a default because the Opentrons App will let the user confirm everything
+# before starting the run. But when running protocols through the non-interactive
+# `opentrons_execute`, we don't want it to silently use default data if the file is corrupt.
+def deserialize_pydantic_model(
+    serialized: bytes,
+    model: typing.Type[_ModelT],
+) -> typing.Optional[_ModelT]:
+    """Safely read bytes from `serialize_pydantic_model()` back into a Pydantic model.
+
+    Returns `None` if the file is missing or corrupt.
+    """
+    try:
+        return model.model_validate_json(serialized)
+    except json.JSONDecodeError:
+        _log.warning("Data is not valid JSON.", exc_info=True)
+        return None
+    except pydantic.ValidationError:
+        _log.warning(f"Data is malformed as a {model}.", exc_info=True)
+        return None

opentrons/calibration_storage/helpers.py

@@ -0,0 +1,103 @@
+""" opentrons.calibration_storage.helpers: various miscellaneous
+functions
+
+This module has functions that you can import to save robot or
+labware calibration to its designated file location.
+"""
+import json
+from typing import Any, Union, List, Dict, TYPE_CHECKING, cast, Tuple
+from dataclasses import is_dataclass, asdict
+
+
+from hashlib import sha256
+
+from . import types as local_types
+
+if TYPE_CHECKING:
+    from opentrons_shared_data.labware.types import LabwareDefinition
+    from opentrons_shared_data.pipette.types import LabwareUri
+
+
+def dict_filter_none(data: List[Tuple[str, Any]]) -> Dict[str, Any]:
+    """
+    Helper function to filter out None keys from a dataclass
+    before saving to file.
+    """
+    return dict(item for item in data if item[1] is not None)
+
+
+def convert_to_dict(obj: Any) -> Dict[str, Any]:
+    # The correct way to type this is described here:
+    # https://github.com/python/mypy/issues/6568
+    # Unfortunately, since it's not currently supported I have an
+    # assert check instead.
+    assert is_dataclass(obj) and not isinstance(
+        obj, type
+    ), "This function is intended for dataclasses only"
+    return asdict(obj, dict_factory=dict_filter_none)
+
+
+# TODO(mc, 2021-11-09): this hashing function may produce different hashes
+# for semantically identical labware defs. For example, a value of `10` will
+# produce a different hash than a value of `10.0`. Hashing should be produce
+# identical hashes for `==` values. This could be done by running defs through
+# Pydantic or similar rather via json.dumps
+def hash_labware_def(labware_def: "LabwareDefinition") -> str:
+    """
+    Helper function to take in a labware definition and return
+    a hashed string of key elements from the labware definition
+    to make it a unique identifier.
+
+    :param labware_def: Full labware definition
+    :returns: sha256 string
+    """
+    # remove keys that do not affect run
+    blocklist = ["metadata", "brand", "groups"]
+    def_no_metadata = {k: v for k, v in labware_def.items() if k not in blocklist}
+    sorted_def_str = json.dumps(def_no_metadata, sort_keys=True, separators=(",", ":"))
+
+    return sha256(sorted_def_str.encode("utf-8")).hexdigest()
+
+
+def details_from_uri(uri: str, delimiter: str = "/") -> local_types.UriDetails:
+    """
+    Unpack a labware URI to get the namespace, loadname and version
+    """
+    try:
+        info = uri.split(delimiter)
+        return local_types.UriDetails(
+            namespace=info[0], load_name=info[1], version=int(info[2])
+        )
+    except IndexError:
+        # Here we are assuming that the 'uri' passed in is actually
+        # the loadname, though sometimes it may be an empty string.
+        return local_types.UriDetails(namespace="", load_name=uri, version=1)
+
+
+def uri_from_details(
+    namespace: str, load_name: str, version: Union[str, int], delimiter: str = "/"
+) -> "LabwareUri":
+    """Build a labware URI from its details.
+
+    A labware URI is a string that uniquely specifies a labware definition.
+
+    :returns str: The URI.
+    """
+    return cast("LabwareUri", f"{namespace}{delimiter}{load_name}{delimiter}{version}")
+
+
+def uri_from_definition(
+    definition: "LabwareDefinition", delimiter: str = "/"
+) -> "LabwareUri":
+    """Build a labware URI from its definition.
+
+    A labware URI is a string that uniquely specifies a labware definition.
+
+    :returns str: The URI.
+    """
+    return uri_from_details(
+        namespace=definition["namespace"],
+        load_name=definition["parameters"]["loadName"],
+        version=definition["version"],
+        delimiter=delimiter,
+    )

opentrons/calibration_storage/ot2/__init__.py

@@ -0,0 +1,34 @@
+from . import (
+    models,
+    mark_bad_calibration,
+)
+from .pipette_offset import (
+    save_pipette_calibration,
+    clear_pipette_offset_calibrations,
+    get_pipette_offset,
+    delete_pipette_offset_file,
+)
+
+from .tip_length import (
+    clear_tip_length_calibration,
+    create_tip_length_data,
+    save_tip_length_calibration,
+    tip_lengths_for_pipette,
+    load_tip_length_calibration,
+    delete_tip_length_calibration,
+)
+
+__all__ = [
+    "models",
+    "mark_bad_calibration",
+    "save_pipette_calibration",
+    "clear_pipette_offset_calibrations",
+    "get_pipette_offset",
+    "delete_pipette_offset_file",
+    "clear_tip_length_calibration",
+    "create_tip_length_data",
+    "save_tip_length_calibration",
+    "tip_lengths_for_pipette",
+    "load_tip_length_calibration",
+    "delete_tip_length_calibration",
+]

opentrons/calibration_storage/ot2/deck_attitude.py

@@ -0,0 +1,85 @@
+import json
+import logging
+from pydantic import ValidationError
+from typing import Optional, Union
+from dataclasses import asdict
+
+from opentrons import config
+from opentrons.util.helpers import utc_now
+
+
+from .. import file_operators as io, types as local_types
+
+from .models import v1
+
+log = logging.getLogger(__name__)
+
+# Delete Deck Calibration
+
+
+def delete_robot_deck_attitude() -> None:
+    """
+    Delete the robot deck attitude calibration.
+    """
+    legacy_deck_calibration_file = config.get_opentrons_path("deck_calibration_file")
+
+    robot_dir = config.get_opentrons_path("robot_calibration_dir")
+    gantry_path = robot_dir / "deck_calibration.json"
+
+    # TODO(mc, 2022-06-08): this leaves legacy deck calibration backup files in place
+    # we should eventually clean them up, too, because they can really crowd /data/
+    io.delete_file(legacy_deck_calibration_file)
+    io.delete_file(gantry_path)
+
+
+# Save Deck Calibration
+
+
+def save_robot_deck_attitude(
+    transform: local_types.AttitudeMatrix,
+    pip_id: Optional[str],
+    lw_hash: Optional[str],
+    source: Optional[local_types.SourceType] = None,
+    cal_status: Optional[
+        Union[local_types.CalibrationStatus, v1.CalibrationStatus]
+    ] = None,
+) -> None:
+    robot_dir = config.get_opentrons_path("robot_calibration_dir")
+
+    if isinstance(cal_status, local_types.CalibrationStatus):
+        cal_status_model = v1.CalibrationStatus(**asdict(cal_status))
+    elif isinstance(cal_status, v1.CalibrationStatus):
+        cal_status_model = cal_status
+    else:
+        cal_status_model = v1.CalibrationStatus()
+
+    gantry_calibration = v1.DeckCalibrationModel(
+        attitude=transform,
+        pipette_calibrated_with=pip_id,
+        last_modified=utc_now(),
+        tiprack=lw_hash,
+        source=source or local_types.SourceType.user,
+        status=cal_status_model,
+    )
+    # convert to schema + validate json conversion
+    io.save_to_file(robot_dir, "deck_calibration", gantry_calibration)
+
+
+# Get Deck Calibration
+
+
+def get_robot_deck_attitude() -> Optional[v1.DeckCalibrationModel]:
+    deck_calibration_path = (
+        config.get_opentrons_path("robot_calibration_dir") / "deck_calibration.json"
+    )
+    try:
+        return v1.DeckCalibrationModel(**io.read_cal_file(deck_calibration_path))
+    except FileNotFoundError:
+        log.warning("Deck calibration not found.")
+        pass
+    except (json.JSONDecodeError, ValidationError):
+        log.warning(
+            "Deck calibration is malformed. Please factory reset your calibrations.",
+            exc_info=True,
+        )
+    return None