docs(api): describe new distribute() volume clamping behavior (#14315)

* move and rewrite note * update versioning entry * "API version" instead of "version…of the API" Co-authored-by: Joe Wojak <[email protected]> * revise note text * clean up dispense() docstring * get location out of volume --------- Co-authored-by: Joe Wojak <[email protected]>
Opentrons · Mar 6, 2024 · 4cfb58f · 4cfb58f
1 parent d2696ce
commit 4cfb58f
Show file tree

Hide file tree

Showing 3 changed files with 19 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
@@ -126,6 +126,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,14 @@ 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 ``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.
+                         - 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.
         :type volume: int or float
 
         :param location: Tells the robot where to dispense liquid held in the pipette.