feat(api): add keep_last_tip argument to liquid class transfer methods

[jbleon95]

Overview

Closes AUTH-1996.

This PR adds a new argument keep_last_tip to three liquid class transfer functions (transfer_with_liquid_class, consolidate_with_liquid_class, and distribute_with_liquid_class). If this is set to True, the last (or only tip for never and once) will not be dropped at the end of the high level transfer/consolidate/distribute. Otherwise, the last tip will be dropped, even if the tip policy is never.

In order to maintain existing behavior, this new argument will actually default to None to represent it not being set. If the value is None, we will default to keep_last_tip=False for all tip policies EXCEPT never, which will default to True. This preserves existing behavior and ensures that if not set, it continues to work as expect and if set, works in a logical and orthogonal way.

Test Plan and Hands on Testing

Unit tests and integration tests should cover for any regressions, and the following protocol should work as described in the comments

requirements = {
	"robotType": "Flex",
	"apiLevel": "2.24"
}

metadata = {
    "protocolName":'Liquid Class keep last tip',
    'author':'Jeremy'
}

def run(protocol_context):
	tiprack = protocol_context.load_labware("opentrons_flex_96_tiprack_1000ul", "C2")
	trash = protocol_context.load_trash_bin('A3')
	pipette_1k = protocol_context.load_instrument("flex_1channel_1000", "right", tip_racks=[tiprack])
	nest_plate = protocol_context.load_labware("nest_96_wellplate_2ml_deep", "D1")
	arma_plate = protocol_context.load_labware("armadillo_96_wellplate_200ul_pcr_full_skirt", "D3")

	water_class = protocol_context.get_liquid_class("water")

	pipette_1k.pick_up_tip()
	
	# Tip should stay on at the end, default behavior
	pipette_1k.transfer_with_liquid_class(
		liquid_class=water_class,
		volume=200,
		source=nest_plate['A1'],
		dest=arma_plate['A1'],
		new_tip="never",
		trash_location=trash,
	)
	# Tip should be dropped at the end
	pipette_1k.transfer_with_liquid_class(
		liquid_class=water_class,
		volume=200,
		source=nest_plate['A1'],
		dest=arma_plate['A1'],
		new_tip="never",
		trash_location=trash,
		keep_last_tip=False,
	)

	# Tip should be dropped at the end, default behavior
	pipette_1k.transfer_with_liquid_class(
		liquid_class=water_class,
		volume=200,
		source=nest_plate['A1'],
		dest=arma_plate['A1'],
		new_tip="once",
		trash_location=trash,
	)
	# Tip should be kept at the end
	pipette_1k.transfer_with_liquid_class(
		liquid_class=water_class,
		volume=200,
		source=nest_plate['A1'],
		dest=arma_plate['A1'],
		new_tip="once",
		trash_location=trash,
		keep_last_tip=True,
	)
	pipette_1k.drop_tip()

Changelog

• add keep_last_tip to transfer_with_liquid_class, consolidate_with_liquid_class, and distribute_with_liquid_class to control whether the last (or only) tip used is dropped at the end

Review requests

Mostly name and doc string related suggestions.

Risk assessment

Low-medium, theres changes to all three liquid class functions but the scope is pretty small and the changes overall do not complicate the code.

[ddcc4]

You might want to mention what the return value of this function means -- i.e., if this function returns True, we are really keeping the last tip.

[ddcc4]

So this is saying we never want to end the whole transfer with an air gap in the tip?

[jbleon95]

Yup, because we want the tip to be empty if we are keeping it

[ddcc4]

This keep_last_tip is after you've resolved it, right?

[jbleon95]

Yes, at this point it will either reflect the default or the user's intentions

[ecormany]

Requesting some changes to docstrings (which are :meta private: in this branch, but will become public by the release of 8.5).

Also, regarding docstrings and versioning: is this param retconned into API level 2.23 along with the various _with_liquid_classes, or should we call it out as added in 2.24?

[ecormany]

Prose suggestions below. Highest priority change is to use the term new_tip (the public parameter name) instead of "tip policy" (an internal implementation name).

Suggested change

	:param keep_last_tip: If set to ``True``, do not drop or return the last tip used in the transfer. If set to
	``False``, the last tip will be dropped or returned. If not set, default depends on tip policy chosen. A
	tip policy of ``"never"`` will default to ``True``, all other tip policies will default to ``False``.
	:param keep_last_tip: When ``True``, the pipette keeps the last tip used in the transfer attached. When
	``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.

[ecormany]

And replicate any changes here in the other two functions, modulo action name (transfer/consolidate/distribute).

[jerader]

tested with a protocol I made in PD with 3 steps: transfer, consolidate, and distribute. each with a new_tip:"once" and keep_last_tip=True with drop_tip()s in between and passed analysis 🚀

[ecormany]

New param docstrings look good. Broader things (unhiding docstrings, choosing a version decorator) can be done elsewhere.

[ddcc4]

OK, implementation looks fine.

The issue of the public state vs internal state not knowing that the tip is still attached is a separate bug that we can fix afterwards.