opentrons 8.4.0a2__py2.py3-none-any.whl → 8.4.0a4__py2.py3-none-any.whl

opentrons/protocol_api/core/instrument.py

@@ -11,7 +11,7 @@ from opentrons.protocols.api_support.util import FlowRates
 from opentrons.protocols.advanced_control.transfers.common import TransferTipPolicyV2
 from opentrons.protocol_api._nozzle_layout import NozzleLayout
 from opentrons.protocol_api._liquid import LiquidClass
-from opentrons.protocol_engine.types.liquid_level_detection import LiquidTrackingType
+from opentrons.protocol_engine.types import LiquidTrackingType
 
 from ..disposal_locations import TrashBin, WasteChute
 from .well import WellCoreType
@@ -359,7 +359,7 @@ class AbstractInstrument(ABC, Generic[WellCoreType, LabwareCoreType]):
         ...
 
     @abstractmethod
-    def transfer_liquid(
+    def transfer_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -367,6 +367,7 @@ class AbstractInstrument(ABC, Generic[WellCoreType, LabwareCoreType]):
         dest: List[Tuple[types.Location, WellCoreType]],
         new_tip: TransferTipPolicyV2,
         tip_racks: List[Tuple[types.Location, LabwareCoreType]],
+        starting_tip: Optional[WellCoreType],
         trash_location: Union[types.Location, TrashBin, WasteChute],
         return_tip: bool,
     ) -> None:
@@ -374,7 +375,7 @@ class AbstractInstrument(ABC, Generic[WellCoreType, LabwareCoreType]):
         ...
 
     @abstractmethod
-    def distribute_liquid(
+    def distribute_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -382,6 +383,7 @@ class AbstractInstrument(ABC, Generic[WellCoreType, LabwareCoreType]):
         dest: List[Tuple[types.Location, WellCoreType]],
         new_tip: TransferTipPolicyV2,
         tip_racks: List[Tuple[types.Location, LabwareCoreType]],
+        starting_tip: Optional[WellCoreType],
         trash_location: Union[types.Location, TrashBin, WasteChute],
         return_tip: bool,
     ) -> None:
@@ -392,7 +394,7 @@ class AbstractInstrument(ABC, Generic[WellCoreType, LabwareCoreType]):
         ...
 
     @abstractmethod
-    def consolidate_liquid(
+    def consolidate_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -400,6 +402,7 @@ class AbstractInstrument(ABC, Generic[WellCoreType, LabwareCoreType]):
         dest: Tuple[types.Location, WellCoreType],
         new_tip: TransferTipPolicyV2,
         tip_racks: List[Tuple[types.Location, LabwareCoreType]],
+        starting_tip: Optional[WellCoreType],
         trash_location: Union[types.Location, TrashBin, WasteChute],
         return_tip: bool,
     ) -> None:

opentrons/protocol_api/core/legacy/legacy_instrument_core.py

@@ -22,7 +22,7 @@ from opentrons.protocols.geometry import planning
 from opentrons.protocol_api._nozzle_layout import NozzleLayout
 from opentrons.protocol_api._liquid import LiquidClass
 
-from opentrons.protocol_engine.types.liquid_level_detection import LiquidTrackingType
+from opentrons.protocol_engine.types import LiquidTrackingType
 
 from ...disposal_locations import TrashBin, WasteChute
 from ..instrument import AbstractInstrument
@@ -438,32 +438,6 @@ class LegacyInstrumentCore(AbstractInstrument[LegacyWellCore, LegacyLabwareCore]
                 location=location, mount=location_cache_mount
             )
 
-    def evotip_seal(
-        self,
-        location: types.Location,
-        well_core: LegacyWellCore,
-        in_place: Optional[bool] = False,
-    ) -> None:
-        """This will never be called because it was added in API 2.22."""
-        assert False, "evotip_seal only supported in API 2.22 & later"
-
-    def evotip_unseal(
-        self, location: types.Location, well_core: WellCore, home_after: Optional[bool]
-    ) -> None:
-        """This will never be called because it was added in API 2.22."""
-        assert False, "evotip_unseal only supported in API 2.22 & later"
-
-    def evotip_dispense(
-        self,
-        location: types.Location,
-        well_core: WellCore,
-        volume: Optional[float] = None,
-        flow_rate: Optional[float] = None,
-        push_out: Optional[float] = None,
-    ) -> None:
-        """This will never be called because it was added in API 2.22."""
-        assert False, "evotip_dispense only supported in API 2.22 & later"
-
     def get_mount(self) -> types.Mount:
         """Get the mount this pipette is attached to."""
         return self._mount
@@ -624,7 +598,7 @@ class LegacyInstrumentCore(AbstractInstrument[LegacyWellCore, LegacyLabwareCore]
         """This will never be called because it was added in API 2.16."""
         pass
 
-    def transfer_liquid(
+    def transfer_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -632,13 +606,14 @@ class LegacyInstrumentCore(AbstractInstrument[LegacyWellCore, LegacyLabwareCore]
         dest: List[Tuple[types.Location, LegacyWellCore]],
         new_tip: TransferTipPolicyV2,
         tip_racks: List[Tuple[types.Location, LegacyLabwareCore]],
+        starting_tip: Optional[LegacyWellCore],
         trash_location: Union[types.Location, TrashBin, WasteChute],
         return_tip: bool,
     ) -> None:
         """This will never be called because it was added in API 2.23"""
         assert False, "transfer_liquid is not supported in legacy context"
 
-    def distribute_liquid(
+    def distribute_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -646,13 +621,14 @@ class LegacyInstrumentCore(AbstractInstrument[LegacyWellCore, LegacyLabwareCore]
         dest: List[Tuple[types.Location, LegacyWellCore]],
         new_tip: TransferTipPolicyV2,
         tip_racks: List[Tuple[types.Location, LegacyLabwareCore]],
+        starting_tip: Optional[LegacyWellCore],
         trash_location: Union[types.Location, TrashBin, WasteChute],
         return_tip: bool,
     ) -> None:
         """This will never be called because it was added in API 2.23"""
         assert False, "distribute_liquid is not supported in legacy context"
 
-    def consolidate_liquid(
+    def consolidate_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -660,6 +636,7 @@ class LegacyInstrumentCore(AbstractInstrument[LegacyWellCore, LegacyLabwareCore]
         dest: Tuple[types.Location, LegacyWellCore],
         new_tip: TransferTipPolicyV2,
         tip_racks: List[Tuple[types.Location, LegacyLabwareCore]],
+        starting_tip: Optional[LegacyWellCore],
         trash_location: Union[types.Location, TrashBin, WasteChute],
         return_tip: bool,
     ) -> None:

opentrons/protocol_api/core/legacy_simulator/legacy_instrument_core.py

@@ -23,7 +23,7 @@ from opentrons_shared_data.errors.exceptions import (
     UnexpectedTipAttachError,
 )
 
-from opentrons.protocol_engine.types.liquid_level_detection import LiquidTrackingType
+from opentrons.protocol_engine.types import LiquidTrackingType
 
 from ..legacy.legacy_labware_core import LegacyLabwareCore
 from ...disposal_locations import TrashBin, WasteChute
@@ -513,7 +513,7 @@ class LegacyInstrumentCoreSimulator(
         """This will never be called because it was added in API 2.15."""
         pass
 
-    def transfer_liquid(
+    def transfer_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -521,13 +521,14 @@ class LegacyInstrumentCoreSimulator(
         dest: List[Tuple[types.Location, LegacyWellCore]],
         new_tip: TransferTipPolicyV2,
         tip_racks: List[Tuple[types.Location, LegacyLabwareCore]],
+        starting_tip: Optional[LegacyWellCore],
         trash_location: Union[types.Location, TrashBin, WasteChute],
         return_tip: bool,
     ) -> None:
         """This will never be called because it was added in API 2.23."""
         assert False, "transfer_liquid is not supported in legacy context"
 
-    def distribute_liquid(
+    def distribute_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -535,13 +536,14 @@ class LegacyInstrumentCoreSimulator(
         dest: List[Tuple[types.Location, LegacyWellCore]],
         new_tip: TransferTipPolicyV2,
         tip_racks: List[Tuple[types.Location, LegacyLabwareCore]],
+        starting_tip: Optional[LegacyWellCore],
         trash_location: Union[types.Location, TrashBin, WasteChute],
         return_tip: bool,
     ) -> None:
         """This will never be called because it was added in API 2.23."""
         assert False, "distribute_liquid is not supported in legacy context"
 
-    def consolidate_liquid(
+    def consolidate_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -549,6 +551,7 @@ class LegacyInstrumentCoreSimulator(
         dest: Tuple[types.Location, LegacyWellCore],
         new_tip: TransferTipPolicyV2,
         tip_racks: List[Tuple[types.Location, LegacyLabwareCore]],
+        starting_tip: Optional[LegacyWellCore],
         trash_location: Union[types.Location, TrashBin, WasteChute],
         return_tip: bool,
     ) -> None:

opentrons/protocol_api/core/well.py

@@ -4,7 +4,7 @@ from abc import ABC, abstractmethod
 from typing import TypeVar, Optional, Union
 
 from opentrons.types import Point
-from opentrons.protocol_engine.types.liquid_level_detection import LiquidTrackingType
+from opentrons.protocol_engine.types import LiquidTrackingType
 
 from .._liquid import Liquid
 

opentrons/protocol_api/instrument_context.py

@@ -42,7 +42,7 @@ from ..protocols.advanced_control.transfers.common import (
     TransferTipPolicyV2,
     TransferTipPolicyV2Type,
 )
-from ..protocol_engine.types.liquid_level_detection import LiquidTrackingType
+from ..protocol_engine.types import LiquidTrackingType
 
 _DEFAULT_ASPIRATE_CLEARANCE = 1.0
 _DEFAULT_DISPENSE_CLEARANCE = 1.0
@@ -1509,7 +1509,7 @@ class InstrumentContext(publisher.CommandPublisher):
             getattr(self, cmd["method"])(*cmd["args"], **cmd["kwargs"])
 
     @requires_version(2, 23)
-    def transfer_liquid(
+    def transfer_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -1526,12 +1526,40 @@ class InstrumentContext(publisher.CommandPublisher):
         return_tip: bool = False,
         visit_every_well: bool = False,
     ) -> InstrumentContext:
-        """Transfer liquid from source to dest using the specified liquid class properties.
+        """Move a particular type of liquid from one well or group of wells to another.
 
-        TODO: Add args description.
+        :param liquid_class: The type of liquid to move. You must specify the liquid class,
+            even if you have used :py:meth:`.load_liquid` to indicate what liquid the
+            source contains.
+        :type liquid_class: :py:class:`.LiquidClass`
+
+        :param volume: The amount, in µL, to aspirate from each source and dispense to
+                       each destination.
+        :param source: A single well or a list of wells to aspirate liquid from.
+        :param dest: A single well or a list of wells to dispense liquid into.
+        :param new_tip: When to pick up and drop tips during the command.
+            Defaults to ``"once"``.
+
+              - ``"once"``: Use one tip for the entire command.
+              - ``"always"``: Use a new tip for each set of aspirate and dispense steps.
+              - ``"per source"``: Use one tip for each source well, even if
+                :ref:`tip refilling <complex-tip-refilling>` is required.
+              - ``"never"``: Do not pick up or drop tips at all.
+
+            See :ref:`param-tip-handling` for details.
+
+        :param trash_location: A trash container, well, or other location to dispose of
+            tips. Depending on the liquid class, the pipette may also blow out liquid here.
+        :param return_tip: Whether to drop used tips in their original locations
+            in the tip rack, instead of the trash.
+        """
+        if volume == 0.0:
+            _log.info(
+                f"Transfer of {liquid_class.name} specified with a volume of 0uL."
+                f" Skipping."
+            )
+            return self
 
-        :meta private:
-        """
         transfer_args = verify_and_normalize_transfer_args(
             source=source,
             dest=dest,
@@ -1552,29 +1580,42 @@ class InstrumentContext(publisher.CommandPublisher):
                 " to transfer liquid onto one destinations from many sources, use 'consolidate_liquid'."
             )
 
-        self._core.transfer_liquid(
-            liquid_class=liquid_class,
-            volume=volume,
-            source=[
-                (types.Location(types.Point(), labware=well), well._core)
-                for well in transfer_args.sources_list
-            ],
-            dest=[
-                (types.Location(types.Point(), labware=well), well._core)
-                for well in transfer_args.destinations_list
-            ],
-            new_tip=transfer_args.tip_policy,
-            tip_racks=[
-                (types.Location(types.Point(), labware=rack), rack._core)
-                for rack in transfer_args.tip_racks
-            ],
-            trash_location=transfer_args.trash_location,
-            return_tip=return_tip,
-        )
+        with publisher.publish_context(
+            broker=self.broker,
+            command=cmds.transfer_with_liquid_class(
+                instrument=self,
+                liquid_class=liquid_class,
+                volume=volume,
+                source=source,
+                destination=dest,
+            ),
+        ):
+            self._core.transfer_with_liquid_class(
+                liquid_class=liquid_class,
+                volume=volume,
+                source=[
+                    (types.Location(types.Point(), labware=well), well._core)
+                    for well in transfer_args.sources_list
+                ],
+                dest=[
+                    (types.Location(types.Point(), labware=well), well._core)
+                    for well in transfer_args.destinations_list
+                ],
+                new_tip=transfer_args.tip_policy,
+                tip_racks=[
+                    (types.Location(types.Point(), labware=rack), rack._core)
+                    for rack in transfer_args.tip_racks
+                ],
+                starting_tip=self.starting_tip._core
+                if self.starting_tip is not None
+                else None,
+                trash_location=transfer_args.trash_location,
+                return_tip=return_tip,
+            )
         return self
 
     @requires_version(2, 23)
-    def distribute_liquid(
+    def distribute_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -1590,13 +1631,38 @@ class InstrumentContext(publisher.CommandPublisher):
         visit_every_well: bool = False,
     ) -> InstrumentContext:
         """
-        Distribute liquid from a single source to multiple destinations
-        using the specified liquid class properties.
+        Distribute a particular type of liquid from one well to a group of wells.
+
+        :param liquid_class: The type of liquid to move. You must specify the liquid class,
+            even if you have used :py:meth:`.load_liquid` to indicate what liquid the
+            source contains.
+        :type liquid_class: :py:class:`.LiquidClass`
+
+        :param volume: The amount, in µL, to aspirate from the source and dispense to
+                       each destination.
+        :param source: A single well to aspirate liquid from.
+        :param dest: A list of wells to dispense liquid into.
+        :param new_tip: When to pick up and drop tips during the command.
+            Defaults to ``"once"``.
 
-        TODO: Add args description.
+              - ``"once"`` or ``"per source"``: Use one tip for the entire command.
+              - ``"always"``: Use a new tip for each set of aspirate and dispense steps.
+              - ``"never"``: Do not pick up or drop tips at all.
 
-        :meta private:
+            See :ref:`param-tip-handling` for details.
+
+        :param trash_location: A trash container, well, or other location to dispose of
+            tips. Depending on the liquid class, the pipette may also blow out liquid here.
+        :param return_tip: Whether to drop used tips in their original locations
+            in the tip rack, instead of the trash.
         """
+        if volume == 0.0:
+            _log.info(
+                f"Distribution of {liquid_class.name} specified with a volume of 0uL."
+                f" Skipping."
+            )
+            return self
+
         transfer_args = verify_and_normalize_transfer_args(
             source=source,
             dest=dest,
@@ -1621,29 +1687,42 @@ class InstrumentContext(publisher.CommandPublisher):
             )
 
         verified_source = transfer_args.sources_list[0]
-        self._core.distribute_liquid(
-            liquid_class=liquid_class,
-            volume=volume,
-            source=(
-                types.Location(types.Point(), labware=verified_source),
-                verified_source._core,
+        with publisher.publish_context(
+            broker=self.broker,
+            command=cmds.distribute_with_liquid_class(
+                instrument=self,
+                liquid_class=liquid_class,
+                volume=volume,
+                source=source,
+                destination=dest,
             ),
-            dest=[
-                (types.Location(types.Point(), labware=well), well._core)
-                for well in transfer_args.destinations_list
-            ],
-            new_tip=transfer_args.tip_policy,
-            tip_racks=[
-                (types.Location(types.Point(), labware=rack), rack._core)
-                for rack in transfer_args.tip_racks
-            ],
-            trash_location=transfer_args.trash_location,
-            return_tip=return_tip,
-        )
+        ):
+            self._core.distribute_with_liquid_class(
+                liquid_class=liquid_class,
+                volume=volume,
+                source=(
+                    types.Location(types.Point(), labware=verified_source),
+                    verified_source._core,
+                ),
+                dest=[
+                    (types.Location(types.Point(), labware=well), well._core)
+                    for well in transfer_args.destinations_list
+                ],
+                new_tip=transfer_args.tip_policy,
+                tip_racks=[
+                    (types.Location(types.Point(), labware=rack), rack._core)
+                    for rack in transfer_args.tip_racks
+                ],
+                starting_tip=self.starting_tip._core
+                if self.starting_tip is not None
+                else None,
+                trash_location=transfer_args.trash_location,
+                return_tip=return_tip,
+            )
         return self
 
     @requires_version(2, 23)
-    def consolidate_liquid(
+    def consolidate_with_liquid_class(
         self,
         liquid_class: LiquidClass,
         volume: float,
@@ -1659,13 +1738,39 @@ class InstrumentContext(publisher.CommandPublisher):
         visit_every_well: bool = False,
     ) -> InstrumentContext:
         """
-        Consolidate liquid from multiple sources to a single destination
-        using the specified liquid class properties.
+        Consolidate a particular type of liquid from a group of wells to one well.
 
-        TODO: Add args description.
+        :param liquid_class: The type of liquid to move. You must specify the liquid class,
+            even if you have used :py:meth:`.load_liquid` to indicate what liquid the
+            source contains.
+        :type liquid_class: :py:class:`.LiquidClass`
 
-        :meta private:
+        :param volume: The amount, in µL, to aspirate from the source and dispense to
+                       each destination.
+        :param source: A list of wells to aspirate liquid from.
+        :param dest: A single well to dispense liquid into.
+        :param new_tip: When to pick up and drop tips during the command.
+            Defaults to ``"once"``.
+
+              - ``"once"``: Use one tip for the entire command.
+              - ``"always"``: Use a new tip for each set of aspirate and dispense steps.
+              - ``"per source"``: Not available when consolidating.
+              - ``"never"``: Do not pick up or drop tips at all.
+
+            See :ref:`param-tip-handling` for details.
+
+        :param trash_location: A trash container, well, or other location to dispose of
+            tips. Depending on the liquid class, the pipette may also blow out liquid here.
+        :param return_tip: Whether to drop used tips in their original locations
+            in the tip rack, instead of the trash.
         """
+        if volume == 0.0:
+            _log.info(
+                f"Consolidation of {liquid_class.name} specified with a volume of 0uL."
+                f" Skipping."
+            )
+            return self
+
         transfer_args = verify_and_normalize_transfer_args(
             source=source,
             dest=dest,
@@ -1690,25 +1795,38 @@ class InstrumentContext(publisher.CommandPublisher):
             )
 
         verified_dest = transfer_args.destinations_list[0]
-        self._core.consolidate_liquid(
-            liquid_class=liquid_class,
-            volume=volume,
-            source=[
-                (types.Location(types.Point(), labware=well), well._core)
-                for well in transfer_args.sources_list
-            ],
-            dest=(
-                types.Location(types.Point(), labware=verified_dest),
-                verified_dest._core,
+        with publisher.publish_context(
+            broker=self.broker,
+            command=cmds.consolidate_with_liquid_class(
+                instrument=self,
+                liquid_class=liquid_class,
+                volume=volume,
+                source=source,
+                destination=dest,
             ),
-            new_tip=transfer_args.tip_policy,
-            tip_racks=[
-                (types.Location(types.Point(), labware=rack), rack._core)
-                for rack in transfer_args.tip_racks
-            ],
-            trash_location=transfer_args.trash_location,
-            return_tip=return_tip,
-        )
+        ):
+            self._core.consolidate_with_liquid_class(
+                liquid_class=liquid_class,
+                volume=volume,
+                source=[
+                    (types.Location(types.Point(), labware=well), well._core)
+                    for well in transfer_args.sources_list
+                ],
+                dest=(
+                    types.Location(types.Point(), labware=verified_dest),
+                    verified_dest._core,
+                ),
+                new_tip=transfer_args.tip_policy,
+                tip_racks=[
+                    (types.Location(types.Point(), labware=rack), rack._core)
+                    for rack in transfer_args.tip_racks
+                ],
+                starting_tip=self.starting_tip._core
+                if self.starting_tip is not None
+                else None,
+                trash_location=transfer_args.trash_location,
+                return_tip=return_tip,
+            )
         return self
 
     @requires_version(2, 0)
@@ -2522,10 +2640,6 @@ class InstrumentContext(publisher.CommandPublisher):
         """Check the height of the liquid within a well.
 
         :returns: The height, in mm, of the liquid from the deck.
-
-        :meta private:
-
-        This is intended for Opentrons internal use only and is not a guaranteed API.
         """
         self._raise_if_pressure_not_supported_by_pipette()
         loc = well.top()

opentrons/protocol_api/labware.py

@@ -46,7 +46,7 @@ from opentrons.protocols.api_support.util import (
     APIVersionError,
     UnsupportedAPIError,
 )
-from opentrons.protocol_engine.types.liquid_level_detection import LiquidTrackingType
+from opentrons.protocol_engine.types import LiquidTrackingType
 
 # TODO(mc, 2022-09-02): re-exports provided for backwards compatibility
 # remove when their usage is no longer needed
@@ -684,7 +684,7 @@ class Labware:
         version: Optional[int] = None,
     ) -> Labware:
         """
-        Load a stack of Lids onto a valid Deck Location or Adapter.
+        Load a stack of Opentrons Tough Auto-Sealing Lids onto a valid deck location or adapter.
 
         :param str load_name: A string to use for looking up a lid definition.
             You can find the ``load_name`` for any standard lid on the Opentrons
@@ -705,9 +705,7 @@ class Labware:
             leave this unspecified to let ``load_lid_stack()`` choose a version
             automatically.
 
-        :return: The initialized and loaded labware object representing the Lid Stack.
-
-        :meta private:
+        :return:  The initialized and loaded labware object representing the lid stack.
         """
         if self._api_version < validation.LID_STACK_VERSION_GATE:
             raise APIVersionError(
@@ -773,11 +771,14 @@ class Labware:
                 you must either use ``set_offset()`` on all of them or none of them.
             * - 2.14–2.17
               - ``set_offset()`` is not available, and the API raises an error.
-            * - 2.18 and newer
+            * - 2.18--2.22
               -
                 - Offsets apply to any labware of the same type, in the same on-deck location.
                 - Offsets can't be set on labware that is currently off-deck.
                 - Offsets do not follow a labware instance when using :py:meth:`.move_labware`.
+            * - 2.23 and newer
+              -
+                On Flex, offsets can apply to all labware of the same type, regardless of their on-deck location.
 
         .. note::