feat(api): add option to air_gap() in place

[ddcc4]

Overview

The API air_gap() function allows you to specify a height above the well to perform the air gap. If no height is specified, then air_gap() defaults to 5 mm above the well. But that means there is no way to air gap in place without moving the pipette.

To match the capabilities of PD step generation, this PR adds a new air_gap(in_place=True) option to the API. This new parameter is gated on API version 2.24 and above. AUTH-1797

Test Plan and Hands on Testing

Added unit tests for the new in_place option, and made sure you cannot specify both in_place and a height.

Risk assessment

This is an API change, so once we release it publicly, we'll be stuck with it.

[sanni-t]

LGTM! 👍

[sanni-t]

We should update this line to mention that this applies only if in_place is False.

[ddcc4]

Good point, thanks! I've updated the docstring.

[ecormany]

I think the behavior added in this PR doesn't match the expectations we've set in the rest of the API. This would be the only API command that I know of where you would explicitly command the pipette, "Don't move! But then do an action."

I would expect that any API addition that allows an action to happen in more places than before would use something like a location argument, or expand an existing location argument's valid values. But air_gap() is strange: it doesn't have a location argument, yet it's keeping track of a location. The pipette might move, or it might not. It might move back to some Well-based location even though you've had the pipette move_to() somewhere else in the meantime. And the API doesn't have an InstrumentContext.current_location() that we can pass in. Whenever we want the pipette to stay in place for other methods, we use location=None. But that would break the behavior of older protocols migrating to 2.24 and not changing any of their air_gap() args.

I've argued around in a circle on this, so I'm not sure what the solution is. I think the conclusion may be that this is an acceptable band-aid for getting a PD feature into the Python API. But it might really be waiting on some sort of PAPIv3 unification yet to come.

[ddcc4]

I think the behavior added in this PR doesn't match the expectations we've set in the rest of the API. This would be the only API command that I know of where you would explicitly command the pipette, "Don't move! But then do an action."

Yeah. I've mentioned to the folks here that, ideally, air_gap() should behave like aspirate(), since air_gap() is really an aspiration behind the scenes. If you aspirate() and don't specify a location, it would aspirate in place. Ideally, air_gap() would do that too.

But we've already defined air_gap() with no argument to mean air-gapping 5 mm above the well, and we can't change that. So I don't see an elegant way to make air_gap() match the semantics of aspirate().

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 23.47%. Comparing base (c5c0329) to head (5ee1637).
Report is 2 commits behind head on edge.

Additional details and impacted files

@@            Coverage Diff             @@
##             edge   #18249      +/-   ##
==========================================
- Coverage   23.51%   23.47%   -0.04%     
==========================================
  Files        3059     3064       +5     
  Lines      256370   256745     +375     
  Branches    30114    30040      -74     
==========================================
+ Hits        60274    60283       +9     
- Misses     196082   196448     +366     
  Partials       14       14              

Flag	Coverage Δ
step-generation	4.55% <ø> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

see 22 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.