docs(api): Python Protocol API 2.17 (#14493)

Documenting changes in version 2.17 of the Python Protocol API --------- Co-authored-by: Joe Wojak <[email protected]>
Opentrons · Mar 6, 2024 · d6f22ac · d6f22ac
1 parent d2696ce
commit d6f22ac
Show file tree

Hide file tree

Showing 3 changed files with 30 additions and 11 deletions.
diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst
@@ -75,6 +75,13 @@ To dispense liquid from a pipette tip, call the :py:meth:`.InstrumentContext.dis
 
     pipette.dispense(200, plate["B1"])
 
+.. note::
+    In API version 2.16 and earlier, you could pass a ``volume`` argument to ``dispense()`` greater than what was aspirated into the pipette. In this case, the API would ignore ``volume`` and dispense the pipette's :py:obj:`~.InstrumentContext.current_volume`. The robot *would not* move the plunger lower as a result.
+
+    In version 2.17 and later, passing such values raises an error.
+
+    To move the plunger a small extra amount, add a :ref:`push out <push-out-dispense>`. Or to move it a large amount, use :ref:`blow out <blow-out>`.
+
 If the pipette doesn’t move, you can specify an additional dispense action without including a location. To demonstrate, this code snippet pauses the protocol, automatically resumes it, and dispense a second time from location B1.
 
 .. code-block:: python
@@ -129,9 +136,6 @@ For example, this dispense action moves the plunger the equivalent of an additio
 
 .. versionadded:: 2.15
 
-.. note::
-    In version 7.0.2 and earlier of the robot software, you could accomplish a similar result by dispensing a volume greater than what was aspirated into the pipette. In version 7.1.0 and later, the API will return an error. Calculate the difference between the two amounts and use that as the value of ``push_out``.
-
 .. _new-blow-out:
 
 .. _blow-out:

diff --git a/api/docs/v2/versioning.rst b/api/docs/v2/versioning.rst
@@ -84,6 +84,8 @@ This table lists the correspondence between Protocol API versions and robot soft
 +-------------+------------------------------+
 | API Version | Introduced in Robot Software |
 +=============+==============================+
+|     2.17    |          7.2.0               |
++-------------+------------------------------+
 |     2.16    |          7.1.0               |
 +-------------+------------------------------+
 |     2.15    |          7.0.0               |
@@ -126,6 +128,11 @@ This table lists the correspondence between Protocol API versions and robot soft
 Changes in API Versions
 =======================
 
+Version 2.17
+------------
+
+- :py:meth:`.dispense` now raises an error if you try to dispense more than :py:obj:`.InstrumentContext.current_volume`.
+
 Version 2.16
 ------------
 

diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py
@@ -289,15 +289,20 @@ def dispense(  # noqa: C901
 
         See :ref:`new-dispense` for more details and examples.
 
-        :param volume: The volume to dispense, measured in µL. If unspecified,
-                       defaults to :py:attr:`current_volume`. If only a volume is
-                       passed, the pipette will dispense from its current position.
+        :param volume: The volume to dispense, measured in µL.
+
+                         - If unspecified or ``None``, dispense the :py:attr:`current_volume`.
+
+                         - If 0, the behavior of ``dispense()`` depends on the API level
+                           of the protocol. In API version 2.16 and earlier, dispense all
+                           liquid in the pipette (same as unspecified or ``None``). In API
+                           version 2.17 and later, dispense no liquid.
+
+                         - If greater than :py:obj:`.current_volume`, the behavior of
+                           ``dispense()`` depends on the API level of the protocol. In API
+                           version 2.16 and earlier, dispense all liquid in the pipette.
+                           In API version 2.17 and later, raise an error.
 
-                       If ``dispense`` is called with a volume of precisely 0, its behavior
-                       depends on the API level of the protocol. On API levels below 2.16,
-                       it will behave the same as a volume of ``None``/unspecified: dispense
-                       all liquid in the pipette. On API levels at or above 2.16, no liquid
-                       will be dispensed.
         :type volume: int or float
 
         :param location: Tells the robot where to dispense liquid held in the pipette.
@@ -344,6 +349,9 @@ def dispense(  # noqa: C901
 
         .. versionchanged:: 2.15
             Added the ``push_out`` parameter.
+
+        .. versionchanged:: 2.17
+            Behavior of the ``volume`` parameter.
         """
         if self.api_version < APIVersion(2, 15) and push_out:
             raise APIVersionError(