feat(api): add final_push_out arg to mix

[jerader]

closes AUTH-1704

Overview

This PR introduces final_push_out arg to mix() in API 2.24. If final_push_out is not defined, it will default to the non-zero default push_out value for the final dispense in the mix. If it is defined, it will replace that final dispense push_out to the specified value.

This new arg allows for a customizable push_out value which we will add to PD for PD/py interop, which is what we decided on what would be best in the slack thread.

Test Plan and Hands on Testing

Review the code and test it with simulate? I added a pytest and it seems to work. Plus I tried this and it also appears to work when i check the Timeline tab in the app

    pipette_left.pick_up_tip(location=tip_rack_1)
    pipette_left.configure_for_volume(10)
    pipette_left.flow_rate.aspirate = 24
    pipette_left.flow_rate.dispense = 50
    pipette_left.mix(
        repetitions=2,
        volume=10,
        location=reservoir_1["A1"].bottom(z=1),
        final_push_out=3.9,
    )
    pipette_left.drop_tip()

Changelog

Add new arg to instrument_context.mix and add to the text_mix_with_delay test

Review requests

This is my first time editing the API and i used David's "add delay to mix()" pr as reference. I feel like I'm missing something but it does seem to work when i test it out.

Risk assessment

low, adds a new optional arg to mix()

[ecormany]

Maybe something like this, with a cross reference for the default values:

Suggested change

	:param final_push_out: Optional ``push_out`` value. If not specified, it will emit the
	default non-zero amount.
	:param final_push_out: How much to push out after the final mix repetition. The pipette will not push out after earlier repetitions. If not specified or ``None``, the pipette will push out the
	default non-zero amount. See :ref:`push-out-dispense`.

[ddcc4]

Yeah. Work with Ed on the wording. But this should explain that the default will be a positive pushout of some mystery amount.

[ecormany]

Hopefully not a mystery amount! We have defaults documented now.

[ddcc4]

Yeah. Work with Ed on the wording. But this should explain that the default will be a positive pushout of some mystery amount.

[ddcc4]

You don't need the self.api_version >= APIVersion(2, 24) condition here because the function would have already failed above if the user specified final_push_out for an API version < 2.24.

[ddcc4]

Yay!
Just FYI, I think real-world push-out amounts are limited to something like 4 uL.

[jerader]

oh, i set it high so it will be more distinguishable from the other values that were set for delay, etc. i'll change it to 2 to be more realistic though!

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 24.72%. Comparing base (d9fa3d9) to head (b1c1f7b).
Report is 10 commits behind head on edge.

Additional details and impacted files

@@             Coverage Diff             @@
##             edge   #18193       +/-   ##
===========================================
- Coverage   57.49%   24.72%   -32.77%     
===========================================
  Files        3043     3041        -2     
  Lines      255239   253423     -1816     
  Branches    30503    30447       -56     
===========================================
- Hits       146742    62661    -84081     
- Misses     108311   190739    +82428     
+ Partials      186       23      -163     

Flag	Coverage Δ
app	3.13% <ø> (-44.63%)	⬇️
labware-library	3.96% <ø> (?)
opentrons-ai-client	3.16% <ø> (-0.02%)	⬇️
protocol-designer	18.93% <ø> (ø)
step-generation	4.37% <ø> (-0.01%)	⬇️

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

see 1768 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.