ophyd-async 0.3a2__py3-none-any.whl → 0.3a3__py3-none-any.whl

ophyd_async/_version.py

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

ophyd_async/core/__init__.py

@@ -30,6 +30,10 @@ from .signal import (
     SignalRW,
     SignalW,
     SignalX,
+    assert_configuration,
+    assert_emitted,
+    assert_reading,
+    assert_value,
     observe_value,
     set_and_wait_for_value,
     set_sim_callback,
@@ -41,7 +45,7 @@ from .signal import (
 )
 from .signal_backend import SignalBackend
 from .sim_signal_backend import SimSignalBackend
-from .standard_readable import StandardReadable
+from .standard_readable import ConfigSignal, HintedSignal, StandardReadable
 from .utils import (
     DEFAULT_TIMEOUT,
     Callback,
@@ -84,6 +88,8 @@ __all__ = [
     "ShapeProvider",
     "StaticDirectoryProvider",
     "StandardReadable",
+    "ConfigSignal",
+    "HintedSignal",
     "TriggerInfo",
     "TriggerLogic",
     "HardwareTriggeredFlyable",
@@ -103,4 +109,8 @@ __all__ = [
     "walk_rw_signals",
     "load_device",
     "save_device",
+    "assert_reading",
+    "assert_value",
+    "assert_configuration",
+    "assert_emitted",
 ]

ophyd_async/core/detector.py

@@ -19,7 +19,7 @@ from typing import (
 
 from bluesky.protocols import (
     Collectable,
-    Descriptor,
+    DataKey,
     Flyable,
     Preparable,
     Reading,
@@ -33,7 +33,6 @@ from ophyd_async.protocols import AsyncConfigurable, AsyncReadable
 
 from .async_status import AsyncStatus
 from .device import Device
-from .signal import SignalR
 from .utils import DEFAULT_TIMEOUT, merge_gathered_dicts
 
 T = TypeVar("T")
@@ -110,7 +109,7 @@ class DetectorWriter(ABC):
     (e.g. an HDF5 file)"""
 
     @abstractmethod
-    async def open(self, multiplier: int = 1) -> Dict[str, Descriptor]:
+    async def open(self, multiplier: int = 1) -> Dict[str, DataKey]:
         """Open writer and wait for it to be ready for data.
 
         Args:
@@ -161,7 +160,7 @@ class StandardDetector(
         self,
         controller: DetectorControl,
         writer: DetectorWriter,
-        config_sigs: Sequence[SignalR] = (),
+        config_sigs: Sequence[AsyncReadable] = (),
         name: str = "",
         writer_timeout: float = DEFAULT_TIMEOUT,
     ) -> None:
@@ -181,7 +180,7 @@ class StandardDetector(
         """
         self._controller = controller
         self._writer = writer
-        self._describe: Dict[str, Descriptor] = {}
+        self._describe: Dict[str, DataKey] = {}
         self._config_sigs = list(config_sigs)
         self._frame_writing_timeout = writer_timeout
         # For prepare
@@ -214,7 +213,7 @@ class StandardDetector(
     async def _check_config_sigs(self):
         """Checks configuration signals are named and connected."""
         for signal in self._config_sigs:
-            if signal._name == "":
+            if signal.name == "":
                 raise Exception(
                     "config signal must be named before it is passed to the detector"
                 )
@@ -234,14 +233,14 @@ class StandardDetector(
     async def read_configuration(self) -> Dict[str, Reading]:
         return await merge_gathered_dicts(sig.read() for sig in self._config_sigs)
 
-    async def describe_configuration(self) -> Dict[str, Descriptor]:
+    async def describe_configuration(self) -> Dict[str, DataKey]:
         return await merge_gathered_dicts(sig.describe() for sig in self._config_sigs)
 
     async def read(self) -> Dict[str, Reading]:
         # All data is in StreamResources, not Events, so nothing to output here
         return {}
 
-    async def describe(self) -> Dict[str, Descriptor]:
+    async def describe(self) -> Dict[str, DataKey]:
         return self._describe
 
     @AsyncStatus.wrap
@@ -330,7 +329,7 @@ class StandardDetector(
         assert self._fly_status, "Kickoff not run"
         return await self._fly_status
 
-    async def describe_collect(self) -> Dict[str, Descriptor]:
+    async def describe_collect(self) -> Dict[str, DataKey]:
         return self._describe
 
     async def collect_asset_docs(

ophyd_async/core/flyer.py

@@ -1,7 +1,7 @@
 from abc import ABC, abstractmethod
 from typing import Dict, Generic, Sequence, TypeVar
 
-from bluesky.protocols import Descriptor, Flyable, Preparable, Reading, Stageable
+from bluesky.protocols import DataKey, Flyable, Preparable, Reading, Stageable
 
 from .async_status import AsyncStatus
 from .device import Device
@@ -74,7 +74,7 @@ class HardwareTriggeredFlyable(
     async def complete(self) -> None:
         await self._trigger_logic.complete()
 
-    async def describe_configuration(self) -> Dict[str, Descriptor]:
+    async def describe_configuration(self) -> Dict[str, DataKey]:
         return await merge_gathered_dicts(
             [sig.describe() for sig in self._configuration_signals]
         )

ophyd_async/core/signal.py

@@ -2,19 +2,29 @@ from __future__ import annotations
 
 import asyncio
 import functools
-from typing import AsyncGenerator, Callable, Dict, Generic, Optional, Tuple, Type, Union
+from typing import (
+    Any,
+    AsyncGenerator,
+    Callable,
+    Dict,
+    Generic,
+    Mapping,
+    Optional,
+    Tuple,
+    Type,
+    Union,
+)
 
 from bluesky.protocols import (
-    Descriptor,
+    DataKey,
     Locatable,
     Location,
     Movable,
     Reading,
-    Stageable,
     Subscribable,
 )
 
-from ophyd_async.protocols import AsyncReadable
+from ophyd_async.protocols import AsyncConfigurable, AsyncReadable, AsyncStageable
 
 from .async_status import AsyncStatus
 from .device import Device
@@ -128,7 +138,7 @@ class _SignalCache(Generic[T]):
         return self._staged or bool(self._listeners)
 
 
-class SignalR(Signal[T], AsyncReadable, Stageable, Subscribable):
+class SignalR(Signal[T], AsyncReadable, AsyncStageable, Subscribable):
     """Signal that can be read from and monitored"""
 
     _cache: Optional[_SignalCache] = None
@@ -161,9 +171,9 @@ class SignalR(Signal[T], AsyncReadable, Stageable, Subscribable):
         return {self.name: await self._backend_or_cache(cached).get_reading()}
 
     @_add_timeout
-    async def describe(self) -> Dict[str, Descriptor]:
+    async def describe(self) -> Dict[str, DataKey]:
         """Return a single item dict with the descriptor in it"""
-        return {self.name: await self._backend.get_descriptor(self.source)}
+        return {self.name: await self._backend.get_datakey(self.source)}
 
     @_add_timeout
     async def get_value(self, cached: Optional[bool] = None) -> T:
@@ -272,6 +282,91 @@ def soft_signal_r_and_backend(
     return (signal, backend)
 
 
+async def assert_value(signal: SignalR[T], value: Any) -> None:
+    """Assert a signal's value and compare it an expected signal.
+
+    Parameters
+    ----------
+    signal:
+        signal with get_value.
+    value:
+        The expected value from the signal.
+
+    Notes
+    -----
+    Example usage::
+        await assert_value(signal, value)
+
+    """
+    assert await signal.get_value() == value
+
+
+async def assert_reading(
+    readable: AsyncReadable, reading: Mapping[str, Reading]
+) -> None:
+    """Assert readings from readable.
+
+    Parameters
+    ----------
+    readable:
+        Callable with readable.read function that generate readings.
+
+    reading:
+        The expected readings from the readable.
+
+    Notes
+    -----
+    Example usage::
+        await assert_reading(readable, reading)
+
+    """
+    assert await readable.read() == reading
+
+
+async def assert_configuration(
+    configurable: AsyncConfigurable,
+    configuration: Mapping[str, Reading],
+) -> None:
+    """Assert readings from Configurable.
+
+    Parameters
+    ----------
+    configurable:
+        Configurable with Configurable.read function that generate readings.
+
+    configuration:
+        The expected readings from configurable.
+
+    Notes
+    -----
+    Example usage::
+        await assert_configuration(configurable configuration)
+
+    """
+    assert await configurable.read_configuration() == configuration
+
+
+def assert_emitted(docs: Mapping[str, list[dict]], **numbers: int):
+    """Assert emitted document generated by running a Bluesky plan
+
+    Parameters
+    ----------
+    Doc:
+        A dictionary
+
+    numbers:
+        expected emission in kwarg from
+
+    Notes
+    -----
+    Example usage::
+        assert_emitted(docs, start=1, descriptor=1,
+        resource=1, datum=1, event=1, stop=1)
+    """
+    assert list(docs) == list(numbers)
+    assert {name: len(d) for name, d in docs.items()} == numbers
+
+
 async def observe_value(signal: SignalR[T], timeout=None) -> AsyncGenerator[T, None]:
     """Subscribe to the value of a signal so it can be iterated from.
 

ophyd_async/core/signal_backend.py

@@ -1,7 +1,7 @@
 from abc import abstractmethod
 from typing import Generic, Optional, Type
 
-from bluesky.protocols import Descriptor, Reading
+from bluesky.protocols import DataKey, Reading
 
 from .utils import DEFAULT_TIMEOUT, ReadingValueCallback, T
 
@@ -27,7 +27,7 @@ class SignalBackend(Generic[T]):
         """Put a value to the PV, if wait then wait for completion for up to timeout"""
 
     @abstractmethod
-    async def get_descriptor(self, source: str) -> Descriptor:
+    async def get_datakey(self, source: str) -> DataKey:
         """Metadata like source, dtype, shape, precision, units"""
 
     @abstractmethod

ophyd_async/core/sim_signal_backend.py

@@ -9,7 +9,7 @@ from enum import Enum
 from typing import Any, Dict, Generic, Optional, Type, Union, cast, get_origin
 
 import numpy as np
-from bluesky.protocols import Descriptor, Dtype, Reading
+from bluesky.protocols import DataKey, Dtype, Reading
 
 from .signal_backend import SignalBackend
 from .utils import DEFAULT_TIMEOUT, ReadingValueCallback, T, get_dtype
@@ -36,7 +36,7 @@ class SimConverter(Generic[T]):
             alarm_severity=-1 if severity > 2 else severity,
         )
 
-    def descriptor(self, source: str, value) -> Descriptor:
+    def get_datakey(self, source: str, value) -> DataKey:
         dtype = type(value)
         if np.issubdtype(dtype, np.integer):
             dtype = int
@@ -56,7 +56,7 @@ class SimConverter(Generic[T]):
 
 
 class SimArrayConverter(SimConverter):
-    def descriptor(self, source: str, value) -> Descriptor:
+    def get_datakey(self, source: str, value) -> DataKey:
         return {"source": source, "dtype": "array", "shape": [len(value)]}
 
     def make_initial_value(self, datatype: Optional[Type[T]]) -> T:
@@ -79,7 +79,7 @@ class SimEnumConverter(SimConverter):
         else:
             return self.enum_class(value)
 
-    def descriptor(self, source: str, value) -> Descriptor:
+    def get_datakey(self, source: str, value) -> DataKey:
         choices = [e.value for e in self.enum_class]
         return {"source": source, "dtype": "string", "shape": [], "choices": choices}  # type: ignore
 
@@ -164,8 +164,8 @@ class SimSignalBackend(SignalBackend[T]):
         if self.callback:
             self.callback(reading, self._value)
 
-    async def get_descriptor(self, source: str) -> Descriptor:
-        return self.converter.descriptor(source, self._value)
+    async def get_datakey(self, source: str) -> DataKey:
+        return self.converter.get_datakey(source, self._value)
 
     async def get_reading(self) -> Reading:
         return self.converter.reading(self._value, self._timestamp, self._severity)

ophyd_async/core/standard_readable.py

@@ -1,16 +1,34 @@
-from typing import Dict, Sequence, Tuple
+import warnings
+from contextlib import contextmanager
+from typing import (
+    Callable,
+    Dict,
+    Generator,
+    Optional,
+    Sequence,
+    Tuple,
+    Type,
+    Union,
+)
 
-from bluesky.protocols import Descriptor, Reading, Stageable
+from bluesky.protocols import DataKey, HasHints, Hints, Reading
 
-from ophyd_async.protocols import AsyncConfigurable, AsyncReadable
+from ophyd_async.protocols import AsyncConfigurable, AsyncReadable, AsyncStageable
 
 from .async_status import AsyncStatus
-from .device import Device
+from .device import Device, DeviceVector
 from .signal import SignalR
 from .utils import merge_gathered_dicts
 
+ReadableChild = Union[AsyncReadable, AsyncConfigurable, AsyncStageable, HasHints]
+ReadableChildWrapper = Union[
+    Callable[[ReadableChild], ReadableChild], Type["ConfigSignal"], Type["HintedSignal"]
+]
 
-class StandardReadable(Device, AsyncReadable, AsyncConfigurable, Stageable):
+
+class StandardReadable(
+    Device, AsyncReadable, AsyncConfigurable, AsyncStageable, HasHints
+):
     """Device that owns its children and provides useful default behavior.
 
     - When its name is set it renames child Devices
@@ -18,9 +36,12 @@ class StandardReadable(Device, AsyncReadable, AsyncConfigurable, Stageable):
     - These signals will be subscribed for read() between stage() and unstage()
     """
 
-    _read_signals: Tuple[SignalR, ...] = ()
-    _configuration_signals: Tuple[SignalR, ...] = ()
-    _read_uncached_signals: Tuple[SignalR, ...] = ()
+    # These must be immutable types to avoid accidental sharing between
+    # different instances of the class
+    _readables: Tuple[AsyncReadable, ...] = ()
+    _configurables: Tuple[AsyncConfigurable, ...] = ()
+    _stageables: Tuple[AsyncStageable, ...] = ()
+    _has_hints: Tuple[HasHints, ...] = ()
 
     def set_readable_signals(
         self,
@@ -38,37 +59,203 @@ class StandardReadable(Device, AsyncReadable, AsyncConfigurable, Stageable):
         read_uncached:
             Signals to make up :meth:`~StandardReadable.read` that won't be cached
         """
-        self._read_signals = tuple(read)
-        self._configuration_signals = tuple(config)
-        self._read_uncached_signals = tuple(read_uncached)
+        warnings.warn(
+            DeprecationWarning(
+                "Migrate to `add_children_as_readables` context manager or "
+                "`add_readables` method"
+            )
+        )
+        self.add_readables(read, wrapper=HintedSignal)
+        self.add_readables(config, wrapper=ConfigSignal)
+        self.add_readables(read_uncached, wrapper=HintedSignal.uncached)
 
     @AsyncStatus.wrap
     async def stage(self) -> None:
-        for sig in self._read_signals + self._configuration_signals:
+        for sig in self._stageables:
             await sig.stage().task
 
     @AsyncStatus.wrap
     async def unstage(self) -> None:
-        for sig in self._read_signals + self._configuration_signals:
+        for sig in self._stageables:
             await sig.unstage().task
 
-    async def describe_configuration(self) -> Dict[str, Descriptor]:
+    async def describe_configuration(self) -> Dict[str, DataKey]:
         return await merge_gathered_dicts(
-            [sig.describe() for sig in self._configuration_signals]
+            [sig.describe_configuration() for sig in self._configurables]
         )
 
     async def read_configuration(self) -> Dict[str, Reading]:
         return await merge_gathered_dicts(
-            [sig.read() for sig in self._configuration_signals]
+            [sig.read_configuration() for sig in self._configurables]
         )
 
-    async def describe(self) -> Dict[str, Descriptor]:
-        return await merge_gathered_dicts(
-            [sig.describe() for sig in self._read_signals + self._read_uncached_signals]
-        )
+    async def describe(self) -> Dict[str, DataKey]:
+        return await merge_gathered_dicts([sig.describe() for sig in self._readables])
 
     async def read(self) -> Dict[str, Reading]:
-        return await merge_gathered_dicts(
-            [sig.read() for sig in self._read_signals]
-            + [sig.read(cached=False) for sig in self._read_uncached_signals]
-        )
+        return await merge_gathered_dicts([sig.read() for sig in self._readables])
+
+    @property
+    def hints(self) -> Hints:
+        hints: Hints = {}
+        for new_hint in self._has_hints:
+            # Merge the existing and new hints, based on the type of the value.
+            # This avoids default dict merge behaviour that overrides the values;
+            # we want to combine them when they are Sequences, and ensure they are
+            # identical when string values.
+            for key, value in new_hint.hints.items():
+                if isinstance(value, str):
+                    if key in hints:
+                        assert (
+                            hints[key] == value  # type: ignore[literal-required]
+                        ), f"Hints key {key} value may not be overridden"
+                    else:
+                        hints[key] = value  # type: ignore[literal-required]
+                elif isinstance(value, Sequence):
+                    if key in hints:
+                        for new_val in value:
+                            assert (
+                                new_val not in hints[key]  # type: ignore[literal-required]
+                            ), f"Hint {key} {new_val} overrides existing hint"
+                        hints[key] = (  # type: ignore[literal-required]
+                            hints[key] + value  # type: ignore[literal-required]
+                        )
+                    else:
+                        hints[key] = value  # type: ignore[literal-required]
+                else:
+                    raise TypeError(
+                        f"{new_hint.name}: Unknown type for value '{value}' "
+                        f" for key '{key}'"
+                    )
+
+        return hints
+
+    @contextmanager
+    def add_children_as_readables(
+        self,
+        wrapper: Optional[ReadableChildWrapper] = None,
+    ) -> Generator[None, None, None]:
+        """Context manager to wrap adding Devices
+
+        Add Devices to this class instance inside the Context Manager to automatically
+        add them to the correct fields, based on the Device's interfaces.
+
+        The provided wrapper class will be applied to all Devices and can be used to
+        specify their behaviour.
+
+        Parameters
+        ----------
+        wrapper:
+            Wrapper class to apply to all Devices created inside the context manager.
+
+        See Also
+        --------
+        :func:`~StandardReadable.add_readables`
+        :class:`ConfigSignal`
+        :class:`HintedSignal`
+        :meth:`HintedSignal.uncached`
+        """
+
+        dict_copy = self.__dict__.copy()
+
+        yield
+
+        # Set symmetric difference operator gives all newly added keys
+        new_keys = dict_copy.keys() ^ self.__dict__.keys()
+        new_values = [self.__dict__[key] for key in new_keys]
+
+        flattened_values = []
+        for value in new_values:
+            if isinstance(value, DeviceVector):
+                children = value.children()
+                flattened_values.extend([x[1] for x in children])
+            else:
+                flattened_values.append(value)
+
+        new_devices = list(filter(lambda x: isinstance(x, Device), flattened_values))
+        self.add_readables(new_devices, wrapper)
+
+    def add_readables(
+        self,
+        devices: Sequence[Device],
+        wrapper: Optional[ReadableChildWrapper] = None,
+    ) -> None:
+        """Add the given devices to the lists of known Devices
+
+        Add the provided Devices to the relevant fields, based on the Signal's
+        interfaces.
+
+        The provided wrapper class will be applied to all Devices and can be used to
+        specify their behaviour.
+
+        Parameters
+        ----------
+        devices:
+            The devices to be added
+        wrapper:
+            Wrapper class to apply to all Devices created inside the context manager.
+
+        See Also
+        --------
+        :func:`~StandardReadable.add_children_as_readables`
+        :class:`ConfigSignal`
+        :class:`HintedSignal`
+        :meth:`HintedSignal.uncached`
+        """
+
+        for readable in devices:
+            obj = readable
+            if wrapper:
+                obj = wrapper(readable)
+
+            if isinstance(obj, AsyncReadable):
+                self._readables += (obj,)
+
+            if isinstance(obj, AsyncConfigurable):
+                self._configurables += (obj,)
+
+            if isinstance(obj, AsyncStageable):
+                self._stageables += (obj,)
+
+            if isinstance(obj, HasHints):
+                self._has_hints += (obj,)
+
+
+class ConfigSignal(AsyncConfigurable):
+    def __init__(self, signal: ReadableChild) -> None:
+        assert isinstance(signal, SignalR), f"Expected signal, got {signal}"
+        self.signal = signal
+
+    async def read_configuration(self) -> Dict[str, Reading]:
+        return await self.signal.read()
+
+    async def describe_configuration(self) -> Dict[str, DataKey]:
+        return await self.signal.describe()
+
+
+class HintedSignal(HasHints, AsyncReadable):
+    def __init__(self, signal: ReadableChild, allow_cache: bool = True) -> None:
+        assert isinstance(signal, SignalR), f"Expected signal, got {signal}"
+        self.signal = signal
+        self.cached = None if allow_cache else allow_cache
+        if allow_cache:
+            self.stage = signal.stage
+            self.unstage = signal.unstage
+
+    async def read(self) -> Dict[str, Reading]:
+        return await self.signal.read(cached=self.cached)
+
+    async def describe(self) -> Dict[str, DataKey]:
+        return await self.signal.describe()
+
+    @property
+    def name(self) -> str:
+        return self.signal.name
+
+    @property
+    def hints(self) -> Hints:
+        return {"fields": [self.signal.name]}
+
+    @classmethod
+    def uncached(cls, signal: ReadableChild) -> "HintedSignal":
+        return cls(signal, allow_cache=False)

ophyd_async/epics/_backend/_aioca.py

@@ -15,7 +15,7 @@ from aioca import (
     caput,
 )
 from aioca.types import AugmentedValue, Dbr, Format
-from bluesky.protocols import Descriptor, Dtype, Reading
+from bluesky.protocols import DataKey, Dtype, Reading
 from epicscorelibs.ca import dbr
 
 from ophyd_async.core import (
@@ -58,7 +58,7 @@ class CaConverter:
             "alarm_severity": -1 if value.severity > 2 else value.severity,
         }
 
-    def descriptor(self, source: str, value: AugmentedValue) -> Descriptor:
+    def get_datakey(self, source: str, value: AugmentedValue) -> DataKey:
         return {"source": source, "dtype": dbr_to_dtype[value.datatype], "shape": []}
 
 
@@ -73,7 +73,7 @@ class CaLongStrConverter(CaConverter):
 
 
 class CaArrayConverter(CaConverter):
-    def descriptor(self, source: str, value: AugmentedValue) -> Descriptor:
+    def get_datakey(self, source: str, value: AugmentedValue) -> DataKey:
         return {"source": source, "dtype": "array", "shape": [len(value)]}
 
 
@@ -90,7 +90,7 @@ class CaEnumConverter(CaConverter):
     def value(self, value: AugmentedValue):
         return self.enum_class(value)
 
-    def descriptor(self, source: str, value: AugmentedValue) -> Descriptor:
+    def get_datakey(self, source: str, value: AugmentedValue) -> DataKey:
         choices = [e.value for e in self.enum_class]
         return {"source": source, "dtype": "string", "shape": [], "choices": choices}
 
@@ -218,9 +218,9 @@ class CaSignalBackend(SignalBackend[T]):
             timeout=None,
         )
 
-    async def get_descriptor(self, source: str) -> Descriptor:
+    async def get_datakey(self, source: str) -> DataKey:
         value = await self._caget(FORMAT_CTRL)
-        return self.converter.descriptor(source, value)
+        return self.converter.get_datakey(source, value)
 
     async def get_reading(self) -> Reading:
         value = await self._caget(FORMAT_TIME)