docs(api): lids updates in app 8.4 / PAPI 2.23

api/docs/v2/modules/thermocycler.rst

@@ -156,7 +156,7 @@ Use the following API load names for the auto-sealing lid and deck riser:
   * - Opentrons Flex Deck Riser
     - ``opentrons_flex_deck_riser``
 
-Load the riser directly onto the deck with :py:meth:`.ProtocolContext.load_adapter`. Load the auto-sealing lid onto a compatible location (the deck, the riser, or another lid) with the appropriate ``load_labware()`` method. You can create a stack of up to five auto-sealing lids. If you try to stack more than five lids, the API will raise an error.
+Load the riser directly onto the deck with :py:meth:`.ProtocolContext.load_adapter`. Load the auto-sealing lid onto a compatible location (the deck, the riser, or another lid) with the :py:meth:`.ProtocolContext.load_lid_stack` method. You can create a stack of up to five auto-sealing lids. If you try to stack more than five lids, the API will raise an error.
 
 Setting up the riser and preparing a lid to use on the Thermocycler generally consists of the following steps:
 
@@ -175,18 +175,24 @@ The following code sample shows how to perform these steps, using the riser and
         load_name="opentrons_flex_deck_riser", location="A2"
     )
 
-    # load three lids
-    lid_1 = riser.load_labware("opentrons_tough_pcr_auto_sealing_lid")
-    lid_2 = lid_1.load_labware("opentrons_tough_pcr_auto_sealing_lid")
-    lid_3 = lid_2.load_labware("opentrons_tough_pcr_auto_sealing_lid")
+    # load a stack of three lids
+    lid_stack = riser.load_lid_stack(
+        load_name="opentrons_tough_pcr_auto_sealing_lid",
+        location=riser,
+        quantity=3
+    )
 
     # load plate on Thermocycler
     plate = protocol.load_labware(
         load_name="opentrons_96_wellplate_200ul_pcr_full_skirt", location=tc_mod
     )
 
     # move lid to PCR plate
-    protocol.move_labware(labware=lid_3, new_location=plate, use_gripper=True)
+    protocol.move_lid(
+        source_location=lid_stack,
+        new_location=plate,
+        use_gripper=True
+    )
 
     # close Thermocycler
     tc_mod.close_lid()
@@ -197,11 +203,17 @@ The following code sample shows how to perform these steps, using the riser and
 When you're finished with a lid, use the gripper to dispose of it in either the waste chute or a trash bin::
 
     tc_mod.open_lid()
-    protocol.move_labware(labware=lid_3, new_location=trash, use_gripper=True)
+    protocol.move_lid(
+        source_location=plate,
+        new_location=trash, 
+        use_gripper=True)
 
 .. versionadded:: 2.16
     :py:class:`.TrashBin` and :py:class:`.WasteChute` objects can accept lids.
 
+.. versionadded:: 2.23
+    Use :py:meth:`.ProtocolContext.load_lid_stack` and :py:meth:`.ProtocolContext.move_lid` to stack and move auto-sealing lids in your protocol. 
+
 You can then move the PCR plate off of the Thermocycler. The Flex Gripper can't move a plate that has a lid on top of it. Always move the lid first, then the plate.
 
 Changes with the GEN2 Thermocycler Module

api/docs/v2/moving_labware.rst

@@ -93,7 +93,13 @@ You can manually move any standard or custom labware. Using the gripper to move
           * ``opentrons_flex_96_filtertiprack_50ul``
           * ``opentrons_flex_96_filtertiprack_200ul``
           * ``opentrons_flex_96_filtertiprack_1000ul``
+    * - Opentrons labware lids 
+      - 
+          * ``opentrons_tough_pcr_auto_sealing_lid``
+          * ``opentrons_flex_tiprack_lid``
 
+You can move compatible Opentrons lids manually or with the Flex Gripper, but some restrictions apply. For more information, see :ref:`moving-lids`.
+
 The gripper may work with other ANSI/SLAS standard labware, but this is not recommended.
 
 .. note::
@@ -106,7 +112,7 @@ The gripper may work with other ANSI/SLAS standard labware, but this is not reco
 Movement with Modules
 =====================
 
-Moving labware on and off of modules lets you precisely control when the labware is in contact with the hot, cold, or magnetic surfaces of the modules — all within a single protocol.
+Moving labware on and off of modules lets you precisely control when the labware is in contact with the hot, cold, or magnetic surfaces of the modules.
 
 When moving labware anywhere that isn't an empty deck slot, consider what physical object the labware will rest on following the move. That object should be the value of ``new_location``, and you need to make sure it's already loaded before the move. For example, if you want to move a 96-well flat plate onto a Heater-Shaker module, you actually want to have it rest on top of the Heater-Shaker's 96 Flat Bottom Adapter. Pass the adapter, not the module or the slot, as the value of ``new_location``::
 
@@ -146,6 +152,48 @@ This will pick up ``plate`` from its current location and drop it into the chute
 
 Always specify ``use_gripper=True`` when moving labware into the waste chute. The chute is not designed for manual movement. You can still manually move labware to other locations, including off-deck, with the chute installed.
 
+.. _moving-lids:
+
+Moving Lids
+===========
+
+You can use :py:meth:`.ProtocolContext.move_lid` to move labware lids around the deck manually or using the Flex Gripper. Currently supported lids include the Opentrons Tough PCR Auto-Sealing Lid (for use with the Thermocycler) and the Opentrons Flex Tip Rack Lid.
+
+You can move the auto-sealing lids between deck slots, lid stacks, or compatible labware loaded in your protocol. This example loads a stack of lids and then moves one to a PCR plate on the Thermocycler.
+
+.. code-block:: python
+
+    # load Thermocycler and plate
+    tc_mod = protocol.load_module(module_name="thermocyclerModuleV2")
+    plate = tc_mod.load_labware(name="opentrons_96_wellplate_200ul_pcr_full_skirt")
+
+    # load lid stack
+    lid_stack = protocol.load_lid_stack(
+        load_name="opentrons_tough_pcr_auto_sealing_lid",
+        location="B2",
+        quantity=4
+    )
+
+    # move one lid to a compatible well plate in the Thermocycler
+    tc_mod.open_lid()
+    protocol.move_lid(
+        source_location=lid_stack,
+        new_location=plate,
+        use_gripper=True
+    )
+
+When you're done with a lid, use ``move_lid()`` to dispose of it in the waste chute or a trash bin::
+
+    protocol.move_lid(
+        source_location=plate,
+        new_location=trash,
+        use_gripper=True
+    )
+
+To work with tip rack lids, first :ref:`load the tip rack lid <loading-lids>` using the ``lid`` parameter of :py:meth:`~.ProtocolContext.load_labware`. Once loaded, you can only move a tip rack lid to another, unlidded tip rack or to a trash container. If you try setting another ``new_location``, the API will raise an error.
+
+.. versionadded:: 2.23
+
 .. _off-deck-location:
 
 The Off-Deck Location

api/docs/v2/new_labware.rst

@@ -48,7 +48,7 @@ Throughout this section, we'll use the labware listed in the following table.
       - Labware name
       - API load name
     * - Well plate
-      - `Corning 96 Well Plate 360 µL Flat <https://labware.opentrons.com/corning_96_wellplate_360ul_flat/>`_
+      - `Opentrons Tough 96 Well Plate 200 µL PCR Full Skirt <https://labware.opentrons.com/opentrons_96_wellplate_200ul_pcr_full_skirt/>`_
       - ``corning_96_wellplate_360ul_flat``
     * - Flex tip rack
       - `Opentrons Flex 96 Tips 200 µL <https://shop.opentrons.com/opentrons-flex-tips-200-l/>`_
@@ -63,13 +63,13 @@ Similar to the code sample in :ref:`overview-section-v2`, here's how you use the
 
     #Flex
     tiprack = protocol.load_labware("opentrons_flex_96_tiprack_200ul", "D1")
-    plate = protocol.load_labware("corning_96_wellplate_360ul_flat", "D2")
+    plate = protocol.load_labware("opentrons_96_wellplate_200ul_pcr_full_skirt", "D2")
 
 .. code-block:: python
 
     #OT-2
     tiprack = protocol.load_labware("opentrons_96_tiprack_300ul", "1")
-    plate = protocol.load_labware("corning_96_wellplate_360ul_flat", "2")
+    plate = protocol.load_labware("opentrons_96_wellplate_200ul_pcr_full_skirt", "2")
 
 .. versionadded:: 2.0
 
@@ -82,10 +82,46 @@ When the ``load_labware`` method loads labware into your protocol, it returns a
     The ``load_labware`` method includes an optional ``label`` argument. You can use it to identify labware with a descriptive name. If used, the label value is displayed in the Opentrons App. For example::
 
         tiprack = protocol.load_labware(
-            load_name="corning_96_wellplate_360ul_flat",
+            load_name="opentrons_flex_96_tiprack_200ul",
             location="D1",
             label="any-name-you-want")
 
+
+.. _loading-lids:
+
+Loading Lids
+============
+
+You can load lids on compatible plates or tip racks with the optional ``lid`` parameter of :py:meth:`~.ProtocolContext.load_labware`. This example adds an Opentrons Tough Auto-Sealing Lid to a PCR plate::
+
+    plate = protocol.load_labware(
+        load_name="opentrons_96_wellplate_200ul_pcr_full_skirt",
+        location="D2",
+        lid="opentrons_tough_pcr_auto_sealing_lid"
+    )
+
+And this example loads an Opentrons Flex Tip Rack Lid onto a rack of 200 µL tips::
+
+    tiprack = protocol.load_labware(
+        load_name="opentrons_flex_96_tiprack_200ul",
+        location="D1",
+        lid="opentrons_flex_tiprack_lid"
+    )
+
+You might need multiple lids during your protocol. Use :py:meth:`.load_lid_stack` to stack up to five Opentrons Tough Auto-Sealing Lids on a deck slot, riser, or compatible adapter.
+
+.. code-block:: python
+
+    lid_stack = protocol.load_lid_stack(
+        load_name="opentrons_tough_pcr_auto_sealing_lid",
+        location="B2",
+        quantity=4
+    )
+
+Tip rack lids can't be stacked or placed on the deck.
+
+.. versionadded:: 2.23
+
 .. _labware-on-adapters:
 
 Loading Labware on Adapters

api/src/opentrons/protocol_api/protocol_context.py

@@ -451,14 +451,14 @@ def load_labware(
             choose the adapter's version automatically.
 
                         .. versionadded:: 2.15
+        :param lid: A lid to load on the 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 adapter's version automatically.
+
+                        .. versionadded:: 2.23
         """
-        # TODO: re-include in docstring when 2.23 is ready
-        #         :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.23
+
         if isinstance(location, OffDeckType) and self._api_version < APIVersion(2, 15):
             raise APIVersionError(
                 api_element="Loading a labware off-deck",
@@ -1391,13 +1391,13 @@ def load_lid_stack(
         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
+            You can find the ``load_name`` for any compatible 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.
+            like ``1``, ``"1"``, or ``"D1"``, or 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
@@ -1418,9 +1418,10 @@ def load_lid_stack(
             leave this unspecified to let ``load_lid_stack()`` choose a version
             automatically.
 
-        :return:  The initialized and loaded labware object representing the Lid Stack.
+        :return:  The initialized and loaded labware object representing the lid stack.
+
+        .. versionadded:: 2.23
 
-        :meta private:
         """
         if self._api_version < validation.LID_STACK_VERSION_GATE:
             raise APIVersionError(
@@ -1479,9 +1480,9 @@ def move_lid(
         pick_up_offset: Optional[Mapping[str, float]] = None,
         drop_offset: Optional[Mapping[str, float]] = None,
     ) -> Labware | None:
-        """Move a lid from a valid source to a new location. Can return a Lid Stack if one is created.
+        """Move a compatible lid from a valid source to a new location. Can return a lid stack if one is created.
 
-        :param source_location: Where to take the lid from. This is either:
+        :param source_location: The lid's starting location. This is either:
 
                 * A deck slot like ``1``, ``"1"``, or ``"D1"``. See :ref:`deck-slots`.
                 * A labware or adapter that's already been loaded on the deck
@@ -1498,7 +1499,7 @@ def move_lid(
                   with :py:meth:`load_labware` or :py:meth:`load_adapter`.
                 * The special constant :py:obj:`OFF_DECK`.
 
-        :param use_gripper: Whether to use the Flex Gripper for this movement.
+        :param use_gripper: Whether to use the Flex Gripper to move the lid.
 
                 * If ``True``, use the gripper to perform an automatic
                   movement. This will raise an error in an OT-2 protocol.
@@ -1515,7 +1516,8 @@ def move_lid(
         labware's current and new locations are accessible, i.e., open the Thermocycler lid
         or open the Heater-Shaker's labware latch.
 
-        :meta private:
+        .. versionadded:: 2.23
+
         """
         source: Union[LabwareCore, DeckSlotName, StagingSlotName]
         if isinstance(source_location, Labware):