opentrons 8.5.0a9__py2.py3-none-any.whl → 8.5.0a10__py2.py3-none-any.whl

opentrons/protocol_api/core/engine/instrument.py

@@ -30,6 +30,9 @@ from opentrons.protocols.advanced_control.transfers.common import (
     NoLiquidClassPropertyError,
 )
 from opentrons.protocols.advanced_control.transfers import common as tx_commons
+from opentrons.protocols.advanced_control.transfers.transfer_liquid_utils import (
+    check_current_volume_before_dispensing,
+)
 from opentrons.protocol_engine import commands as cmd
 from opentrons.protocol_engine import (
     DeckPoint,
@@ -2143,9 +2146,12 @@ class InstrumentCore(AbstractInstrument[WellCore, LabwareCore]):
         """Remove an air gap that was previously added during a transfer."""
         if last_air_gap == 0:
             return
-
+        current_vol = self.get_current_volume()
+        check_current_volume_before_dispensing(
+            current_volume=current_vol, dispense_volume=last_air_gap
+        )
         correction_volume = dispense_props.correction_by_volume.get_for_volume(
-            self.get_current_volume() - last_air_gap
+            current_vol - last_air_gap
         )
         # The minimum flow rate should be air_gap_volume per second
         flow_rate = max(

opentrons/protocol_api/core/engine/transfer_components_executor.py

@@ -25,6 +25,7 @@ from opentrons.protocol_engine.errors import TouchTipDisabledError
 from opentrons.types import Location, Point, Mount
 from opentrons.protocols.advanced_control.transfers.transfer_liquid_utils import (
     LocationCheckDescriptors,
+    check_current_volume_before_dispensing,
 )
 from opentrons.protocols.advanced_control.transfers import (
     transfer_liquid_utils as tx_utils,
@@ -253,8 +254,12 @@ class TransferComponentsExecutor:
         push_out_override: Optional[float],
     ) -> None:
         """Dispense according to dispense properties and wait if enabled."""
+        current_vol = self._instrument.get_current_volume()
+        check_current_volume_before_dispensing(
+            current_volume=current_vol, dispense_volume=volume
+        )
         correction_volume = dispense_properties.correction_by_volume.get_for_volume(
-            self._instrument.get_current_volume() - volume
+            current_vol - volume
         )
         self._instrument.dispense(
             location=self._target_location,

opentrons/protocol_api/instrument_context.py

@@ -840,10 +840,9 @@ class InstrumentContext(publisher.CommandPublisher):
         :type speed: float
         :param mm_from_edge: How far to move inside the well, as a distance from the
                              well's edge.
-                             When ``mm_from_edge=0``, the pipette tip will move all the
-                             way to the edge of the target well. When ``mm_from_edge=1``,
-                             the pipette tip will move to 1 mm from the well's edge.
-                             Lower values will press the tip harder into the well's
+                             When ``mm_from_edge=0``, the pipette will move to the target well's edge to touch the tip. When ``mm_from_edge=1``,
+                             the pipette will move to 1 mm from the target well's edge to touch the tip.
+                             Values lower than 0 will press the tip harder into the target well's
                              walls; higher values will touch the well more lightly, or
                              not at all.
                              ``mm_from_edge`` and ``radius`` are mutually exclusive: to
@@ -1829,6 +1828,7 @@ class InstrumentContext(publisher.CommandPublisher):
 
         :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.
+            If not specified, the pipette will dispose of tips in its :py:obj:`~.InstrumentContext.trash_container`.
         :param return_tip: Whether to drop used tips in their original locations
             in the tip rack, instead of the trash.
         :param group_wells: For multi-channel transfers only. If set to ``True``, group together contiguous wells
@@ -1838,7 +1838,6 @@ class InstrumentContext(publisher.CommandPublisher):
             ``False``, the last tip will be dropped or returned. If not set, behavior depends on the value of
             ``new_tip``. ``new_tip="never"`` keeps the tip, and all other values of ``new_tip`` drop or return the tip.
 
-        :meta private:
         """
         if volume == 0.0:
             _log.info(
@@ -1962,13 +1961,14 @@ class InstrumentContext(publisher.CommandPublisher):
             Defaults to ``"once"``.
 
               - ``"once"``: Use one tip for the entire command.
+              - ``"always"``: Use a new tip before each aspirate.
               - ``"never"``: Do not pick up or drop tips at all.
-              - ``"always"``: Pick up a new tip before every aspirate.
 
             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.
+            If not specified, the pipette will dispose of tips in its :py:obj:`~.InstrumentContext.trash_container`.
         :param return_tip: Whether to drop used tips in their original locations
             in the tip rack, instead of the trash.
         :param group_wells: For multi-channel transfers only. If set to ``True``, group together contiguous wells
@@ -1978,7 +1978,6 @@ class InstrumentContext(publisher.CommandPublisher):
             ``False``, the last tip will be dropped or returned. If not set, behavior depends on the value of
             ``new_tip``. ``new_tip="never"`` keeps the tip, and all other values of ``new_tip`` drop or return the tip.
 
-        :meta private:
         """
         if volume == 0.0:
             _log.info(
@@ -2111,13 +2110,14 @@ class InstrumentContext(publisher.CommandPublisher):
             Defaults to ``"once"``.
 
               - ``"once"``: Use one tip for the entire command.
+              - ``"always"``: Use a new tip after each aspirate and dispense, even when visiting the same source again.
               - ``"never"``: Do not pick up or drop tips at all.
-              - ``"always"``: Pick up a new tip before going back to source for refilling after a dispense.
 
             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.
+            If not specified, the pipette will dispose of tips in its :py:obj:`~.InstrumentContext.trash_container`.
         :param return_tip: Whether to drop used tips in their original locations
             in the tip rack, instead of the trash.
         :param group_wells: For multi-channel transfers only. If set to ``True``, group together contiguous wells
@@ -2127,7 +2127,6 @@ class InstrumentContext(publisher.CommandPublisher):
             ``False``, the last tip will be dropped or returned. If not set, behavior depends on the value of
             ``new_tip``. ``new_tip="never"`` keeps the tip, and all other values of ``new_tip`` drop or return the tip.
 
-        :meta private:
         """
         if volume == 0.0:
             _log.info(

opentrons/protocol_api/protocol_context.py

@@ -1377,10 +1377,13 @@ class ProtocolContext(CommandPublisher):
         name: str,
     ) -> LiquidClass:
         """
-        Get an instance of a built-in liquid class for use in the protocol.
+        Get an instance of an Opentrons-verified liquid class for use in a Flex protocol.
 
-        Args:
-            name: Name of an Opentrons-defined liquid class.
+        :param name: Name of an Opentrons-verified liquid class. Must be one of:
+
+            - ``"water"``: an Opentrons-verified liquid class based on deionized water.
+            - ``"glycerol_50"``: an Opentrons-verified liquid class for viscous liquid. Based on 50% glycerol.
+            - ``"ethanol_80"``: an Opentrons-verified liquid class for volatile liquid. Based on 80% ethanol.
 
         :raises: ``LiquidClassDefinitionDoesNotExist``: if the specified liquid class does not exist.
         """
@@ -1394,28 +1397,14 @@ class ProtocolContext(CommandPublisher):
         base_liquid_class: Optional[LiquidClass] = None,
         display_name: Optional[str] = None,
     ) -> LiquidClass:
-        """Define a custom liquid class, either a completely new one or based on an existing one.
-
-        Args:
-            name: The name to give to the new liquid class. Cannot use names of existing in-built liquid classes.
-            properties: A dict of transfer properties per tip per pipette.
-                Accepts a nested dictionary in the following format:
-
-                .. code-block:: python
+        """Define a custom liquid class, either based on an existing, Opentrons-verified liquid class, or to create a completely new one.
 
-                    {
-                    <pipette_name>: {
-                        <tiprack_uri>: <properties in the shape of TransferPropertiesDict>
+        :param name: The name to give to the new liquid class. Cannot use the name of an Opentrons-verified liquid class.
+        :param properties: A dict of transfer properties for the Flex pipette and tips to use for liquid class transfers. The nested dictionary must have top-level keys corresponding to pipette load names and second-level keys corresponding to compatible tip rack load names. Further nested key–value pairs should be in the format returned by :py:meth:`.LiquidClass.get_for`. See also the `liquid class JSON schema <https://github.com/Opentrons/opentrons/tree/edge/shared-data/liquid-class/schemas>`_.
 
-                        # TransferPropertiesDict is a dictionary representation of the
-                        # transfer properties returned by the `LiquidClass.get_for(..)` function.
-                    }}
+        :param base_liquid_class: An Opentrons-verified liquid class to base the newly defined liquid class on. The specified ``transfer_properties`` will override any existing properties for the Flex pipette and tips. All other properties will remain the same as those in the base class.
 
-            base_liquid_class: A LiquidClass to base this liquid class on. The properties
-                specified in transfer_properties will override any existing ones
-                for the specified pipettes & tips.
-            display_name: An optional human-readable name for the liquid. If not provided,
-                will default to title-cased name.
+        :param display_name: An optional name for the liquid class. Defaults to the title-case ``name`` if a display name isn't provided.
 
         """
         if definition_exists(name, DEFAULT_LC_VERSION):

opentrons/protocols/advanced_control/transfers/transfer_liquid_utils.py

@@ -212,3 +212,20 @@ def _group_wells_for_nozzle_configuration(  # noqa: C901
         grouped_wells.reverse()
 
     return grouped_wells
+
+
+def check_current_volume_before_dispensing(
+    current_volume: float,
+    dispense_volume: float,
+) -> None:
+    """Check if the current volume is valid for dispensing the dispense volume."""
+    if current_volume < dispense_volume:
+        # Although this should never happen, we can get into an unexpected state
+        # following error recovery and not have the expected amount of liquid in the tip.
+        # If this happens, we want to raise a useful error so the user can understand
+        # the cause of the problem. If we don't make this check for current volume,
+        # an unhelpful error might get raised when a '..byVolume' property encounters
+        # a negative volume (current_volume - dispense_volume).
+        raise RuntimeError(
+            f"Cannot dispense {dispense_volume}uL when the tip has only {current_volume}uL."
+        )

{opentrons-8.5.0a9.dist-info → opentrons-8.5.0a10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: opentrons
-Version: 8.5.0a9
+Version: 8.5.0a10
 Summary: The Opentrons API is a simple framework designed to make writing automated biology lab protocols easy.
 Author: Opentrons
 Author-email: engineering@opentrons.com
@@ -21,7 +21,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.10
 License-File: ../LICENSE
-Requires-Dist: opentrons-shared-data (==8.5.0a9)
+Requires-Dist: opentrons-shared-data (==8.5.0a10)
 Requires-Dist: aionotify (==0.3.1)
 Requires-Dist: anyio (<4.0.0,>=3.6.1)
 Requires-Dist: jsonschema (<4.18.0,>=3.0.1)
@@ -35,9 +35,9 @@ Requires-Dist: pyusb (==1.2.1)
 Requires-Dist: packaging (>=21.0)
 Requires-Dist: importlib-metadata (>=1.0) ; python_version < "3.8"
 Provides-Extra: flex-hardware
-Requires-Dist: opentrons-hardware[flex] (==8.5.0a9) ; extra == 'flex-hardware'
+Requires-Dist: opentrons-hardware[flex] (==8.5.0a10) ; extra == 'flex-hardware'
 Provides-Extra: ot2-hardware
-Requires-Dist: opentrons-hardware (==8.5.0a9) ; extra == 'ot2-hardware'
+Requires-Dist: opentrons-hardware (==8.5.0a10) ; extra == 'ot2-hardware'
 
 .. _Full API Documentation: http://docs.opentrons.com
 

{opentrons-8.5.0a9.dist-info → opentrons-8.5.0a10.dist-info}/RECORD

@@ -229,11 +229,11 @@ opentrons/protocol_api/config.py,sha256=r9lyvXjagTX_g3q5FGURPpcz2IA9sSF7Oa_1mKx-
 opentrons/protocol_api/create_protocol_context.py,sha256=wwsZje0L__oDnu1Yrihau320_f-ASloR9eL1QCtkOh8,7612
 opentrons/protocol_api/deck.py,sha256=94vFceg1SC1bAGd7TvC1ZpYwnJR-VlzurEZ6jkacYeg,8910
 opentrons/protocol_api/disposal_locations.py,sha256=NRiSGmDR0LnbyEkWSOM-o64uR2fUoB1NWJG7Y7SsJSs,7920
-opentrons/protocol_api/instrument_context.py,sha256=B0-bI1UYtmk0tzikmtBamW-VBkx4iiktFrOgNtN5mOY,138964
+opentrons/protocol_api/instrument_context.py,sha256=mtflJtJfzHbnU3dFkQp8a2D4dqE1VRzy8JkqbDVpAJc,139254
 opentrons/protocol_api/labware.py,sha256=AhL1JX10Xt-mpB85CAnEOBvz9r5v3xncJuLMkiY1FPM,60934
 opentrons/protocol_api/module_contexts.py,sha256=Mzut2a92Gcv23wFPdNVU9fj2P--7WDqBx27xAJ7z8eo,48361
 opentrons/protocol_api/module_validation_and_errors.py,sha256=XL_m72P8rcvGO2fynY7UzXLcpGuI6X4s0V6Xf735Iyc,1464
-opentrons/protocol_api/protocol_context.py,sha256=9vIQmpCBJcfFH4TgAGzxMwqhw09JrN9nA0yZ1b90H8w,69672
+opentrons/protocol_api/protocol_context.py,sha256=PkedIdTuE8EBd4I7E6q1HjfXQWwmO_j3Q8dmNwLVJ90,70060
 opentrons/protocol_api/robot_context.py,sha256=D6ZdpFX30VTtVUDHitsVjabJQXD5TxOV9_Z6sik1LvE,11891
 opentrons/protocol_api/validation.py,sha256=73QwpdK5337yu9g8jvpHHizOD0Mf3m6Wr9S8eikrHIc,28993
 opentrons/protocol_api/core/__init__.py,sha256=-g74o8OtBB0LmmOvwkRvPgrHt7fF7T8FRHDj-x_-Onk,736
@@ -249,7 +249,7 @@ opentrons/protocol_api/core/well_grid.py,sha256=BU28DKaBgEU_JdZ6pEzrwNxmuh6TkO4z
 opentrons/protocol_api/core/engine/__init__.py,sha256=B_5T7zgkWDb1mXPg4NbT-wBkQaK-WVokMMnJRNu7xiM,582
 opentrons/protocol_api/core/engine/deck_conflict.py,sha256=q3JViIAHDthIqq6ce7h2gxw3CHRfYsm5kkwzuXB-Gnc,12334
 opentrons/protocol_api/core/engine/exceptions.py,sha256=aZgNrmYEeuPZm21nX_KZYtvyjv5h_zPjxxgPkEV7_bw,725
-opentrons/protocol_api/core/engine/instrument.py,sha256=3qh-qmK69ot3B73oWmepBx53jXOcpwFPPModhGoqu2U,103611
+opentrons/protocol_api/core/engine/instrument.py,sha256=HCc9SMglY9gumz1sAg7PU9cb7pR36Qkn0Cf6G1779_o,103900
 opentrons/protocol_api/core/engine/labware.py,sha256=1xvzguNnK7aecFLiJK0gtRrZ5kpwtzLS73HnKvdJ5lc,8413
 opentrons/protocol_api/core/engine/load_labware_params.py,sha256=I4Cb8rqpBhmykQuZE8QRG802APrdCy_TYS88rm_9oGA,7159
 opentrons/protocol_api/core/engine/module_core.py,sha256=MLPgYSRJHUZPZ9rTLvsg3GlpL5b6-Pjk5UBgXCGrL6U,30994
@@ -259,7 +259,7 @@ opentrons/protocol_api/core/engine/point_calculations.py,sha256=C2eF0fvJQGMqQv3D
 opentrons/protocol_api/core/engine/protocol.py,sha256=OvE8kDONIR0z5S-FV10KUw5v5_HskPk7aqFNyTSUasc,46919
 opentrons/protocol_api/core/engine/robot.py,sha256=bzUt23NG-clD-9-QFsV_6nm3fMgSmvYEG9DyyZI1xgw,5366
 opentrons/protocol_api/core/engine/stringify.py,sha256=GwFgEhFMk-uPfFQhQG_2mkaf4cxaItiY8RW7rZwiooQ,2794
-opentrons/protocol_api/core/engine/transfer_components_executor.py,sha256=zLokgodl5hu471_3uGKhm3TKOuOsvyeDKSiSkmmotf0,43462
+opentrons/protocol_api/core/engine/transfer_components_executor.py,sha256=2RAcqU-a2uB6YQw7MGKIjeFhNkVFTD3AQySPGgrmpxc,43661
 opentrons/protocol_api/core/engine/well.py,sha256=IaaFK-3hoUfabfn_twIT7zcAynhzAmRxDnvABss2szo,8923
 opentrons/protocol_api/core/legacy/__init__.py,sha256=_9jCJNKG3SlS_vljVu8HHkZmtLf4F-f-JHALLF5d5go,401
 opentrons/protocol_api/core/legacy/deck.py,sha256=qHqcGo-Kdkl9L1aOE0pwrm9tsAnwkXbt4rIOr_VEP-s,13955
@@ -526,7 +526,7 @@ opentrons/protocols/advanced_control/mix.py,sha256=GobQ9E6F2gARjfhNp2xdyWQXFBSwO
 opentrons/protocols/advanced_control/transfers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 opentrons/protocols/advanced_control/transfers/common.py,sha256=Mal5AKO35nCXqjwxR6tDityEoLYg09Yty3Jv1fgOHnQ,5498
 opentrons/protocols/advanced_control/transfers/transfer.py,sha256=-vE1uZq2BqAagSGeiuTxTyL1wT6fza_fwkO_V_OMMFc,37318
-opentrons/protocols/advanced_control/transfers/transfer_liquid_utils.py,sha256=uHUQJLYzDqA4pzZyIbR00PKRN5FMc6A6JgPBA9wSKTg,9713
+opentrons/protocols/advanced_control/transfers/transfer_liquid_utils.py,sha256=wCyAi0nbAWR0qFetRb2w7PYzyaIbpeFkZn9tbcumJgE,10571
 opentrons/protocols/api_support/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 opentrons/protocols/api_support/constants.py,sha256=pI_zJ8oORr6FUOaF508ttll3KOIYqRRgcwVFwnqZuqc,262
 opentrons/protocols/api_support/deck_type.py,sha256=cBxm-IQqFyL1QtYTMGtLXOlyuh-67xWgnJSP6rkg8oc,3942
@@ -584,9 +584,9 @@ opentrons/util/linal.py,sha256=IlKAP9HkNBBgULeSf4YVwSKHdx9jnCjSr7nvDvlRALg,5753
 opentrons/util/logging_config.py,sha256=7et4YYuQdWdq_e50U-8vFS_QyNBRgdnqPGAQJm8qrIo,9954
 opentrons/util/logging_queue_handler.py,sha256=ZsSJwy-oV8DXwpYiZisQ1PbYwmK2cOslD46AcyJ1E4I,2484
 opentrons/util/performance_helpers.py,sha256=ew7H8XD20iS6-2TJAzbQeyzStZkkE6PzHt_Adx3wbZQ,5172
-opentrons-8.5.0a9.dist-info/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-opentrons-8.5.0a9.dist-info/METADATA,sha256=nJjbwXecLEzOwdHxrr1YkHreHdpA1rane4x2MmTnJUI,5084
-opentrons-8.5.0a9.dist-info/WHEEL,sha256=qUzzGenXXuJTzyjFah76kDVqDvnk-YDzY00svnrl84w,109
-opentrons-8.5.0a9.dist-info/entry_points.txt,sha256=fTa6eGCYkvOtv0ov-KVE8LLGetgb35LQLF9x85OWPVw,106
-opentrons-8.5.0a9.dist-info/top_level.txt,sha256=wk6whpbMZdBQpcK0Fg0YVfUGrAgVOFON7oQAhOMGMW8,10
-opentrons-8.5.0a9.dist-info/RECORD,,
+opentrons-8.5.0a10.dist-info/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+opentrons-8.5.0a10.dist-info/METADATA,sha256=ashrw6ywHgLbcFpe0gEN3i2AquuqwgzaxM6bvgxdDIw,5088
+opentrons-8.5.0a10.dist-info/WHEEL,sha256=qUzzGenXXuJTzyjFah76kDVqDvnk-YDzY00svnrl84w,109
+opentrons-8.5.0a10.dist-info/entry_points.txt,sha256=fTa6eGCYkvOtv0ov-KVE8LLGetgb35LQLF9x85OWPVw,106
+opentrons-8.5.0a10.dist-info/top_level.txt,sha256=wk6whpbMZdBQpcK0Fg0YVfUGrAgVOFON7oQAhOMGMW8,10
+opentrons-8.5.0a10.dist-info/RECORD,,