opentrons 8.2.0a3__py2.py3-none-any.whl → 8.3.0__py2.py3-none-any.whl

opentrons/protocol_api/labware.py

@@ -1,4 +1,4 @@
-""" opentrons.protocol_api.labware: classes and functions for labware handling
+"""opentrons.protocol_api.labware: classes and functions for labware handling
 
 This module provides things like :py:class:`Labware`, and :py:class:`Well`
 to encapsulate labware instances used in protocols
@@ -13,18 +13,29 @@ from __future__ import annotations
 import logging
 
 from itertools import dropwhile
-from typing import TYPE_CHECKING, Any, List, Dict, Optional, Union, Tuple, cast
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    List,
+    Dict,
+    Optional,
+    Union,
+    Tuple,
+    cast,
+    Sequence,
+    Mapping,
+)
 
 from opentrons_shared_data.labware.types import LabwareDefinition, LabwareParameters
 
-from opentrons.types import Location, Point
+from opentrons.types import Location, Point, NozzleMapInterface
 from opentrons.protocols.api_support.types import APIVersion
 from opentrons.protocols.api_support.util import (
     requires_version,
     APIVersionError,
     UnsupportedAPIError,
 )
-from opentrons.hardware_control.nozzle_manager import NozzleMap
+
 
 # TODO(mc, 2022-09-02): re-exports provided for backwards compatibility
 # remove when their usage is no longer needed
@@ -104,8 +115,23 @@ class Well:
     @property
     @requires_version(2, 0)
     def has_tip(self) -> bool:
-        """Whether this well contains a tip. Always ``False`` if the parent labware
-        isn't a tip rack."""
+        """Whether this well contains an unused tip.
+
+        From API v2.2 on:
+
+        - Returns ``False`` if:
+
+          - the well has no tip present, or
+          - the well has a tip that's been used by the protocol previously
+
+        - Returns ``True`` if the well has an unused tip.
+
+        Before API v2.2:
+
+        - Returns ``True`` as long as the well has a tip, even if it is used.
+
+        Always ``False`` if the parent labware isn't a tip rack.
+        """
         return self._core.has_tip()
 
     @has_tip.setter
@@ -280,6 +306,10 @@ class Well:
 
         :param Liquid liquid: The liquid to load into the well.
         :param float volume: The volume of liquid to load, in µL.
+
+        .. TODO: flag as deprecated in 2.22 docs
+            In API version 2.22 and later, use :py:meth:`~Labware.load_liquid`, :py:meth:`~Labware.load_liquid_by_well`,
+            or :py:meth:`~Labware.load_empty` to load liquid into a well.
         """
         self._core.load_liquid(
             liquid=liquid,
@@ -529,6 +559,7 @@ class Labware:
         self,
         name: str,
         label: Optional[str] = None,
+        lid: Optional[str] = None,
         namespace: Optional[str] = None,
         version: Optional[int] = None,
     ) -> Labware:
@@ -558,6 +589,20 @@ class Labware:
 
         self._core_map.add(labware_core, labware)
 
+        if lid is not None:
+            if self._api_version < validation.LID_STACK_VERSION_GATE:
+                raise APIVersionError(
+                    api_element="Loading a Lid on a Labware",
+                    until_version="2.23",
+                    current_version=f"{self._api_version}",
+                )
+            self._protocol_core.load_lid(
+                load_name=lid,
+                location=labware_core,
+                namespace=namespace,
+                version=version,
+            )
+
         return labware
 
     @requires_version(2, 15)
@@ -582,6 +627,65 @@ class Labware:
             label=label,
         )
 
+    @requires_version(2, 23)
+    def load_lid_stack(
+        self,
+        load_name: str,
+        quantity: int,
+        namespace: Optional[str] = None,
+        version: Optional[int] = None,
+    ) -> Labware:
+        """
+        Load a stack of 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
+            `Labware Library <https://labware.opentrons.com>`_.
+        :param int quantity: The quantity of lids to be loaded in the stack.
+        :param str namespace: The namespace that the lid labware definition belongs to.
+            If unspecified, the API will automatically search two namespaces:
+
+              - ``"opentrons"``, to load standard Opentrons labware definitions.
+              - ``"custom_beta"``, to load custom labware definitions created with the
+                `Custom Labware Creator <https://labware.opentrons.com/create>`__.
+
+            You might need to specify an explicit ``namespace`` if you have a custom
+            definition whose ``load_name`` is the same as an Opentrons-verified
+            definition, and you want to explicitly choose one or the other.
+
+        :param version: The version of the labware definition. You should normally
+            leave this unspecified to let ``load_lid_stack()`` choose a version
+            automatically.
+
+        :return: The initialized and loaded labware object representing the Lid Stack.
+        """
+        if self._api_version < validation.LID_STACK_VERSION_GATE:
+            raise APIVersionError(
+                api_element="Loading a Lid Stack",
+                until_version="2.23",
+                current_version=f"{self._api_version}",
+            )
+
+        load_location = self._core
+
+        load_name = validation.ensure_lowercase_name(load_name)
+
+        result = self._protocol_core.load_lid_stack(
+            load_name=load_name,
+            location=load_location,
+            quantity=quantity,
+            namespace=namespace,
+            version=version,
+        )
+
+        labware = Labware(
+            core=result,
+            api_version=self._api_version,
+            protocol_core=self._protocol_core,
+            core_map=self._core_map,
+        )
+        return labware
+
     def set_calibration(self, delta: Point) -> None:
         """
         An internal, deprecated method used for updating the labware offset.
@@ -932,7 +1036,7 @@ class Labware:
         num_tips: int = 1,
         starting_tip: Optional[Well] = None,
         *,
-        nozzle_map: Optional[NozzleMap] = None,
+        nozzle_map: Optional[NozzleMapInterface] = None,
     ) -> Optional[Well]:
         """
         Find the next valid well for pick-up.
@@ -1105,6 +1209,141 @@ class Labware:
         """
         self._core.reset_tips()
 
+    @requires_version(2, 22)
+    def load_liquid(
+        self, wells: Sequence[Union[str, Well]], volume: float, liquid: Liquid
+    ) -> None:
+        """Mark several wells as containing the same amount of liquid.
+
+        This method should be called at the beginning of a protocol, soon after loading the labware and before
+        liquid handling operations begin. It is a base of information for liquid tracking functionality. If a well in a labware
+        has not been named in a call to :py:meth:`~Labware.load_empty`, :py:meth:`~Labware.load_liquid`, or
+        :py:meth:`~Labware.load_liquid_by_well`, the volume it contains is unknown and the well's liquid will not be tracked.
+
+        For example, to load 10µL of a liquid named ``water`` (defined with :py:meth:`~ProtocolContext.define_liquid`)
+        into all the wells of a labware, you could call ``labware.load_liquid(labware.wells(), 10, water)``.
+
+        If you want to load different volumes of liquid into different wells, use :py:meth:`~Labware.load_liquid_by_well`.
+
+        If you want to mark the well as containing no liquid, use :py:meth:`~Labware.load_empty`.
+
+        :param wells: The wells to load the liquid into.
+        :type wells: List of well names or list of Well objects, for instance from :py:meth:`~Labware.wells`.
+
+        :param volume: The volume of liquid to load into each well, in 10µL.
+        :type volume: float
+
+        :param liquid: The liquid to load into each well, previously defined by :py:meth:`~ProtocolContext.define_liquid`
+        :type liquid: Liquid
+        """
+        well_names: List[str] = []
+        for well in wells:
+            if isinstance(well, str):
+                if well not in self.wells_by_name():
+                    raise KeyError(
+                        f"{well} is not a well in labware {self.name}. The elements of wells should name wells in this labware."
+                    )
+                well_names.append(well)
+            elif isinstance(well, Well):
+                if well.parent is not self:
+                    raise KeyError(
+                        f"{well.well_name} is not a well in labware {self.name}. The elements of wells should be wells of this labware."
+                    )
+                well_names.append(well.well_name)
+            else:
+                raise TypeError(
+                    f"Unexpected type for element {repr(well)}. The elements of wells should be Well instances or well names."
+                )
+            if not isinstance(volume, (float, int)):
+                raise TypeError(
+                    f"Unexpected type for volume {repr(volume)}. Volume should be a number in microliters."
+                )
+        self._core.load_liquid({well_name: volume for well_name in well_names}, liquid)
+
+    @requires_version(2, 22)
+    def load_liquid_by_well(
+        self, volumes: Mapping[Union[str, Well], float], liquid: Liquid
+    ) -> None:
+        """Mark several wells as containing unique volumes of liquid.
+
+        This method should be called at the beginning of a protocol, soon after loading the labware and before
+        liquid handling operations begin. It is a base of information for liquid tracking functionality. If a well in a labware
+        has not been named in a call to :py:meth:`~Labware.load_empty`, :py:meth:`~Labware.load_liquid`, or
+        :py:meth:`~Labware.load_liquid_by_well`, the volume it contains is unknown and the well's liquid will not be tracked.
+
+        For example, to load a decreasing amount of of a liquid named ``water`` (defined with :py:meth:`~ProtocolContext.define_liquid`)
+        into each successive well of a row, you could call
+        ``labware.load_liquid_by_well({'A1': 1000, 'A2': 950, 'A3': 900, ..., 'A12': 600}, water)``
+
+        If you want to load the same volume of a liquid into multiple wells, it is often easier to use :py:meth:`~Labware.load_liquid`.
+
+        If you want to mark the well as containing no liquid, use :py:meth:`~Labware.load_empty`.
+
+        :param volumes: A dictionary of well names (or :py:class:`Well` objects, for instance from ``labware['A1']``)
+        :type wells: Dict[Union[str, Well], float]
+
+        :param liquid: The liquid to load into each well, previously defined by :py:meth:`~ProtocolContext.define_liquid`
+        :type liquid: Liquid
+        """
+        verified_volumes: Dict[str, float] = {}
+        for well, volume in volumes.items():
+            if isinstance(well, str):
+                if well not in self.wells_by_name():
+                    raise KeyError(
+                        f"{well} is not a well in {self.name}. The keys of volumes should name wells in this labware"
+                    )
+                verified_volumes[well] = volume
+            elif isinstance(well, Well):
+                if well.parent is not self:
+                    raise KeyError(
+                        f"{well.well_name} is not a well in {self.name}. The keys of volumes should be wells of this labware"
+                    )
+                verified_volumes[well.well_name] = volume
+            else:
+                raise TypeError(
+                    f"Unexpected type for well name {repr(well)}. The keys of volumes should be Well instances or well names."
+                )
+            if not isinstance(volume, (float, int)):
+                raise TypeError(
+                    f"Unexpected type for volume {repr(volume)}. The values of volumes should be numbers in microliters."
+                )
+        self._core.load_liquid(verified_volumes, liquid)
+
+    @requires_version(2, 22)
+    def load_empty(self, wells: Sequence[Union[Well, str]]) -> None:
+        """Mark several wells as empty.
+
+        This method should be called at the beginning of a protocol, soon after loading the labware and before liquid handling
+        operations begin. It is a base of information for liquid tracking functionality. If a well in a labware has not been named
+        in a call to :py:meth:`Labware.load_empty`, :py:meth:`Labware.load_liquid`, or :py:meth:`Labware.load_liquid_by_well`, the
+        volume it contains is unknown and the well's liquid will not be tracked.
+
+        For instance, to mark all wells in the labware as empty, you can call ``labware.load_empty(labware.wells())``.
+
+        :param wells: The list of wells to mark empty. To mark all wells as empty, pass ``labware.wells()``. You can also specify
+                      wells by their names (for instance, ``labware.load_empty(['A1', 'A2'])``).
+        :type wells: Union[List[Well], List[str]]
+        """
+        well_names: List[str] = []
+        for well in wells:
+            if isinstance(well, str):
+                if well not in self.wells_by_name():
+                    raise KeyError(
+                        f"{well} is not a well in {self.name}. The elements of wells should name wells in this labware."
+                    )
+                well_names.append(well)
+            elif isinstance(well, Well):
+                if well.parent is not self:
+                    raise KeyError(
+                        f"{well.well_name} is not a well in {self.name}. The elements of wells should be wells of this labware."
+                    )
+                well_names.append(well.well_name)
+            else:
+                raise TypeError(
+                    f"Unexpected type for well name {repr(well)}. The elements of wells should be Well instances or well names."
+                )
+        self._core.load_empty(well_names)
+
 
 # TODO(mc, 2022-11-09): implementation detail, move to core
 def split_tipracks(tip_racks: List[Labware]) -> Tuple[Labware, List[Labware]]:
@@ -1121,7 +1360,7 @@ def select_tiprack_from_list(
     num_channels: int,
     starting_point: Optional[Well] = None,
     *,
-    nozzle_map: Optional[NozzleMap] = None,
+    nozzle_map: Optional[NozzleMapInterface] = None,
 ) -> Tuple[Labware, Well]:
     try:
         first, rest = split_tipracks(tip_racks)
@@ -1159,7 +1398,7 @@ def next_available_tip(
     tip_racks: List[Labware],
     channels: int,
     *,
-    nozzle_map: Optional[NozzleMap] = None,
+    nozzle_map: Optional[NozzleMapInterface] = None,
 ) -> Tuple[Labware, Well]:
     start = starting_tip
     if start is None:

opentrons/protocol_api/module_contexts.py

@@ -125,6 +125,7 @@ class ModuleContext(CommandPublisher):
         namespace: Optional[str] = None,
         version: Optional[int] = None,
         adapter: Optional[str] = None,
+        lid: Optional[str] = None,
     ) -> Labware:
         """Load a labware onto the module using its load parameters.
 
@@ -180,6 +181,19 @@ class ModuleContext(CommandPublisher):
             version=version,
             location=load_location,
         )
+        if lid is not None:
+            if self._api_version < validation.LID_STACK_VERSION_GATE:
+                raise APIVersionError(
+                    api_element="Loading a lid on a Labware",
+                    until_version="2.23",
+                    current_version=f"{self._api_version}",
+                )
+            self._protocol_core.load_lid(
+                load_name=lid,
+                location=labware_core,
+                namespace=namespace,
+                version=version,
+            )
 
         if isinstance(self._core, LegacyModuleCore):
             labware = self._core.add_labware_core(cast(LegacyLabwareCore, labware_core))
@@ -608,7 +622,7 @@ class ThermocyclerContext(ModuleContext):
         .. note::
 
             The Thermocycler will proceed to the next command immediately after
-            ``temperature`` has been reached.
+            ``temperature`` is reached.
 
         """
         self._core.set_target_lid_temperature(celsius=temperature)
@@ -625,28 +639,18 @@ class ThermocyclerContext(ModuleContext):
         """Execute a Thermocycler profile, defined as a cycle of
         ``steps``, for a given number of ``repetitions``.
 
-        :param steps: List of unique steps that make up a single cycle.
-                      Each list item should be a dictionary that maps to
-                      the parameters of the :py:meth:`set_block_temperature`
-                      method with a ``temperature`` key, and either or both of
+        :param steps: List of steps that make up a single cycle.
+                      Each list item should be a dictionary that maps to the parameters
+                      of the :py:meth:`set_block_temperature` method. The dictionary's
+                      keys must be ``temperature`` and one or both of
                       ``hold_time_seconds`` and ``hold_time_minutes``.
         :param repetitions: The number of times to repeat the cycled steps.
         :param block_max_volume: The greatest volume of liquid contained in any
                                  individual well of the loaded labware, in µL.
                                  If not specified, the default is 25 µL.
 
-        .. note::
-
-            Unlike with :py:meth:`set_block_temperature`, either or both of
-            ``hold_time_minutes`` and ``hold_time_seconds`` must be defined
-            and for each step.
-
-        .. note::
-
-            Before API Version 2.21, Thermocycler profiles run with this command
-            would be listed in the app as having a number of repetitions equal to
-            their step count. At or above API Version 2.21, the structure of the
-            Thermocycler cycles is preserved.
+        .. versionchanged:: 2.21
+            Fixed run log listing number of steps instead of number of repetitions.
 
         """
         repetitions = validation.ensure_thermocycler_repetition_count(repetitions)

opentrons/protocol_api/protocol_context.py

@@ -186,7 +186,14 @@ class ProtocolContext(CommandPublisher):
         self._commands: List[str] = []
         self._params: Parameters = Parameters()
         self._unsubscribe_commands: Optional[Callable[[], None]] = None
-        self._robot = RobotContext(self._core)
+        try:
+            self._robot: Optional[RobotContext] = RobotContext(
+                core=self._core.load_robot(),
+                protocol_core=self._core,
+                api_version=self._api_version,
+            )
+        except APIVersionError:
+            self._robot = None
         self.clear_commands()
 
     @property
@@ -212,12 +219,14 @@ class ProtocolContext(CommandPublisher):
         return self._api_version
 
     @property
-    @requires_version(2, 21)
+    @requires_version(2, 22)
     def robot(self) -> RobotContext:
         """The :py:class:`.RobotContext` for the protocol.
 
         :meta private:
         """
+        if self._core.robot_type != "OT-3 Standard" or not self._robot:
+            raise RobotTypeError("The RobotContext is only available on Flex robots.")
         return self._robot
 
     @property
@@ -229,7 +238,9 @@ class ProtocolContext(CommandPublisher):
             "This function will be deprecated in later versions."
             "Please use with caution."
         )
-        return self._robot.hardware
+        if self._robot:
+            return self._robot.hardware
+        return HardwareManager(hardware=self._core.get_hardware())
 
     @property
     @requires_version(2, 0)
@@ -388,6 +399,7 @@ class ProtocolContext(CommandPublisher):
         namespace: Optional[str] = None,
         version: Optional[int] = None,
         adapter: Optional[str] = None,
+        lid: Optional[str] = None,
     ) -> Labware:
         """Load a labware onto a location.
 
@@ -432,6 +444,10 @@ class ProtocolContext(CommandPublisher):
             values as the ``load_name`` parameter of :py:meth:`.load_adapter`. The
             adapter will use the same namespace as the labware, and the API will
             choose the adapter's version automatically.
+        :param lid: A lid to load the on top of the main labware. Accepts the same
+            values as the ``load_name`` parameter of :py:meth:`.load_lid_stack`. The
+            lid will use the same namespace as the labware, and the API will
+            choose the lid's version automatically.
 
                         .. versionadded:: 2.15
         """
@@ -472,6 +488,20 @@ class ProtocolContext(CommandPublisher):
             version=version,
         )
 
+        if lid is not None:
+            if self._api_version < validation.LID_STACK_VERSION_GATE:
+                raise APIVersionError(
+                    api_element="Loading a Lid on a Labware",
+                    until_version="2.23",
+                    current_version=f"{self._api_version}",
+                )
+            self._core.load_lid(
+                load_name=lid,
+                location=labware_core,
+                namespace=namespace,
+                version=version,
+            )
+
         labware = Labware(
             core=labware_core,
             api_version=self._api_version,
@@ -956,7 +986,10 @@ class ProtocolContext(CommandPublisher):
             mount, checked_instrument_name
         )
 
-        is_96_channel = checked_instrument_name == PipetteNameType.P1000_96
+        is_96_channel = checked_instrument_name in [
+            PipetteNameType.P1000_96,
+            PipetteNameType.P200_96,
+        ]
 
         tip_racks = tip_racks or []
 
@@ -1320,6 +1353,94 @@ class ProtocolContext(CommandPublisher):
         """Returns ``True`` if the front door of the robot is closed."""
         return self._core.door_closed()
 
+    @requires_version(2, 23)
+    def load_lid_stack(
+        self,
+        load_name: str,
+        location: Union[DeckLocation, Labware],
+        quantity: int,
+        adapter: Optional[str] = None,
+        namespace: Optional[str] = None,
+        version: Optional[int] = None,
+    ) -> Labware:
+        """
+        Load a stack of 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
+            `Labware Library <https://labware.opentrons.com>`_.
+        :param location: Either a :ref:`deck slot <deck-slots>`,
+            like ``1``, ``"1"``, or ``"D1"``, or the a valid Opentrons Adapter.
+        :param int quantity: The quantity of lids to be loaded in the stack.
+        :param adapter: An adapter to load the lid stack on top of. Accepts the same
+            values as the ``load_name`` parameter of :py:meth:`.load_adapter`. The
+            adapter will use the same namespace as the lid labware, and the API will
+            choose the adapter's version automatically.
+        :param str namespace: The namespace that the lid labware definition belongs to.
+            If unspecified, the API will automatically search two namespaces:
+
+              - ``"opentrons"``, to load standard Opentrons labware definitions.
+              - ``"custom_beta"``, to load custom labware definitions created with the
+                `Custom Labware Creator <https://labware.opentrons.com/create>`__.
+
+            You might need to specify an explicit ``namespace`` if you have a custom
+            definition whose ``load_name`` is the same as an Opentrons-verified
+            definition, and you want to explicitly choose one or the other.
+
+        :param version: The version of the labware definition. You should normally
+            leave this unspecified to let ``load_lid_stack()`` choose a version
+            automatically.
+
+        :return:  The initialized and loaded labware object representing the Lid Stack.
+        """
+        if self._api_version < validation.LID_STACK_VERSION_GATE:
+            raise APIVersionError(
+                api_element="Loading a Lid Stack",
+                until_version="2.23",
+                current_version=f"{self._api_version}",
+            )
+
+        load_location: Union[DeckSlotName, StagingSlotName, LabwareCore]
+        if isinstance(location, Labware):
+            load_location = location._core
+        else:
+            load_location = validation.ensure_and_convert_deck_slot(
+                location, self._api_version, self._core.robot_type
+            )
+
+        if adapter is not None:
+            if isinstance(load_location, DeckSlotName) or isinstance(
+                load_location, StagingSlotName
+            ):
+                loaded_adapter = self.load_adapter(
+                    load_name=adapter,
+                    location=load_location.value,
+                    namespace=namespace,
+                )
+                load_location = loaded_adapter._core
+            else:
+                raise ValueError(
+                    "Location cannot be a Labware or Adapter when the 'adapter' field is not None."
+                )
+
+        load_name = validation.ensure_lowercase_name(load_name)
+
+        result = self._core.load_lid_stack(
+            load_name=load_name,
+            location=load_location,
+            quantity=quantity,
+            namespace=namespace,
+            version=version,
+        )
+
+        labware = Labware(
+            core=result,
+            api_version=self._api_version,
+            protocol_core=self._core,
+            core_map=self._core_map,
+        )
+        return labware
+
 
 def _create_module_context(
     module_core: Union[ModuleCore, NonConnectedModuleCore],