Add a Watchable AsyncStatus and extend the wrap decorator

[dperl-dls]

Fixes #117, fixes #45
As according to discussion in #117, adds a WatchableAsyncStatus, and improves the wrappers so that they can be applied to any function returning an Awaitable or an AsyncIterator

Will break anything previously passing watchers to AsyncStatus which will need to update to WatchableAsyncStatus (but there hopefully isn't much out there yet)

[coretl]

I had more thoughts...

[coretl]

I have a general preference for timeout rather than timeout_s as it matches all the asyncio arguments, and also the ophyd convention

[coretl]

and inlining _move

[coretl]

But here the done_status=move_status is correct as we are talking to a motor record

[coretl]

Please can we use the same wrap logic here? Something like

Suggested change

	async def _move(self, new_position: float, watchers: List[Callable] = []):
	@WatchableAsyncStatus.wrap
	async def set(self, new_position: float) -> :

then yielding WatcherUpdate instead of calling watchers

[coretl]

Just spotted this...

[coretl]

Could be soft_signal_r_and_backend

[coretl]

The original code kicked off self._observe_writer_indices and returned immediately, then returned this status in complete. This code now actually awaits this Status, which is wrong.

However, I think a simplification of the code is the better fix:

    @AsyncStatus.wrap
    async def kickoff(self) -> None:
        # Nothing to do in kickoff, we already armed in prepare
        pass

    @WatchableAsyncStatus.wrap
    async def complete(self):
        async for index in self.writer.observe_indices_written(self._frame_writing_timeout):    
            yield WatcherUpdate(
                name=self.name,
                current=index,
                initial=self._initial_frame,
                target=end_observation,
                unit="",
                precision=0,
                time_elapsed=time.monotonic() - self._fly_start,
            )
            if index >= end_observation:
                break

Then can delete _fly and _observe_writer_indices...

[dperl-dls]

Flyable tells us that kickoff and complete must both return statuses.

[coretl]

That's fine, they're both being wrapped by *AsyncStatus so return a Status. It's just that kickoff returns one that is immediately done...

[coretl]

Can't see timeout being used below...

Suggested change

	@WatchableAsyncStatus.wrap # uses the timeout argument from the function it wraps
	async def set(self, new_position: float, timeout: float | None = None):
	@WatchableAsyncStatus.wrap
	async def set(self, new_position: float):

[dperl-dls]

No, the WatchableAsyncStatus wrapper uses the timeout argument from functions that it wraps, as we discussed in detail earlier in this PR

[coretl]

Yes, but doesn't it add that to the signature itself? So the function doesn't need to mention timeout at all...

[dperl-dls]

It pulls it from kwargs, so the function still needs to either take timeout or **kwargs

[coretl]

These shouldn't be needed

Suggested change

set_sim_put_proceeds(sim_mover.setpoint, False)

[coretl]

This shouldn't be needed now we added the done_status argument above?

Suggested change

	# Trigger any callbacks
	await self.user_readback._backend.put(await self.user_readback.get_value())

[dperl-dls]

not needed for that specific status, but if you have any other callbacks here and call stop any other way it is

[coretl]

Please could you revert this test and check it still passes?

[dperl-dls]

It doesn't the way it is in main - it needs a sleep after the set_mock_value(readback ...) to process the call to the watcher. This slight alteration does pass:

async def test_motor_moving_well_2(sim_motor: motor.Motor) -> None:
    set_mock_put_proceeds(sim_motor.user_setpoint, False)
    s = sim_motor.set(0.55)
    watcher = Mock()
    s.watch(watcher)
    done = Mock()
    s.add_callback(done)
    await asyncio.sleep(A_BIT)
    assert watcher.call_count == 1
    assert watcher.call_args == call(
        name="sim_motor",
        current=0.0,
        initial=0.0,
        target=0.55,
        unit="mm",
        precision=3,
        time_elapsed=pytest.approx(0.0, abs=0.05),
    )
    watcher.reset_mock()
    assert 0.55 == await sim_motor.user_setpoint.get_value()
    assert not s.done
    await asyncio.sleep(0.1)
    set_mock_value(sim_motor.user_readback, 0.1)
    await asyncio.sleep(0.1)
    assert watcher.call_count == 1
    assert watcher.call_args == call(
        name="sim_motor",
        current=0.1,
        initial=0.0,
        target=0.55,
        unit="mm",
        precision=3,
        time_elapsed=pytest.approx(0.11, abs=0.05),
    )
    set_mock_put_proceeds(sim_motor.user_setpoint, True)
    await asyncio.sleep(A_BIT)
    assert s.done
    done.assert_called_once_with(s)