From d6f22ac7e9240e79239182a323da650797ff073e Mon Sep 17 00:00:00 2001 From: Ed Cormany Date: Wed, 6 Mar 2024 15:21:17 -0500 Subject: [PATCH] docs(api): Python Protocol API 2.17 (#14493) Documenting changes in version 2.17 of the Python Protocol API --------- Co-authored-by: Joe Wojak --- api/docs/v2/basic_commands/liquids.rst | 10 +++++--- api/docs/v2/versioning.rst | 7 ++++++ .../protocol_api/instrument_context.py | 24 ++++++++++++------- 3 files changed, 30 insertions(+), 11 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index f5f4d670319..06f5dfd3bf8 100644 --- 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 `. Or to move it a large amount, use :ref:`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 index 10cd50d7392..91d2fcfd924 100644 --- 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 index e92c1bb6bab..3e2d6cac2a2 100644 --- 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(