opentrons 8.6.0a1__py3-none-any.whl

opentrons/protocols/api_support/labware_like.py

@@ -0,0 +1,233 @@
+from enum import Enum, auto
+from typing import TYPE_CHECKING, Any, Optional, Union, cast, Tuple, List, Set
+
+if TYPE_CHECKING:
+    from opentrons.protocol_api.labware import Labware, Well
+    from opentrons.protocol_api.core.legacy.module_geometry import ModuleGeometry
+    from opentrons.protocol_api.module_contexts import ModuleContext
+    from opentrons.protocol_api._types import OffDeckType
+
+WrappableLabwareLike = Union[
+    "Labware",
+    "Well",
+    str,
+    "ModuleGeometry",
+    "LabwareLike",
+    None,
+    "OffDeckType",
+    "ModuleContext",
+]
+
+
+class LabwareLikeType(int, Enum):
+    LABWARE = auto()
+    SLOT = auto()
+    WELL = auto()
+    MODULE = auto()
+    NONE = auto()
+    OFF_DECK = auto()
+
+
+class LabwareLike:
+    """A wrapper for a labware like object."""
+
+    def __init__(self, labware_like: WrappableLabwareLike):
+        """
+        Create a labware like object. Used by Location object's labware field.
+        """
+        # Import locally to avoid circular dependency
+        from opentrons.protocol_api.labware import Labware, Well
+        from opentrons.protocol_api.core.legacy.module_geometry import (
+            ModuleGeometry,
+        )
+        from opentrons.protocol_api.module_contexts import ModuleContext
+        from opentrons.protocol_api._types import OffDeckType
+
+        self._labware_like = labware_like
+        self._type = LabwareLikeType.NONE
+
+        # TODO(mc 2022-10-28): for the love of all that is holy
+        # do not use __repr__ or __str__ to do this; it's so confusing
+        if isinstance(self._labware_like, Well):
+            self._type = LabwareLikeType.WELL
+            self._as_str = repr(self._labware_like)
+        elif isinstance(self._labware_like, Labware):
+            self._type = LabwareLikeType.LABWARE
+            self._as_str = repr(self._labware_like)
+        elif isinstance(self._labware_like, str):
+            self._type = LabwareLikeType.SLOT
+            self._as_str = self._labware_like
+        elif isinstance(self._labware_like, (ModuleGeometry, ModuleContext)):
+            self._type = LabwareLikeType.MODULE
+            self._as_str = repr(self._labware_like)
+        elif isinstance(self._labware_like, LabwareLike):
+            self._type = self._labware_like._type
+            self._as_str = self._labware_like._as_str
+            self._labware_like = self._labware_like.object
+        elif isinstance(self._labware_like, OffDeckType):
+            self._type = LabwareLikeType.OFF_DECK
+            self._as_str = repr(self._labware_like)
+        else:
+            self._as_str = ""
+
+    @property
+    def object(self) -> WrappableLabwareLike:
+        return self._labware_like
+
+    @property
+    def object_type(self) -> LabwareLikeType:
+        return self._type
+
+    @property
+    def has_parent(self) -> bool:
+        return self._type in {
+            LabwareLikeType.LABWARE,
+            LabwareLikeType.WELL,
+            LabwareLikeType.MODULE,
+        }
+
+    @property
+    def parent(self) -> "LabwareLike":
+        # Type ignoring because type checker is not aware that has_parent
+        # performs the validation.
+        parent = None
+        if self.has_parent:
+            parent = self.object.parent  # type: ignore
+        return LabwareLike(parent)
+
+    @property
+    def is_well(self) -> bool:
+        return self.object_type == LabwareLikeType.WELL
+
+    @property
+    def is_labware(self) -> bool:
+        return self.object_type == LabwareLikeType.LABWARE
+
+    @property
+    def is_slot(self) -> bool:
+        return self.object_type == LabwareLikeType.SLOT
+
+    @property
+    def is_empty(self) -> bool:
+        return self.object_type == LabwareLikeType.NONE
+
+    @property
+    def is_module(self) -> bool:
+        return self.object_type == LabwareLikeType.MODULE
+
+    def as_well(self) -> "Well":
+        # Import locally to avoid circular dependency
+        from opentrons.protocol_api.labware import Well
+
+        return cast(Well, self.object)
+
+    def as_labware(self) -> "Labware":
+        # Import locally to avoid circular dependency
+        from opentrons.protocol_api.labware import Labware
+
+        return cast(Labware, self.object)
+
+    def as_module(self) -> Union["ModuleContext", "ModuleGeometry"]:
+        from opentrons.protocol_api.core.legacy.module_geometry import (
+            ModuleGeometry,
+        )
+        from opentrons.protocol_api.module_contexts import ModuleContext
+
+        if isinstance(self.object, ModuleContext):
+            return self.object
+
+        return cast(ModuleGeometry, self.object)
+
+    def get_parent_labware_and_well(
+        self,
+    ) -> Tuple[Optional["Labware"], Optional["Well"]]:
+        """Attempt to split into a labware and well."""
+        if self.is_labware:
+            return self.as_labware(), None
+        elif self.is_well and self.parent:
+            return (
+                self.parent.as_labware(),
+                self.as_well(),
+            )
+        else:
+            return None, None
+
+    def first_parent(self) -> Optional[str]:
+        """Return the topmost parent of this location. It should be
+        either a string naming a slot or a None if the location isn't
+        associated with a slot"""
+
+        # cycle-detecting recursive climbing
+        seen: Set[LabwareLike] = set()
+
+        # internal function to have the cycle detector different per call
+        def _fp_recurse(location: LabwareLike) -> Optional[str]:
+            if location in seen:
+                raise RuntimeError("Cycle in labware parent")
+            seen.add(location)
+            if location.is_empty:
+                return None
+            elif location.is_slot:
+                return str(location)
+            else:
+                return location.parent.first_parent()
+
+        return _fp_recurse(self)
+
+    def module_parent(self) -> Union["ModuleGeometry", "ModuleContext", None]:
+        """
+        Return the closest parent of this LabwareLike (including, possibly,
+        the wrapped object) that is a ModuleGeometry
+        """
+
+        def recursive_get_module_parent(
+            obj: LabwareLike,
+        ) -> Union["ModuleGeometry", "ModuleContext", None]:
+            if obj.is_module:
+                return obj.as_module()
+            next_obj = obj.parent
+            if next_obj.is_empty:
+                return None
+            else:
+                return recursive_get_module_parent(obj.parent)
+
+        if self.is_empty:
+            return None
+        return recursive_get_module_parent(self)
+
+    def quirks_from_any_parent(self) -> Set[str]:
+        """Walk the tree of wells and labwares and extract quirks"""
+
+        def recursive_get_quirks(obj: LabwareLike, found: List[str]) -> List[str]:
+            if obj.is_labware:
+                return found + obj.as_labware().quirks
+            elif obj.is_well:
+                return recursive_get_quirks(obj.parent, found)
+            else:
+                return found
+
+        return set(recursive_get_quirks(self, []))
+
+    def is_fixed_trash(self) -> bool:
+        """Check if fixedTrash quirk is in any parent."""
+        return "fixedTrash" in self.quirks_from_any_parent()
+
+    def center_multichannel_on_wells(self) -> bool:
+        """Check if centerMultichannelOnWells quirk is in any parent."""
+        return "centerMultichannelOnWells" in self.quirks_from_any_parent()
+
+    def __str__(self) -> str:
+        return self._as_str
+
+    def __repr__(self) -> str:
+        return str(self)
+
+    def __eq__(self, other: Any) -> bool:
+        return (
+            other is not None
+            and isinstance(other, LabwareLike)
+            and self.object == other.object
+        )
+
+    def __hash__(self) -> int:
+        return id(self)

opentrons/protocols/api_support/tip_tracker.py

@@ -0,0 +1,175 @@
+from itertools import dropwhile, takewhile
+from typing import Optional, Sequence
+
+from opentrons.protocol_api.core.well import AbstractWellCore
+
+
+Wells = Sequence[AbstractWellCore]
+WellColumns = Sequence[Wells]
+
+
+class TipTracker:
+    def __init__(self, columns: WellColumns):
+        self._columns = columns
+
+    def next_tip(
+        self, num_tips: int = 1, starting_tip: Optional[AbstractWellCore] = None
+    ) -> Optional[AbstractWellCore]:
+        """
+        Find the next valid well for pick-up.
+
+        Determines the next valid start tip from which to retrieve the
+        specified number of tips. There must be at least `num_tips` sequential
+        wells for which all wells have tips, in the same column.
+
+        :param num_tips: target number of sequential tips in the same column
+        :type num_tips: int
+        :param starting_tip: The :py:class:`.Well` from which to start search.
+                for an available tip.
+        :type starting_tip: :py:class:`.Well`
+        :return: the :py:class:`.Well` meeting the target criteria, or None
+        """
+        columns: WellColumns = self._columns
+        if starting_tip:
+            # Remove columns preceding the one with the pipette's starting tip
+            drop_undefined_columns = list(
+                dropwhile(lambda x: starting_tip not in x, columns)
+            )
+            # Remove tips preceding the starting tip in the first column
+            drop_undefined_columns[0] = list(
+                dropwhile(lambda w: starting_tip is not w, drop_undefined_columns[0])
+            )
+            columns = drop_undefined_columns
+
+        drop_leading_empties = [
+            list(dropwhile(lambda x: not x.has_tip(), column)) for column in columns
+        ]
+        drop_at_first_gap = [
+            list(takewhile(lambda x: x.has_tip(), column))
+            for column in drop_leading_empties
+        ]
+        long_enough = [
+            column for column in drop_at_first_gap if len(column) >= num_tips
+        ]
+
+        try:
+            first_long_enough = long_enough[0]
+            result: Optional[AbstractWellCore] = first_long_enough[0]
+        except IndexError:
+            result = None
+
+        return result
+
+    def use_tips(
+        self,
+        start_well: AbstractWellCore,
+        num_channels: int = 1,
+        fail_if_full: bool = False,
+    ) -> None:
+        """
+        Removes tips from the tip tracker.
+
+        This method should be called when a tip is picked up. Generally, it
+        will be called with `num_channels=1` or `num_channels=8` for single-
+        and multi-channel respectively. If picking up with more than one
+        channel, this method will automatically determine which tips are used
+        based on the start well, the number of channels, and the geometry of
+        the tiprack.
+
+        :param start_well: The :py:class:`.Well` from which to pick up a tip.
+                           For a single-channel pipette, this is the well to
+                           send the pipette to. For a multi-channel pipette,
+                           this is the well to send the back-most nozzle of the
+                           pipette to.
+        :type start_well: :py:class:`.Well`
+        :param num_channels: The number of channels for the current pipette
+        :type num_channels: int
+        :param fail_if_full: for backwards compatibility
+        """
+        # Select the column of the labware that contains the target well
+        target_column = [col for col in self._columns if start_well in col][0]
+
+        well_idx = target_column.index(start_well)
+        # Number of tips to pick up is the lesser of (1) the number of tips
+        # from the starting well to the end of the column, and (2) the number
+        # of channels of the pipette (so a 4-channel pipette would pick up a
+        # max of 4 tips, and picking up from the 2nd-to-bottom well in a
+        # column would get a maximum of 2 tips)
+        num_tips = min(len(target_column) - well_idx, num_channels)
+        target_wells = target_column[well_idx : well_idx + num_tips]
+
+        # In API version 2.2, we no longer reset the tip tracker when a tip
+        # is dropped back into a tiprack well. This fixes a behavior where
+        # subsequent transfers would reuse the dirty tip. However, sometimes
+        # the user explicitly wants to use a dirty tip, and this check would
+        # raise an exception if they tried to do so.
+        # An extension of work here is to have separate tip trackers for
+        # dirty tips and non-present tips; but until then, we can avoid the
+        # exception.
+        if fail_if_full:
+            assert all(
+                well.has_tip() for well in target_wells
+            ), "{} is out of tips".format(str(self))
+
+        for well in target_wells:
+            well.set_has_tip(False)
+
+    def previous_tip(self, num_tips: int = 1) -> Optional[AbstractWellCore]:
+        """
+        Find the best well to drop a tip in.
+
+        This is the well from which the last tip was picked up, if there's
+        room. It can be used to return tips to the tip tracker.
+
+        :param num_tips: target number of tips to return, sequential in a
+                         column
+        :type num_tips: int
+        :return: The :py:class:`.Well` meeting the target criteria, or ``None``
+        """
+        columns = self._columns
+        drop_leading_filled = [
+            list(dropwhile(lambda x: x.has_tip(), column)) for column in columns
+        ]
+        drop_at_first_gap = [
+            list(takewhile(lambda x: not x.has_tip(), column))
+            for column in drop_leading_filled
+        ]
+        long_enough = [
+            column for column in drop_at_first_gap if len(column) >= num_tips
+        ]
+        try:
+            return long_enough[0][0]
+        except IndexError:
+            return None
+
+    def return_tips(self, start_well: AbstractWellCore, num_channels: int = 1) -> None:
+        """
+        Re-adds tips to the tip tracker
+
+        This method should be called when a tip is dropped in a tiprack. It
+        should be called with ``num_channels=1`` or ``num_channels=8`` for
+        single- and multi-channel respectively. If returning more than one
+        channel, this method will automatically determine which tips are
+        returned based on the start well, the number of channels,
+        and the tiprack geometry.
+
+        Note that unlike :py:meth:`use_tips`, calling this method in a way
+        that would drop tips into wells with tips in them will raise an
+        exception; this should only be called on a valid return of
+        :py:meth:`previous_tip`.
+
+        :param start_well: The :py:class:`.Well` into which to return a tip.
+        :type start_well: :py:class:`.Well`
+        :param num_channels: The number of channels for the current pipette
+        :type num_channels: int
+        """
+        # Select the column that contains the target_well
+        target_column = [col for col in self._columns if start_well in col][0]
+        well_idx = target_column.index(start_well)
+        end_idx = min(well_idx + num_channels, len(target_column))
+        drop_targets = target_column[well_idx:end_idx]
+        for well in drop_targets:
+            if well.has_tip():
+                raise AssertionError(f"Well {repr(well)} has a tip")
+        for well in drop_targets:
+            well.set_has_tip(True)

opentrons/protocols/api_support/types.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+from typing import NamedTuple, TypedDict
+
+
+class APIVersion(NamedTuple):
+    major: int
+    minor: int
+
+    @classmethod
+    def from_string(cls, inp: str) -> APIVersion:
+        parts = inp.split(".")
+        if len(parts) != 2:
+            raise ValueError(inp)
+        intparts = [int(p) for p in parts]
+
+        return cls(major=intparts[0], minor=intparts[1])
+
+    def __str__(self) -> str:
+        return f"{self.major}.{self.minor}"
+
+
+class ThermocyclerStepBase(TypedDict):
+    """Required elements of a thermocycler step: the temperature."""
+
+    temperature: float
+
+
+class ThermocyclerStep(ThermocyclerStepBase, total=False):
+    """Optional elements of a thermocycler step: the hold time. One of these must be present."""
+
+    hold_time_seconds: float
+    hold_time_minutes: float