ophyd-async 0.3a4__tar.gz → 0.3a6__tar.gz

{ophyd_async-0.3a4 → ophyd_async-0.3a6}/.codecov.yml

@@ -8,7 +8,7 @@ coverage:
         threshold: 1%
     patch:
       default:
-        target: auto
+        target: 90
         threshold: 1%
 github_checks:
   annotations: false

{ophyd_async-0.3a4 → ophyd_async-0.3a6}/.github/workflows/_release.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Create GitHub Release
         # We pin to the SHA, not the tag, for security reasons.
         # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
-        uses: softprops/action-gh-release@9d7c94cfd0a1f3ed45544c887983e9fa900f0564 # v2.0.4
+        uses: softprops/action-gh-release@69320dbe05506a9a39fc8ae11030b214ec2d1f87 # v2.0.5
         with:
           prerelease: ${{ contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc') }}
           files: "*"

{ophyd_async-0.3a4 → ophyd_async-0.3a6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ophyd-async
-Version: 0.3a4
+Version: 0.3a6
 Summary: Asynchronous Bluesky hardware abstraction code, compatible with control systems like EPICS and Tango
 Author-email: Tom Cobb <tom.cobb@diamond.ac.uk>
 License: BSD 3-Clause License

{ophyd_async-0.3a4 → ophyd_async-0.3a6}/docs/explanations/design-goals.rst

@@ -32,7 +32,7 @@ Parity with Malcolm
 
 Ophyd-async should provide the same building blocks for defining flyscans scans as malcolm_. It should support PandA and Zebra as timing masters by default, but also provide easy helpers for developers to write support for their own devices.
 
-It should enable `motor trajectory scanning <motortraj_>` and `multiple triggering rates<detectorsync_>` based around a base rate, and pausing/resuming scans. Scans should be modelled using scanspec_, which serves as a universal language for defining trajectory and time-resolved scans, and converted to the underlying format of the given motion controller. It should also be possible to define an `outer scan <outerscan_>`.
+It should enable motor trajectory scanning and multiple triggering rates based around a base rate, and pausing/resuming scans. Scans should be modelled using scanspec_, which serves as a universal language for defining trajectory and time-resolved scans, and converted to the underlying format of the given motion controller. It should also be possible to define an outer scan .
 
 
 Improved Trajectory Calculation

ophyd_async-0.3a6/docs/explanations/flyscanning.rst

@@ -0,0 +1,29 @@
+Flyscanning
+===========
+
+See the documents in the [bluesky cookbook](http://blueskyproject.io/bluesky-cookbook/glossary/flyscanning.html)
+
+Hardware
+--------
+
+Ophyd-async ships with support for Quantum Detectors' PandA_ and Zebra_ as triggering mechanisms.
+
+These are very modular and can be used to trigger a variety of detectors and handle readback signals from a variety of sample control devices. See full specs for more information.
+
+It is possible to write support for additional systems/devices.
+
+
+Role of Ophyd-Async
+-------------------
+
+Bluesky supports devices that configure acquisition and then hand over control to an external system via the ``Flyer`` protocol. 
+
+Ophyd-async's job is to provide devices that implement ``Flyer`` and can:
+
+- Configure all necessary hardware for a scan
+- Kickoff a scan and monitor progress until complete
+- Produce documents representing the progress of the scan
+- Allow handing control back and forth to enable outer scanning
+
+.. _PandA: https://quantumdetectors.com/products/pandabox/
+.. _Zebra: https://quantumdetectors.com/products/zebra/

{ophyd_async-0.3a4 → ophyd_async-0.3a6}/src/ophyd_async/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.3a4'
+__version__ = version = '0.3a6'
 __version_tuple__ = version_tuple = (0, 3)

{ophyd_async-0.3a4 → ophyd_async-0.3a6}/src/ophyd_async/core/__init__.py

@@ -5,7 +5,7 @@ from ._providers import (
     ShapeProvider,
     StaticDirectoryProvider,
 )
-from .async_status import AsyncStatus
+from .async_status import AsyncStatus, WatchableAsyncStatus
 from .detector import (
     DetectorControl,
     DetectorTrigger,
@@ -57,6 +57,8 @@ from .soft_signal_backend import SoftSignalBackend
 from .standard_readable import ConfigSignal, HintedSignal, StandardReadable
 from .utils import (
     DEFAULT_TIMEOUT,
+    CalculatableTimeout,
+    CalculateTimeout,
     Callback,
     NotConnected,
     ReadingValueCallback,
@@ -96,6 +98,7 @@ __all__ = [
     "set_mock_value",
     "wait_for_value",
     "AsyncStatus",
+    "WatchableAsyncStatus",
     "DirectoryInfo",
     "DirectoryProvider",
     "NameProvider",
@@ -107,6 +110,8 @@ __all__ = [
     "TriggerInfo",
     "TriggerLogic",
     "HardwareTriggeredFlyable",
+    "CalculateTimeout",
+    "CalculatableTimeout",
     "DEFAULT_TIMEOUT",
     "Callback",
     "NotConnected",

ophyd_async-0.3a6/src/ophyd_async/core/async_status.py

@@ -0,0 +1,142 @@
+"""Equivalent of bluesky.protocols.Status for asynchronous tasks."""
+
+import asyncio
+import functools
+import time
+from dataclasses import asdict, replace
+from typing import (
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Generic,
+    Type,
+    TypeVar,
+    cast,
+)
+
+from bluesky.protocols import Status
+
+from ..protocols import Watcher
+from .utils import Callback, P, T, WatcherUpdate
+
+AS = TypeVar("AS", bound="AsyncStatus")
+WAS = TypeVar("WAS", bound="WatchableAsyncStatus")
+
+
+class AsyncStatusBase(Status):
+    """Convert asyncio awaitable to bluesky Status interface"""
+
+    def __init__(self, awaitable: Awaitable):
+        if isinstance(awaitable, asyncio.Task):
+            self.task = awaitable
+        else:
+            self.task = asyncio.create_task(awaitable)
+        self.task.add_done_callback(self._run_callbacks)
+        self._callbacks: list[Callback[Status]] = []
+
+    def __await__(self):
+        return self.task.__await__()
+
+    def add_callback(self, callback: Callback[Status]):
+        if self.done:
+            callback(self)
+        else:
+            self._callbacks.append(callback)
+
+    def _run_callbacks(self, task: asyncio.Task):
+        for callback in self._callbacks:
+            callback(self)
+
+    def exception(self, timeout: float | None = 0.0) -> BaseException | None:
+        if timeout != 0.0:
+            raise ValueError(
+                "cannot honour any timeout other than 0 in an asynchronous function"
+            )
+        if self.task.done():
+            try:
+                return self.task.exception()
+            except asyncio.CancelledError as e:
+                return e
+        return None
+
+    @property
+    def done(self) -> bool:
+        return self.task.done()
+
+    @property
+    def success(self) -> bool:
+        return (
+            self.task.done()
+            and not self.task.cancelled()
+            and self.task.exception() is None
+        )
+
+    def __repr__(self) -> str:
+        if self.done:
+            if e := self.exception():
+                status = f"errored: {repr(e)}"
+            else:
+                status = "done"
+        else:
+            status = "pending"
+        return f"<{type(self).__name__}, task: {self.task.get_coro()}, {status}>"
+
+    __str__ = __repr__
+
+
+class AsyncStatus(AsyncStatusBase):
+    @classmethod
+    def wrap(cls: Type[AS], f: Callable[P, Awaitable]) -> Callable[P, AS]:
+        """Wrap an async function in an AsyncStatus."""
+
+        @functools.wraps(f)
+        def wrap_f(*args: P.args, **kwargs: P.kwargs) -> AS:
+            return cls(f(*args, **kwargs))
+
+        # type is actually functools._Wrapped[P, Awaitable, P, AS]
+        # but functools._Wrapped is not necessarily available
+        return cast(Callable[P, AS], wrap_f)
+
+
+class WatchableAsyncStatus(AsyncStatusBase, Generic[T]):
+    """Convert AsyncIterator of WatcherUpdates to bluesky Status interface."""
+
+    def __init__(self, iterator: AsyncIterator[WatcherUpdate[T]]):
+        self._watchers: list[Watcher] = []
+        self._start = time.monotonic()
+        self._last_update: WatcherUpdate[T] | None = None
+        super().__init__(self._notify_watchers_from(iterator))
+
+    async def _notify_watchers_from(self, iterator: AsyncIterator[WatcherUpdate[T]]):
+        async for update in iterator:
+            self._last_update = (
+                update
+                if update.time_elapsed is not None
+                else replace(update, time_elapsed=time.monotonic() - self._start)
+            )
+            for watcher in self._watchers:
+                self._update_watcher(watcher, self._last_update)
+
+    def _update_watcher(self, watcher: Watcher, update: WatcherUpdate[T]):
+        vals = asdict(
+            update, dict_factory=lambda d: {k: v for k, v in d if v is not None}
+        )
+        watcher(**vals)
+
+    def watch(self, watcher: Watcher):
+        self._watchers.append(watcher)
+        if self._last_update:
+            self._update_watcher(watcher, self._last_update)
+
+    @classmethod
+    def wrap(
+        cls: Type[WAS],
+        f: Callable[P, AsyncIterator[WatcherUpdate[T]]],
+    ) -> Callable[P, WAS]:
+        """Wrap an AsyncIterator in a WatchableAsyncStatus."""
+
+        @functools.wraps(f)
+        def wrap_f(*args: P.args, **kwargs: P.kwargs) -> WAS:
+            return cls(f(*args, **kwargs))
+
+        return cast(Callable[P, WAS], wrap_f)

{ophyd_async-0.3a4 → ophyd_async-0.3a6}/src/ophyd_async/core/detector.py

@@ -31,9 +31,9 @@ from bluesky.protocols import (
 
 from ophyd_async.protocols import AsyncConfigurable, AsyncReadable
 
-from .async_status import AsyncStatus
+from .async_status import AsyncStatus, WatchableAsyncStatus
 from .device import Device
-from .utils import DEFAULT_TIMEOUT, merge_gathered_dicts
+from .utils import DEFAULT_TIMEOUT, WatcherUpdate, merge_gathered_dicts
 
 T = TypeVar("T")
 
@@ -188,7 +188,7 @@ class StandardDetector(
         self._trigger_info: Optional[TriggerInfo] = None
         # For kickoff
         self._watchers: List[Callable] = []
-        self._fly_status: Optional[AsyncStatus] = None
+        self._fly_status: Optional[WatchableAsyncStatus] = None
         self._fly_start: float
 
         self._intial_frame: int
@@ -292,43 +292,37 @@ class StandardDetector(
             f"Detector {self.controller} needs at least {required}s deadtime, "
             f"but trigger logic provides only {self._trigger_info.deadtime}s"
         )
-
         self._arm_status = await self.controller.arm(
             num=self._trigger_info.num,
             trigger=self._trigger_info.trigger,
             exposure=self._trigger_info.livetime,
         )
-
-    @AsyncStatus.wrap
-    async def kickoff(self) -> None:
-        self._fly_status = AsyncStatus(self._fly(), self._watchers)
         self._fly_start = time.monotonic()
 
-    async def _fly(self) -> None:
-        await self._observe_writer_indicies(self._last_frame)
-
-    async def _observe_writer_indicies(self, end_observation: int):
+    @AsyncStatus.wrap
+    async def kickoff(self):
+        if not self._arm_status:
+            raise Exception("Detector not armed!")
+
+    @WatchableAsyncStatus.wrap
+    async def complete(self):
+        assert self._arm_status, "Prepare not run"
+        assert self._trigger_info
         async for index in self.writer.observe_indices_written(
             self._frame_writing_timeout
         ):
-            for watcher in self._watchers:
-                watcher(
-                    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:
+            yield WatcherUpdate(
+                name=self.name,
+                current=index,
+                initial=self._initial_frame,
+                target=self._trigger_info.num,
+                unit="",
+                precision=0,
+                time_elapsed=time.monotonic() - self._fly_start,
+            )
+            if index >= self._trigger_info.num:
                 break
 
-    @AsyncStatus.wrap
-    async def complete(self) -> AsyncStatus:
-        assert self._fly_status, "Kickoff not run"
-        return await self._fly_status
-
     async def describe_collect(self) -> Dict[str, DataKey]:
         return self._describe
 
@@ -338,7 +332,7 @@ class StandardDetector(
         # Collect stream datum documents for all indices written.
         # The index is optional, and provided for fly scans, however this needs to be
         # retrieved for step scans.
-        if not index:
+        if index is None:
             index = await self.writer.get_indices_written()
         async for doc in self.writer.collect_stream_docs(index):
             yield doc

{ophyd_async-0.3a4 → ophyd_async-0.3a6}/src/ophyd_async/core/device.py

@@ -1,7 +1,6 @@
 """Base device"""
 
-from __future__ import annotations
-
+import asyncio
 import sys
 from functools import cached_property
 from logging import LoggerAdapter, getLogger
@@ -31,7 +30,10 @@ class Device(HasName):
 
     _name: str = ""
     #: The parent Device if it exists
-    parent: Optional[Device] = None
+    parent: Optional["Device"] = None
+    # None if connect hasn't started, a Task if it has
+    _connect_task: Optional[asyncio.Task] = None
+    _connect_mock_arg: bool = False
 
     def __init__(self, name: str = "") -> None:
         self.set_name(name)
@@ -47,7 +49,7 @@ class Device(HasName):
             getLogger("ophyd_async.devices"), {"ophyd_async_device_name": self.name}
         )
 
-    def children(self) -> Iterator[Tuple[str, Device]]:
+    def children(self) -> Iterator[Tuple[str, "Device"]]:
         for attr_name, attr in self.__dict__.items():
             if attr_name != "parent" and isinstance(attr, Device):
                 yield attr_name, attr
@@ -71,7 +73,12 @@ class Device(HasName):
             child.set_name(child_name)
             child.parent = self
 
-    async def connect(self, mock: bool = False, timeout: float = DEFAULT_TIMEOUT):
+    async def connect(
+        self,
+        mock: bool = False,
+        timeout: float = DEFAULT_TIMEOUT,
+        force_reconnect: bool = False,
+    ):
         """Connect self and all child Devices.
 
         Contains a timeout that gets propagated to child.connect methods.
@@ -83,12 +90,26 @@ class Device(HasName):
         timeout:
             Time to wait before failing with a TimeoutError.
         """
-        coros = {
-            name: child_device.connect(mock=mock, timeout=timeout)
-            for name, child_device in self.children()
-        }
-        if coros:
-            await wait_for_connection(**coros)
+        # If previous connect with same args has started and not errored, can use it
+        can_use_previous_connect = (
+            self._connect_task
+            and not (self._connect_task.done() and self._connect_task.exception())
+            and self._connect_mock_arg == mock
+        )
+        if force_reconnect or not can_use_previous_connect:
+            # Kick off a connection
+            coros = {
+                name: child_device.connect(
+                    mock, timeout=timeout, force_reconnect=force_reconnect
+                )
+                for name, child_device in self.children()
+            }
+            self._connect_task = asyncio.create_task(wait_for_connection(**coros))
+            self._connect_mock_arg = mock
+
+        assert self._connect_task, "Connect task not created, this shouldn't happen"
+        # Wait for it to complete
+        await self._connect_task
 
 
 VT = TypeVar("VT", bound=Device)

{ophyd_async-0.3a4 → ophyd_async-0.3a6}/src/ophyd_async/core/flyer.py

@@ -39,7 +39,7 @@ class HardwareTriggeredFlyable(
     def __init__(
         self,
         trigger_logic: TriggerLogic[T],
-        configuration_signals: Sequence[SignalR],
+        configuration_signals: Sequence[SignalR] = (),
         name: str = "",
     ):
         self._trigger_logic = trigger_logic

{ophyd_async-0.3a4 → ophyd_async-0.3a6}/src/ophyd_async/core/mock_signal_backend.py

@@ -1,6 +1,7 @@
 import asyncio
+from functools import cached_property
 from typing import Optional, Type
-from unittest.mock import MagicMock
+from unittest.mock import Mock
 
 from bluesky.protocols import Descriptor, Reading
 
@@ -36,51 +37,49 @@ class MockSignalBackend(SignalBackend):
         else:
             self.soft_backend = initial_backend
 
-        self.mock = MagicMock()
-
-        self.put_proceeds = asyncio.Event()
-        self.put_proceeds.set()
-
     def source(self, name: str) -> str:
-        self.mock.source(name)
         if self.initial_backend:
             return f"mock+{self.initial_backend.source(name)}"
         return f"mock+{name}"
 
     async def connect(self, timeout: float = DEFAULT_TIMEOUT) -> None:
-        self.mock.connect(timeout=timeout)
+        pass
+
+    @cached_property
+    def put_mock(self) -> Mock:
+        return Mock(name="put")
+
+    @cached_property
+    def put_proceeds(self) -> asyncio.Event:
+        put_proceeds = asyncio.Event()
+        put_proceeds.set()
+        return put_proceeds
 
     async def put(self, value: Optional[T], wait=True, timeout=None):
-        self.mock.put(value, wait=wait, timeout=timeout)
+        self.put_mock(value, wait=wait, timeout=timeout)
         await self.soft_backend.put(value, wait=wait, timeout=timeout)
 
         if wait:
             await asyncio.wait_for(self.put_proceeds.wait(), timeout=timeout)
 
     def set_value(self, value: T):
-        self.mock.set_value(value)
         self.soft_backend.set_value(value)
 
     async def get_descriptor(self, source: str) -> Descriptor:
-        self.mock.get_descriptor(source)
         return await self.soft_backend.get_descriptor(source)
 
     async def get_reading(self) -> Reading:
-        self.mock.get_reading()
         return await self.soft_backend.get_reading()
 
     async def get_value(self) -> T:
-        self.mock.get_value()
         return await self.soft_backend.get_value()
 
     async def get_setpoint(self) -> T:
         """For a soft signal, the setpoint and readback values are the same."""
-        self.mock.get_setpoint()
         return await self.soft_backend.get_setpoint()
 
     async def get_datakey(self, source: str) -> Descriptor:
         return await self.soft_backend.get_datakey(source)
 
     def set_callback(self, callback: Optional[ReadingValueCallback[T]]) -> None:
-        self.mock.set_callback(callback)
         self.soft_backend.set_callback(callback)

{ophyd_async-0.3a4 → ophyd_async-0.3a6}/src/ophyd_async/core/mock_signal_utils.py

@@ -1,6 +1,6 @@
 from contextlib import asynccontextmanager, contextmanager
-from typing import Any, Callable, Generator, Iterable, Iterator, List
-from unittest.mock import ANY
+from typing import Any, Callable, Iterable, Iterator, List
+from unittest.mock import ANY, Mock
 
 from ophyd_async.core.signal import Signal
 from ophyd_async.core.utils import T
@@ -43,12 +43,12 @@ async def mock_puts_blocked(*signals: List[Signal]):
 
 def assert_mock_put_called_with(signal: Signal, value: Any, wait=ANY, timeout=ANY):
     backend = _get_mock_signal_backend(signal)
-    backend.mock.put.assert_called_with(value, wait=wait, timeout=timeout)
+    backend.put_mock.assert_called_with(value, wait=wait, timeout=timeout)
 
 
 def reset_mock_put_calls(signal: Signal):
     backend = _get_mock_signal_backend(signal)
-    backend.mock.put.reset_mock()
+    backend.put_mock.reset_mock()
 
 
 class _SetValuesIterator:
@@ -122,16 +122,12 @@ def set_mock_values(
 
 
 @contextmanager
-def _unset_side_effect_cm(mock):
+def _unset_side_effect_cm(put_mock: Mock):
     yield
-    mock.put.side_effect = None
+    put_mock.side_effect = None
 
 
-# linting isn't smart enought to realize @contextmanager will give use a
-# ContextManager[None]
-def callback_on_mock_put(
-    signal: Signal, callback: Callable[[T], None]
-) -> Generator[None, None, None]:
+def callback_on_mock_put(signal: Signal, callback: Callable[[T], None]):
     """For setting a callback when a backend is put to.
 
     Can either be used in a context, with the callback being
@@ -145,5 +141,5 @@ def callback_on_mock_put(
         The callback to call when the backend is put to during the context.
     """
     backend = _get_mock_signal_backend(signal)
-    backend.mock.put.side_effect = callback
-    return _unset_side_effect_cm(backend.mock)
+    backend.put_mock.side_effect = callback
+    return _unset_side_effect_cm(backend.put_mock)