feat!: Redesign BlueapiClient for use in scripts

[tpoliaw]

Where previously the BlueapiClient was mostly a thin wrapper around the
BlueapiRestClient, it is now a more standalone class intended to be
usable from other scripts/applications as well as interactive sessions.

The client can now be created from just the path to a config file
without the user having to handle parsing.

Plans can now be run with less boilerplate with a more method-like
interface. Available devices can be queried and then used as if they
were local objects when running plans.

Using the new client

from blueapi.client.client import BlueapiClient
bc = BlueapiClient.from_config_file("/path/to/config.yaml")
bc.instrument_session = "cm12345-1"

This client can then be reused to run plans or query devices.

for dev in bc.devices:
    print(dev)
    print("    " + ", ".join(p.name for p in dev.model.protocols))

det = bc.devices.det
stage = bc.devices.stage

Sub-devices can also be accessed, while checking that the sub-device
exists on the server:

# assuming the default devices in adsim
stage_x = stage.x # returns new device
det_x = det.x # raises AttributeError

Available plans can be accessed from the server and treated
(approximately) like local methods. Calling a plan as a method blocks
while the plan is running

count = bc.plans.count
help(count) # Display docstring from plan
assert str(count) == "count(detectors, num=None, delay=None, metadata=None)"

# Arguments can be passed as positional arguments
count([det, stage.x], 3) # det and stage from previous step

# ...or by keyword
count([det, stage.x], delay=12)

# ... but the same argument can't use both
count([det], detectors=[stage.x]) # raises TypeError

Other client methods have been replaced by (cached) properties:

print(bc.environment)
print(bc.oidc_config)

if bc.state == WorkerState.IDLE
    # previous methods are mostly still available
    bc.run_task(...)
else:
    print(bc.active_task)

While running in an interactive session, plans and devices are
auto-completable if the REPL supports it.

[codecov]

Codecov Report

❌ Patch coverage is 99.07834% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.29%. Comparing base (ff433a8) to head (c2cbcd1).

Files with missing lines	Patch %	Lines
src/blueapi/client/client.py	98.80%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1323      +/-   ##
==========================================
+ Coverage   95.00%   95.29%   +0.28%     
==========================================
  Files          42       42              
  Lines        2765     2909     +144     
==========================================
+ Hits         2627     2772     +145     
+ Misses        138      137       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[DominicOram]

Some initial thoughts without having looked into it too much:

• Without docs/more usage tests it's not obvious to me what the interface is supposed to look like. It looks like I can run my plan by either doing client.plans.my_plan(args) or something like client.run_task(TaskRequest(name="my_plan"...). We should only allow one and make the other private. client.plans.my_plan(args) feels quite magic to me but I do quite like it as an interface as it reads really nicely for the end scripts
• Should: What is the difference between run_task and create_and_start_task seems to me we only need one?
• Could: I think that for a user a task and a plan are pretty synonymous so I would change the wording so that the client just talks about plans, not tasks

[tpoliaw]

Thanks for looking at it. You're right, it needs a lot more docs but I wanted to wait to check the interface was vaguely right before writing it up. I'll add something to the PR for now.

• It looks like I can run my plan by either doing client.plans.my_plan(args) or something like client.run_task(TaskRequest(name="my_plan"...). We should only allow one and make the other private.

The client.plans.my_plan(client.devices.stage.x, optional=other) interface is the one added here and is the one intended for use in scripts.

The run_task/create_and_start_task methods were there before and I didn't want to break backwards compatibility too much. Maybe if we're changing it anyway, breaking everything at once isn't the end of the world.

• Should: What is the difference between run_task and create_and_start_task seems to me we only need one?

run_task blocks, create_and_start doesn't

• Could: I think that for a user a task and a plan are pretty synonymous so I would change the wording so that the client just talks about plans, not tasks

Not a bad idea but all the task related things were here before this PR so should be a separate change. Could be rolled into #1080 as that already removes the TaskRequest parameters

[tpoliaw]

This requires #1315

[tpoliaw]

Should interrupting a plan abort the plan on the server?

[olliesilvester]

Was there an outcome for this PR after the demo last week? Personally I think it's best to just merge and get people to use it and get feedback that way.

I agree with the comments about docs. I think a simple quickstart guide for making a script and for starting in interactive mode would be fine to start with. Ideally a BL scientist can use the client given that their beamline already has BlueAPI running

[tpoliaw]

I think that was pretty much the decision. The other PR to add type-checking would be useful but can be a later PR. I will rebase this one and add the cancel-plan-on-interrupt change but then I think it can go in. The sooner it gets used in anger the problems can be found.

It is a breaking change though so I don't know what we do about versioning