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

ophyd_async/core/standard_readable.py

@@ -0,0 +1,261 @@
+import warnings
+from contextlib import contextmanager
+from typing import (
+    Callable,
+    Dict,
+    Generator,
+    Optional,
+    Sequence,
+    Tuple,
+    Type,
+    Union,
+)
+
+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, 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, AsyncStageable, HasHints
+):
+    """Device that owns its children and provides useful default behavior.
+
+    - When its name is set it renames child Devices
+    - Signals can be registered for read() and read_configuration()
+    - These signals will be subscribed for read() between stage() and unstage()
+    """
+
+    # 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,
+        read: Sequence[SignalR] = (),
+        config: Sequence[SignalR] = (),
+        read_uncached: Sequence[SignalR] = (),
+    ):
+        """
+        Parameters
+        ----------
+        read:
+            Signals to make up :meth:`~StandardReadable.read`
+        conf:
+            Signals to make up :meth:`~StandardReadable.read_configuration`
+        read_uncached:
+            Signals to make up :meth:`~StandardReadable.read` that won't be cached
+        """
+        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._stageables:
+            await sig.stage().task
+
+    @AsyncStatus.wrap
+    async def unstage(self) -> None:
+        for sig in self._stageables:
+            await sig.unstage().task
+
+    async def describe_configuration(self) -> Dict[str, DataKey]:
+        return await merge_gathered_dicts(
+            [sig.describe_configuration() for sig in self._configurables]
+        )
+
+    async def read_configuration(self) -> Dict[str, Reading]:
+        return await merge_gathered_dicts(
+            [sig.read_configuration() for sig in self._configurables]
+        )
+
+    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._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.
 
@@ -98,3 +174,24 @@ async def merge_gathered_dicts(
     for result in await asyncio.gather(*coros):
         ret.update(result)
     return ret
+
+
+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))

ophyd_async/epics/_backend/_aioca.py

@@ -1,5 +1,5 @@
+import logging
 import sys
-from asyncio import CancelledError
 from dataclasses import dataclass
 from enum import Enum
 from typing import Any, Dict, Optional, Sequence, Type, Union
@@ -8,17 +8,17 @@ from aioca import (
     FORMAT_CTRL,
     FORMAT_RAW,
     FORMAT_TIME,
+    CANothing,
     Subscription,
     caget,
     camonitor,
     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 (
-    NotConnected,
     ReadingValueCallback,
     SignalBackend,
     T,
@@ -26,6 +26,9 @@ from ophyd_async.core import (
     get_unique,
     wait_for_connection,
 )
+from ophyd_async.core.utils import DEFAULT_TIMEOUT, NotConnected
+
+from .common import get_supported_values
 
 dbr_to_dtype: Dict[Dbr, Dtype] = {
     dbr.DBR_STRING: "string",
@@ -49,24 +52,34 @@ class CaConverter:
         return value
 
     def reading(self, value: AugmentedValue):
-        return dict(
-            value=self.value(value),
-            timestamp=value.timestamp,
-            alarm_severity=-1 if value.severity > 2 else value.severity,
-        )
+        return {
+            "value": self.value(value),
+            "timestamp": value.timestamp,
+            "alarm_severity": -1 if value.severity > 2 else value.severity,
+        }
+
+    def get_datakey(self, source: str, value: AugmentedValue) -> DataKey:
+        return {"source": source, "dtype": dbr_to_dtype[value.datatype], "shape": []}
+
 
-    def descriptor(self, source: str, value: AugmentedValue) -> Descriptor:
-        return dict(source=source, dtype=dbr_to_dtype[value.datatype], shape=[])
+class CaLongStrConverter(CaConverter):
+    def __init__(self):
+        return super().__init__(dbr.DBR_CHAR_STR, dbr.DBR_CHAR_STR)
+
+    def write_value(self, value: str):
+        # Add a null in here as this is what the commandline caput does
+        # TODO: this should be in the server so check if it can be pushed to asyn
+        return value + "\0"
 
 
 class CaArrayConverter(CaConverter):
-    def descriptor(self, source: str, value: AugmentedValue) -> Descriptor:
-        return dict(source=source, dtype="array", shape=[len(value)])
+    def get_datakey(self, source: str, value: AugmentedValue) -> DataKey:
+        return {"source": source, "dtype": "array", "shape": [len(value)]}
 
 
 @dataclass
 class CaEnumConverter(CaConverter):
-    enum_class: Type[Enum]
+    choices: dict[str, str]
 
     def write_value(self, value: Union[Enum, str]):
         if isinstance(value, Enum):
@@ -75,13 +88,15 @@ class CaEnumConverter(CaConverter):
             return value
 
     def value(self, value: AugmentedValue):
-        return self.enum_class(value)
+        return self.choices[value]
 
-    def descriptor(self, source: str, value: AugmentedValue) -> Descriptor:
-        choices = [e.value for e in self.enum_class]
-        return dict(
-            source=source, dtype="string", shape=[], choices=choices
-        )  # type: ignore
+    def get_datakey(self, source: str, value: AugmentedValue) -> DataKey:
+        return {
+            "source": source,
+            "dtype": "string",
+            "shape": [],
+            "choices": list(self.choices),
+        }
 
 
 class DisconnectedCaConverter(CaConverter):
@@ -97,7 +112,7 @@ def make_converter(
     is_array = bool([v for v in values.values() if v.element_count > 1])
     if is_array and datatype is str and pv_dbr == dbr.DBR_CHAR:
         # Override waveform of chars to be treated as string
-        return CaConverter(dbr.DBR_CHAR_STR, dbr.DBR_CHAR_STR)
+        return CaLongStrConverter()
     elif is_array and pv_dbr == dbr.DBR_STRING:
         # Waveform of strings, check we wanted this
         if datatype and datatype != Sequence[str]:
@@ -127,18 +142,8 @@ def make_converter(
         pv_choices = get_unique(
             {k: tuple(v.enums) for k, v in values.items()}, "choices"
         )
-        if datatype:
-            if not issubclass(datatype, Enum):
-                raise TypeError(f"{pv} has type Enum not {datatype.__name__}")
-            choices = tuple(v.value for v in datatype)
-            if set(choices) != set(pv_choices):
-                raise TypeError(f"{pv} has choices {pv_choices} not {choices}")
-            enum_class = datatype
-        else:
-            enum_class = Enum(  # type: ignore
-                "GeneratedChoices", {x: x for x in pv_choices}, type=str
-            )
-        return CaEnumConverter(dbr.DBR_STRING, None, enum_class)
+        supported_values = get_supported_values(pv, datatype, pv_choices)
+        return CaEnumConverter(dbr.DBR_STRING, None, supported_values)
     else:
         value = list(values.values())[0]
         # Done the dbr check, so enough to check one of the values
@@ -169,26 +174,31 @@ class CaSignalBackend(SignalBackend[T]):
         self.write_pv = write_pv
         self.initial_values: Dict[str, AugmentedValue] = {}
         self.converter: CaConverter = DisconnectedCaConverter(None, None)
-        self.source = f"ca://{self.read_pv}"
         self.subscription: Optional[Subscription] = None
 
-    async def _store_initial_value(self, pv):
+    def source(self, name: str):
+        return f"ca://{self.read_pv}"
+
+    async def _store_initial_value(self, pv, timeout: float = DEFAULT_TIMEOUT):
         try:
-            self.initial_values[pv] = await caget(pv, format=FORMAT_CTRL, timeout=None)
-        except CancelledError:
-            raise NotConnected(self.source)
+            self.initial_values[pv] = await caget(
+                pv, format=FORMAT_CTRL, timeout=timeout
+            )
+        except CANothing as exc:
+            logging.debug(f"signal ca://{pv} timed out")
+            raise NotConnected(f"ca://{pv}") from exc
 
-    async def connect(self):
+    async def connect(self, timeout: float = DEFAULT_TIMEOUT):
         _use_pyepics_context_if_imported()
         if self.read_pv != self.write_pv:
             # Different, need to connect both
             await wait_for_connection(
-                read_pv=self._store_initial_value(self.read_pv),
-                write_pv=self._store_initial_value(self.write_pv),
+                read_pv=self._store_initial_value(self.read_pv, timeout=timeout),
+                write_pv=self._store_initial_value(self.write_pv, timeout=timeout),
             )
         else:
             # The same, so only need to connect one
-            await self._store_initial_value(self.read_pv)
+            await self._store_initial_value(self.read_pv, timeout=timeout)
         self.converter = make_converter(self.datatype, self.initial_values)
 
     async def put(self, value: Optional[T], wait=True, timeout=None):
@@ -212,9 +222,9 @@ class CaSignalBackend(SignalBackend[T]):
             timeout=None,
         )
 
-    async def get_descriptor(self) -> Descriptor:
+    async def get_datakey(self, source: str) -> DataKey:
         value = await self._caget(FORMAT_CTRL)
-        return self.converter.descriptor(self.source, value)
+        return self.converter.get_datakey(source, value)
 
     async def get_reading(self) -> Reading:
         value = await self._caget(FORMAT_TIME)
@@ -224,6 +234,15 @@ class CaSignalBackend(SignalBackend[T]):
         value = await self._caget(FORMAT_RAW)
         return self.converter.value(value)
 
+    async def get_setpoint(self) -> T:
+        value = await caget(
+            self.write_pv,
+            datatype=self.converter.read_dbr,
+            format=FORMAT_RAW,
+            timeout=None,
+        )
+        return self.converter.value(value)
+
     def set_callback(self, callback: Optional[ReadingValueCallback[T]]) -> None:
         if callback:
             assert (