ophyd-async 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

ophyd_async/core/{sim_signal_backend.py → soft_signal_backend.py}

@@ -1,18 +1,17 @@
 from __future__ import annotations
 
-import asyncio
 import inspect
-import re
 import time
 from collections import abc
 from dataclasses import dataclass
 from enum import Enum
-from typing import Any, Dict, Generic, Optional, Type, Union, cast, get_origin
+from typing import Dict, Generic, Optional, Type, Union, cast, get_origin
 
-from bluesky.protocols import Descriptor, Dtype, Reading
+import numpy as np
+from bluesky.protocols import DataKey, Dtype, Reading
 
 from .signal_backend import SignalBackend
-from .utils import ReadingValueCallback, T, get_dtype
+from .utils import DEFAULT_TIMEOUT, ReadingValueCallback, T, get_dtype
 
 primitive_dtypes: Dict[type, Dtype] = {
     str: "string",
@@ -22,7 +21,7 @@ primitive_dtypes: Dict[type, Dtype] = {
 }
 
 
-class SimConverter(Generic[T]):
+class SoftConverter(Generic[T]):
     def value(self, value: T) -> T:
         return value
 
@@ -36,12 +35,17 @@ 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
+        elif np.issubdtype(dtype, np.floating):
+            dtype = float
         assert (
-            type(value) in primitive_dtypes
+            dtype in primitive_dtypes
         ), f"invalid converter for value of type {type(value)}"
-        dtype = primitive_dtypes[type(value)]
-        return dict(source=source, dtype=dtype, shape=[])
+        dtype_name = primitive_dtypes[dtype]
+        return {"source": source, "dtype": dtype_name, "shape": []}
 
     def make_initial_value(self, datatype: Optional[Type[T]]) -> T:
         if datatype is None:
@@ -50,9 +54,9 @@ class SimConverter(Generic[T]):
         return datatype()
 
 
-class SimArrayConverter(SimConverter):
-    def descriptor(self, source: str, value) -> Descriptor:
-        return dict(source=source, dtype="array", shape=[len(value)])
+class SoftArrayConverter(SoftConverter):
+    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:
         if datatype is None:
@@ -65,7 +69,7 @@ class SimArrayConverter(SimConverter):
 
 
 @dataclass
-class SimEnumConverter(SimConverter):
+class SoftEnumConverter(SoftConverter):
     enum_class: Type[Enum]
 
     def write_value(self, value: Union[Enum, str]) -> Enum:
@@ -74,11 +78,9 @@ 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 dict(
-            source=source, dtype="string", shape=[], choices=choices
-        )  # type: ignore
+        return {"source": source, "dtype": "string", "shape": [], "choices": choices}  # type: ignore
 
     def make_initial_value(self, datatype: Optional[Type[T]]) -> T:
         if datatype is None:
@@ -87,48 +89,50 @@ class SimEnumConverter(SimConverter):
         return cast(T, list(datatype.__members__.values())[0])  # type: ignore
 
 
-class DisconnectedSimConverter(SimConverter):
-    def __getattribute__(self, __name: str) -> Any:
-        raise NotImplementedError("No PV has been set as connect() has not been called")
-
-
 def make_converter(datatype):
     is_array = get_dtype(datatype) is not None
     is_sequence = get_origin(datatype) == abc.Sequence
     is_enum = issubclass(datatype, Enum) if inspect.isclass(datatype) else False
 
     if is_array or is_sequence:
-        return SimArrayConverter()
+        return SoftArrayConverter()
     if is_enum:
-        return SimEnumConverter(datatype)
+        return SoftEnumConverter(datatype)
 
-    return SimConverter()
+    return SoftConverter()
 
 
-class SimSignalBackend(SignalBackend[T]):
-    """An simulated backend to a Signal, created with ``Signal.connect(sim=True)``"""
+class SoftSignalBackend(SignalBackend[T]):
+    """An backend to a soft Signal, for test signals see ``MockSignalBackend``."""
 
     _value: T
-    _initial_value: T
+    _initial_value: Optional[T]
     _timestamp: float
     _severity: int
 
-    def __init__(self, datatype: Optional[Type[T]], source: str) -> None:
-        pv = re.split(r"://", source)[-1]
-        self.source = f"sim://{pv}"
+    def __init__(
+        self,
+        datatype: Optional[Type[T]],
+        initial_value: Optional[T] = None,
+    ) -> None:
         self.datatype = datatype
-        self.pv = source
-        self.converter: SimConverter = DisconnectedSimConverter()
-        self.put_proceeds = asyncio.Event()
-        self.put_proceeds.set()
-        self.callback: Optional[ReadingValueCallback[T]] = None
+        self._initial_value = initial_value
+        self.converter: SoftConverter = make_converter(datatype)
+        if self._initial_value is None:
+            self._initial_value = self.converter.make_initial_value(self.datatype)
+        else:
+            self._initial_value = self.converter.write_value(self._initial_value)
 
-    async def connect(self) -> None:
-        self.converter = make_converter(self.datatype)
-        self._initial_value = self.converter.make_initial_value(self.datatype)
+        self.callback: Optional[ReadingValueCallback[T]] = None
         self._severity = 0
+        self.set_value(self._initial_value)
+
+    def source(self, name: str) -> str:
+        return f"soft://{name}"
 
-        await self.put(None)
+    async def connect(self, timeout: float = DEFAULT_TIMEOUT) -> None:
+        """Connection isn't required for soft signals."""
+        pass
 
     async def put(self, value: Optional[T], wait=True, timeout=None):
         write_value = (
@@ -136,13 +140,11 @@ class SimSignalBackend(SignalBackend[T]):
             if value is not None
             else self._initial_value
         )
-        self._set_value(write_value)
 
-        if wait:
-            await asyncio.wait_for(self.put_proceeds.wait(), timeout)
+        self.set_value(write_value)
 
-    def _set_value(self, value: T):
-        """Method to bypass asynchronous logic, designed to only be used in tests."""
+    def set_value(self, value: T):
+        """Method to bypass asynchronous logic."""
         self._value = value
         self._timestamp = time.monotonic()
         reading: Reading = self.converter.reading(
@@ -152,8 +154,8 @@ class SimSignalBackend(SignalBackend[T]):
         if self.callback:
             self.callback(reading, self._value)
 
-    async def get_descriptor(self) -> Descriptor:
-        return self.converter.descriptor(self.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)
@@ -162,7 +164,7 @@ class SimSignalBackend(SignalBackend[T]):
         return self.converter.value(self._value)
 
     async def get_setpoint(self) -> T:
-        """For a simulated backend, the setpoint and readback values are the same."""
+        """For a soft signal, the setpoint and readback values are the same."""
         return await self.get_value()
 
     def set_callback(self, callback: Optional[ReadingValueCallback[T]]) -> None:

ophyd_async/core/standard_readable.py

@@ -1,14 +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 Configurable, Descriptor, Readable, Reading, Stageable
+from bluesky.protocols import DataKey, HasHints, Hints, Reading
+
+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, Readable, Configurable, 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
@@ -16,9 +36,12 @@ class StandardReadable(Device, Readable, Configurable, 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,
@@ -36,37 +59,203 @@ class StandardReadable(Device, Readable, Configurable, 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/core/utils.py

@@ -1,56 +1,132 @@
+from __future__ import annotations
+
 import asyncio
-from typing import Awaitable, Callable, Dict, Iterable, List, Optional, Type, TypeVar
+import logging
+from dataclasses import dataclass
+from typing import (
+    Awaitable,
+    Callable,
+    Dict,
+    Generic,
+    Iterable,
+    List,
+    Optional,
+    ParamSpec,
+    Type,
+    TypeVar,
+    Union,
+)
 
 import numpy as np
 from bluesky.protocols import Reading
 
 T = TypeVar("T")
+P = ParamSpec("P")
 Callback = Callable[[T], None]
 
 #: A function that will be called with the Reading and value when the
 #: monitor updates
 ReadingValueCallback = Callable[[Reading, T], None]
 DEFAULT_TIMEOUT = 10.0
+ErrorText = Union[str, Dict[str, Exception]]
+
+
+class CalculateTimeout:
+    """Sentinel class used to implement ``myfunc(timeout=CalculateTimeout)``
+
+    This signifies that the function should calculate a suitable non-zero
+    timeout itself
+    """
+
+
+CalculatableTimeout = float | None | Type[CalculateTimeout]
 
 
 class NotConnected(Exception):
     """Exception to be raised if a `Device.connect` is cancelled"""
 
-    def __init__(self, *lines: str):
-        self.lines = list(lines)
+    _indent_width = "    "
+
+    def __init__(self, errors: ErrorText):
+        """
+        NotConnected holds a mapping of device/signal names to
+        errors.
+
+        Parameters
+        ----------
+        errors: ErrorText
+            Mapping of device name to Exception or another NotConnected.
+            Alternatively a string with the signal error text.
+        """
+
+        self._errors = errors
+
+    def _format_sub_errors(self, name: str, error: Exception, indent="") -> str:
+        if isinstance(error, NotConnected):
+            error_txt = ":" + error.format_error_string(indent + self._indent_width)
+        elif isinstance(error, Exception):
+            error_txt = ": " + err_str + "\n" if (err_str := str(error)) else "\n"
+        else:
+            raise RuntimeError(
+                f"Unexpected type `{type(error)}`, expected an Exception"
+            )
+
+        string = f"{indent}{name}: {type(error).__name__}" + error_txt
+        return string
+
+    def format_error_string(self, indent="") -> str:
+        if not isinstance(self._errors, dict) and not isinstance(self._errors, str):
+            raise RuntimeError(
+                f"Unexpected type `{type(self._errors)}` " "expected `str` or `dict`"
+            )
+
+        if isinstance(self._errors, str):
+            return " " + self._errors + "\n"
+
+        string = "\n"
+        for name, error in self._errors.items():
+            string += self._format_sub_errors(name, error, indent=indent)
+        return string
 
     def __str__(self) -> str:
-        return "\n".join(self.lines)
+        return self.format_error_string(indent="")
+
+
+@dataclass(frozen=True)
+class WatcherUpdate(Generic[T]):
+    """A dataclass such that, when expanded, it provides the kwargs for a watcher"""
+
+    current: T
+    initial: T
+    target: T
+    name: str | None = None
+    unit: str | None = None
+    precision: float | None = None
+    fraction: float | None = None
+    time_elapsed: float | None = None
+    time_remaining: float | None = None
 
 
 async def wait_for_connection(**coros: Awaitable[None]):
-    """Call many underlying signals, accumulating `NotConnected` exceptions
+    """Call many underlying signals, accumulating exceptions and returning them
 
-    Raises
-    ------
-    `NotConnected` if cancelled
+    Expected kwargs should be a mapping of names to coroutine tasks to execute.
     """
-    ts = {k: asyncio.create_task(c) for (k, c) in coros.items()}  # type: ignore
-    try:
-        done, pending = await asyncio.wait(ts.values())
-    except asyncio.CancelledError:
-        for t in ts.values():
-            t.cancel()
-        lines: List[str] = []
-        for k, t in ts.items():
-            try:
-                await t
-            except NotConnected as e:
-                if len(e.lines) == 1:
-                    lines.append(f"{k}: {e.lines[0]}")
-                else:
-                    lines.append(f"{k}:")
-                    lines += [f"  {line}" for line in e.lines]
-        raise NotConnected(*lines)
-    else:
-        # Wait for everything to foreground the exceptions
-        for f in list(done) + list(pending):
-            await f
+    results = await asyncio.gather(*coros.values(), return_exceptions=True)
+    exceptions = {}
+
+    for name, result in zip(coros, results):
+        if isinstance(result, Exception):
+            exceptions[name] = result
+            if not isinstance(result, NotConnected):
+                logging.exception(
+                    f"device `{name}` raised unexpected exception "
+                    f"{type(result).__name__}",
+                    exc_info=result,
+                )
+
+    if exceptions:
+        raise NotConnected(exceptions)
 
 
 def get_dtype(typ: Type) -> Optional[np.dtype]:
@@ -86,7 +162,7 @@ def get_unique(values: Dict[str, T], types: str) -> T:
 
 
 async def merge_gathered_dicts(
-    coros: Iterable[Awaitable[Dict[str, T]]]
+    coros: Iterable[Awaitable[Dict[str, T]]],
 ) -> Dict[str, T]:
     """Merge dictionaries produced by a sequence of coroutines.
 
@@ -102,3 +178,20 @@ async def merge_gathered_dicts(
 
 async def gather_list(coros: Iterable[Awaitable[T]]) -> List[T]:
     return await asyncio.gather(*coros)
+
+
+def in_micros(t: float) -> int:
+    """
+    Converts between a positive number of seconds and an equivalent
+    number of microseconds.
+
+    Args:
+        t (float): A time in seconds
+    Raises:
+        ValueError: if t < 0
+    Returns:
+        t (int): A time in microseconds, rounded up to the nearest whole microsecond,
+    """
+    if t < 0:
+        raise ValueError(f"Expected a positive time in seconds, got {t!r}")
+    return int(np.ceil(t * 1e6))