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

ophyd_async/core/_readable.py

@@ -1,6 +1,8 @@
 import warnings
-from collections.abc import Callable, Generator, Sequence
+from collections.abc import Awaitable, Callable, Generator, Sequence
 from contextlib import contextmanager
+from enum import Enum
+from typing import Any, cast
 
 from bluesky.protocols import HasHints, Hints, Reading
 from event_model import DataKey
@@ -11,11 +13,61 @@ from ._signal import SignalR
 from ._status import AsyncStatus
 from ._utils import merge_gathered_dicts
 
-ReadableChild = AsyncReadable | AsyncConfigurable | AsyncStageable | HasHints
-ReadableChildWrapper = (
-    Callable[[ReadableChild], ReadableChild]
-    | type["ConfigSignal"]
-    | type["HintedSignal"]
+
+class StandardReadableFormat(Enum):
+    """Declare how a `Device` should contribute to the `StandardReadable` verbs."""
+
+    #: Detect which verbs the child supports and contribute to:
+    #:
+    #: - ``read()``, ``describe()`` if it is `bluesky.protocols.Readable`
+    #: - ``read_configuration()``, ``describe_configuration()`` if it is
+    #:   `bluesky.protocols.Configurable`
+    #: - ``stage()``, ``unstage()`` if it is `bluesky.protocols.Stageable`
+    #: - ``hints`` if it `bluesky.protocols.HasHints`
+    CHILD = "CHILD"
+    #: Contribute the `Signal` value to ``read_configuration()`` and
+    #: ``describe_configuration()``
+    CONFIG_SIGNAL = "CONFIG_SIGNAL"
+    #: Contribute the monitored `Signal` value to ``read()`` and ``describe()``` and
+    #: put the signal name in ``hints``
+    HINTED_SIGNAL = "HINTED_SIGNAL"
+    #: Contribute the uncached `Signal` value to ``read()`` and ``describe()```
+    UNCACHED_SIGNAL = "UNCACHED_SIGNAL"
+    #: Contribute the uncached `Signal` value to ``read()`` and ``describe()``` and
+    #: put the signal name in ``hints``
+    HINTED_UNCACHED_SIGNAL = "HINTED_UNCACHED_SIGNAL"
+
+    def __call__(self, parent: Device, child: Device):
+        if not isinstance(parent, StandardReadable):
+            raise TypeError(f"Expected parent to be StandardReadable, got {parent}")
+        parent.add_readables([child], self)
+
+
+# Back compat
+class _WarningMatcher:
+    def __init__(self, name: str, target: StandardReadableFormat):
+        self._name = name
+        self._target = target
+
+    def __eq__(self, value: object) -> bool:
+        warnings.warn(
+            DeprecationWarning(
+                f"Use `StandardReadableFormat.{self._target.name}` "
+                f"instead of `{self._name}`"
+            ),
+            stacklevel=2,
+        )
+        return value == self._target
+
+
+def _compat_format(name: str, target: StandardReadableFormat) -> StandardReadableFormat:
+    return cast(StandardReadableFormat, _WarningMatcher(name, target))
+
+
+ConfigSignal = _compat_format("ConfigSignal", StandardReadableFormat.CONFIG_SIGNAL)
+HintedSignal: Any = _compat_format("HintedSignal", StandardReadableFormat.HINTED_SIGNAL)
+HintedSignal.uncached = _compat_format(
+    "HintedSignal.uncached", StandardReadableFormat.HINTED_UNCACHED_SIGNAL
 )
 
 
@@ -31,38 +83,13 @@ class StandardReadable(
 
     # These must be immutable types to avoid accidental sharing between
     # different instances of the class
-    _readables: tuple[AsyncReadable, ...] = ()
-    _configurables: tuple[AsyncConfigurable, ...] = ()
+    _describe_config_funcs: tuple[Callable[[], Awaitable[dict[str, DataKey]]], ...] = ()
+    _read_config_funcs: tuple[Callable[[], Awaitable[dict[str, Reading]]], ...] = ()
+    _describe_funcs: tuple[Callable[[], Awaitable[dict[str, DataKey]]], ...] = ()
+    _read_funcs: tuple[Callable[[], Awaitable[dict[str, Reading]]], ...] = ()
     _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"
-            ),
-            stacklevel=2,
-        )
-        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:
@@ -75,19 +102,17 @@ class StandardReadable(
 
     async def describe_configuration(self) -> dict[str, DataKey]:
         return await merge_gathered_dicts(
-            [sig.describe_configuration() for sig in self._configurables]
+            [func() for func in self._describe_config_funcs]
         )
 
     async def read_configuration(self) -> dict[str, Reading]:
-        return await merge_gathered_dicts(
-            [sig.read_configuration() for sig in self._configurables]
-        )
+        return await merge_gathered_dicts([func() for func in self._read_config_funcs])
 
     async def describe(self) -> dict[str, DataKey]:
-        return await merge_gathered_dicts([sig.describe() for sig in self._readables])
+        return await merge_gathered_dicts([func() for func in self._describe_funcs])
 
     async def read(self) -> dict[str, Reading]:
-        return await merge_gathered_dicts([sig.read() for sig in self._readables])
+        return await merge_gathered_dicts([func() for func in self._read_funcs])
 
     @property
     def hints(self) -> Hints:
@@ -127,27 +152,13 @@ class StandardReadable(
     @contextmanager
     def add_children_as_readables(
         self,
-        wrapper: ReadableChildWrapper | None = None,
+        format: StandardReadableFormat = StandardReadableFormat.CHILD,
     ) -> Generator[None, None, None]:
-        """Context manager to wrap adding Devices
+        """Context manager that calls `add_readables` on child Devices added within.
 
-        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`
+        Scans ``self.children()`` on entry and exit to context manager, and calls
+        `add_readables` on any that are added with the provided
+        `StandardReadableFormat`.
         """
 
         dict_copy = dict(self.children())
@@ -167,95 +178,83 @@ class StandardReadable(
                 flattened_values.append(value)
 
         new_devices = list(filter(lambda x: isinstance(x, Device), flattened_values))
-        self.add_readables(new_devices, wrapper)
+        self.add_readables(new_devices, format)
 
     def add_readables(
         self,
-        devices: Sequence[ReadableChild],
-        wrapper: ReadableChildWrapper | None = None,
+        devices: Sequence[Device],
+        format: StandardReadableFormat = StandardReadableFormat.CHILD,
     ) -> None:
-        """Add the given devices to the lists of known Devices
+        """Add devices to contribute to various bluesky verbs.
 
-        Add the provided Devices to the relevant fields, based on the Signal's
-        interfaces.
+        Use output from the given devices to contribute to the verbs of the following
+        interfaces:
 
-        The provided wrapper class will be applied to all Devices and can be used to
-        specify their behaviour.
+        - `bluesky.protocols.Readable`
+        - `bluesky.protocols.Configurable`
+        - `bluesky.protocols.Stageable`
+        - `bluesky.protocols.HasHints`
 
         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`
+        format:
+            Determines which of the devices functions are added to which verb as per the
+            `StandardReadableFormat` documentation
         """
 
-        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}"
+        for device in devices:
+            match format:
+                case StandardReadableFormat.CHILD:
+                    if isinstance(device, AsyncConfigurable):
+                        self._describe_config_funcs += (device.describe_configuration,)
+                        self._read_config_funcs += (device.read_configuration,)
+                    if isinstance(device, AsyncReadable):
+                        self._describe_funcs += (device.describe,)
+                        self._read_funcs += (device.read,)
+                    if isinstance(device, AsyncStageable):
+                        self._stageables += (device,)
+                    if isinstance(device, HasHints):
+                        self._has_hints += (device,)
+                case StandardReadableFormat.CONFIG_SIGNAL:
+                    assert isinstance(device, SignalR), f"{device} is not a SignalR"
+                    self._describe_config_funcs += (device.describe,)
+                    self._read_config_funcs += (device.read,)
+                case StandardReadableFormat.HINTED_SIGNAL:
+                    assert isinstance(device, SignalR), f"{device} is not a SignalR"
+                    self._describe_funcs += (device.describe,)
+                    self._read_funcs += (device.read,)
+                    self._stageables += (device,)
+                    self._has_hints += (_HintsFromName(device),)
+                case StandardReadableFormat.UNCACHED_SIGNAL:
+                    assert isinstance(device, SignalR), f"{device} is not a SignalR"
+                    self._describe_funcs += (device.describe,)
+                    self._read_funcs += (_UncachedRead(device),)
+                case StandardReadableFormat.HINTED_UNCACHED_SIGNAL:
+                    assert isinstance(device, SignalR), f"{device} is not a SignalR"
+                    self._describe_funcs += (device.describe,)
+                    self._read_funcs += (_UncachedRead(device),)
+                    self._has_hints += (_HintsFromName(device),)
+
+
+class _UncachedRead:
+    def __init__(self, signal: SignalR) -> None:
         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()
-
-    @property
-    def name(self) -> str:
-        return self.signal.name
+    async def __call__(self) -> dict[str, Reading]:
+        return await self.signal.read(cached=False)
 
 
-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()
+class _HintsFromName(HasHints):
+    def __init__(self, device: Device) -> None:
+        self.device = device
 
     @property
     def name(self) -> str:
-        return self.signal.name
+        return self.device.name
 
     @property
     def hints(self) -> Hints:
-        if self.signal.name == "":
-            return {"fields": []}
-        return {"fields": [self.signal.name]}
-
-    @classmethod
-    def uncached(cls, signal: ReadableChild) -> "HintedSignal":
-        return cls(signal, allow_cache=False)
+        fields = [self.name] if self.name else []
+        return {"fields": fields}

ophyd_async/core/_utils.py

@@ -5,7 +5,15 @@ import logging
 from collections.abc import Awaitable, Callable, Iterable, Sequence
 from dataclasses import dataclass
 from enum import Enum, EnumMeta
-from typing import Any, Generic, Literal, ParamSpec, TypeVar, get_args, get_origin
+from typing import (
+    Any,
+    Generic,
+    Literal,
+    ParamSpec,
+    TypeVar,
+    get_args,
+    get_origin,
+)
 
 import numpy as np
 

ophyd_async/epics/adaravis/_aravis_io.py

@@ -1,6 +1,6 @@
 from ophyd_async.core import StrictEnum, SubsetEnum
 from ophyd_async.epics import adcore
-from ophyd_async.epics.signal import epics_signal_rw_rbv
+from ophyd_async.epics.core import epics_signal_rw_rbv
 
 
 class AravisTriggerMode(StrictEnum):

ophyd_async/epics/adcore/_core_io.py

@@ -1,5 +1,5 @@
 from ophyd_async.core import Device, StrictEnum
-from ophyd_async.epics.signal import (
+from ophyd_async.epics.core import (
     epics_signal_r,
     epics_signal_rw,
     epics_signal_rw_rbv,

ophyd_async/epics/adcore/_single_trigger.py

@@ -3,13 +3,8 @@ from collections.abc import Sequence
 
 from bluesky.protocols import Triggerable
 
-from ophyd_async.core import (
-    AsyncStatus,
-    ConfigSignal,
-    HintedSignal,
-    SignalR,
-    StandardReadable,
-)
+from ophyd_async.core import AsyncStatus, SignalR, StandardReadable
+from ophyd_async.core import StandardReadableFormat as Format
 
 from ._core_io import ADBaseIO, NDPluginBaseIO
 from ._utils import ImageMode
@@ -28,10 +23,10 @@ class SingleTriggerDetector(StandardReadable, Triggerable):
 
         self.add_readables(
             [self.drv.array_counter, *read_uncached],
-            wrapper=HintedSignal.uncached,
+            Format.HINTED_UNCACHED_SIGNAL,
         )
 
-        self.add_readables([self.drv.acquire_time], wrapper=ConfigSignal)
+        self.add_readables([self.drv.acquire_time], Format.CONFIG_SIGNAL)
 
         super().__init__(name=name)
 

ophyd_async/epics/adkinetix/_kinetix_io.py

@@ -1,6 +1,6 @@
 from ophyd_async.core import StrictEnum
 from ophyd_async.epics import adcore
-from ophyd_async.epics.signal import epics_signal_rw_rbv
+from ophyd_async.epics.core import epics_signal_rw_rbv
 
 
 class KinetixTriggerMode(StrictEnum):

ophyd_async/epics/adpilatus/_pilatus_io.py

@@ -1,6 +1,6 @@
 from ophyd_async.core import StrictEnum
 from ophyd_async.epics import adcore
-from ophyd_async.epics.signal import epics_signal_r, epics_signal_rw_rbv
+from ophyd_async.epics.core import epics_signal_r, epics_signal_rw_rbv
 
 
 class PilatusTriggerMode(StrictEnum):

ophyd_async/epics/advimba/_vimba_io.py

@@ -1,6 +1,6 @@
 from ophyd_async.core import StrictEnum
 from ophyd_async.epics import adcore
-from ophyd_async.epics.signal import epics_signal_rw_rbv
+from ophyd_async.epics.core import epics_signal_rw_rbv
 
 
 class VimbaPixelFormat(StrictEnum):

ophyd_async/epics/core/__init__.py

@@ -0,0 +1,26 @@
+from ._epics_connector import EpicsDeviceConnector, PvSuffix
+from ._epics_device import EpicsDevice
+from ._pvi_connector import PviDeviceConnector
+from ._signal import (
+    CaSignalBackend,
+    PvaSignalBackend,
+    epics_signal_r,
+    epics_signal_rw,
+    epics_signal_rw_rbv,
+    epics_signal_w,
+    epics_signal_x,
+)
+
+__all__ = [
+    "PviDeviceConnector",
+    "EpicsDeviceConnector",
+    "PvSuffix",
+    "EpicsDevice",
+    "CaSignalBackend",
+    "PvaSignalBackend",
+    "epics_signal_r",
+    "epics_signal_rw",
+    "epics_signal_rw_rbv",
+    "epics_signal_w",
+    "epics_signal_x",
+]

ophyd_async/epics/{signal → core}/_aioca.py

@@ -24,7 +24,6 @@ from ophyd_async.core import (
     Array1D,
     Callback,
     NotConnected,
-    SignalBackend,
     SignalDatatype,
     SignalDatatypeT,
     SignalMetadata,
@@ -34,7 +33,7 @@ from ophyd_async.core import (
     wait_for_connection,
 )
 
-from ._common import format_datatype, get_supported_values
+from ._util import EpicsSignalBackend, format_datatype, get_supported_values
 
 
 def _limits_from_augmented_value(value: AugmentedValue) -> Limits:
@@ -227,19 +226,17 @@ def _use_pyepics_context_if_imported():
         _tried_pyepics = True
 
 
-class CaSignalBackend(SignalBackend[SignalDatatypeT]):
+class CaSignalBackend(EpicsSignalBackend[SignalDatatypeT]):
     def __init__(
         self,
         datatype: type[SignalDatatypeT] | None,
         read_pv: str = "",
         write_pv: str = "",
     ):
-        self.read_pv = read_pv
-        self.write_pv = write_pv
         self.converter: CaConverter = DisconnectedCaConverter(float, dbr.DBR_DOUBLE)
         self.initial_values: dict[str, AugmentedValue] = {}
         self.subscription: Subscription | None = None
-        super().__init__(datatype)
+        super().__init__(datatype, read_pv, write_pv)
 
     def source(self, name: str, read: bool):
         return f"ca://{self.read_pv if read else self.write_pv}"

ophyd_async/epics/core/_epics_connector.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from ophyd_async.core import Device, DeviceConnector, DeviceFiller
+
+from ._signal import EpicsSignalBackend, get_signal_backend_type, split_protocol_from_pv
+
+
+@dataclass
+class PvSuffix:
+    read_suffix: str
+    write_suffix: str | None = None
+
+    @classmethod
+    def rbv(cls, write_suffix: str, rbv_suffix: str = "_RBV") -> PvSuffix:
+        return cls(write_suffix + rbv_suffix, write_suffix)
+
+
+def fill_backend_with_prefix(
+    prefix: str, backend: EpicsSignalBackend, annotations: list[Any]
+):
+    unhandled = []
+    while annotations:
+        annotation = annotations.pop(0)
+        if isinstance(annotation, PvSuffix):
+            backend.read_pv = prefix + annotation.read_suffix
+            backend.write_pv = prefix + (
+                annotation.write_suffix or annotation.read_suffix
+            )
+        else:
+            unhandled.append(annotation)
+    annotations.extend(unhandled)
+    # These leftover annotations will now be handled by the iterator
+
+
+class EpicsDeviceConnector(DeviceConnector):
+    def __init__(self, prefix: str) -> None:
+        self.prefix = prefix
+
+    def create_children_from_annotations(self, device: Device):
+        if not hasattr(self, "filler"):
+            protocol, prefix = split_protocol_from_pv(self.prefix)
+            self.filler = DeviceFiller(
+                device,
+                signal_backend_factory=get_signal_backend_type(protocol),
+                device_connector_factory=DeviceConnector,
+            )
+            for backend, annotations in self.filler.create_signals_from_annotations():
+                fill_backend_with_prefix(prefix, backend, annotations)
+
+            list(self.filler.create_devices_from_annotations())

ophyd_async/epics/core/_epics_device.py

@@ -0,0 +1,13 @@
+from ophyd_async.core import Device
+
+from ._epics_connector import EpicsDeviceConnector
+from ._pvi_connector import PviDeviceConnector
+
+
+class EpicsDevice(Device):
+    def __init__(self, prefix: str, with_pvi: bool = False, name: str = ""):
+        if with_pvi:
+            connector = PviDeviceConnector(prefix)
+        else:
+            connector = EpicsDeviceConnector(prefix)
+        super().__init__(name=name, connector=connector)

ophyd_async/epics/{signal → core}/_p4p.py

@@ -18,7 +18,6 @@ from ophyd_async.core import (
     Array1D,
     Callback,
     NotConnected,
-    SignalBackend,
     SignalDatatype,
     SignalDatatypeT,
     SignalMetadata,
@@ -30,7 +29,7 @@ from ophyd_async.core import (
     wait_for_connection,
 )
 
-from ._common import format_datatype, get_supported_values
+from ._util import EpicsSignalBackend, format_datatype, get_supported_values
 
 
 def _limits_from_value(value: Any) -> Limits:
@@ -293,19 +292,17 @@ def _pva_request_string(fields: Sequence[str]) -> str:
     return f"field({','.join(fields)})"
 
 
-class PvaSignalBackend(SignalBackend[SignalDatatypeT]):
+class PvaSignalBackend(EpicsSignalBackend[SignalDatatypeT]):
     def __init__(
         self,
         datatype: type[SignalDatatypeT] | None,
         read_pv: str = "",
         write_pv: str = "",
     ):
-        self.read_pv = read_pv
-        self.write_pv = write_pv
         self.converter: PvaConverter = DisconnectedPvaConverter(float)
         self.initial_values: dict[str, Any] = {}
         self.subscription: Subscription | None = None
-        super().__init__(datatype)
+        super().__init__(datatype, read_pv, write_pv)
 
     def source(self, name: str, read: bool):
         return f"pva://{self.read_pv if read else self.write_pv}"