ophyd-async 0.9.0a1__py3-none-any.whl → 0.10.0a1__py3-none-any.whl

ophyd_async/core/_readable.py

@@ -17,25 +17,34 @@ from ._utils import merge_gathered_dicts
 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()``
+    """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)
+    """
+
     CONFIG_SIGNAL = "CONFIG_SIGNAL"
-    #: Contribute the monitored `Signal` value to ``read()`` and ``describe()``` and
-    #: put the signal name in ``hints``
+    """Contribute the `Signal` value to `read_configuration()` and
+    `describe_configuration()`
+    """
+
     HINTED_SIGNAL = "HINTED_SIGNAL"
-    #: Contribute the uncached `Signal` value to ``read()`` and ``describe()```
+    """Contribute the monitored `Signal` value to `read()` and `describe()` and
+    put the signal name in `hints`
+    """
+
     UNCACHED_SIGNAL = "UNCACHED_SIGNAL"
-    #: Contribute the uncached `Signal` value to ``read()`` and ``describe()``` and
-    #: put the signal name in ``hints``
+    """Contribute the uncached `Signal` value to `read()` and `describe()`
+    """
+
     HINTED_UNCACHED_SIGNAL = "HINTED_UNCACHED_SIGNAL"
+    """Contribute the uncached `Signal` value to `read()` and `describe()` and
+    put the signal name in `hints`
+    """
 
     def __call__(self, parent: Device, child: Device):
         if not isinstance(parent, StandardReadable):
@@ -74,11 +83,15 @@ HintedSignal.uncached = _compat_format(
 class StandardReadable(
     Device, AsyncReadable, AsyncConfigurable, AsyncStageable, HasHints
 ):
-    """Device that owns its children and provides useful default behavior.
+    """Device that provides selected child Device values in `read()`.
+
+    Provides the ability for children to be registered to:
+    - Participate in `stage()` and `unstage()`
+    - Provide their value in `read()` and `describe()
+    - Provide their value in `read_configuration()` and `describe_configuration()
+    - Select a value to appear in `hints`
 
-    - 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()
+    The behavior is customized with a [](#StandardReadableFormat)
     """
 
     # These must be immutable types to avoid accidental sharing between
@@ -119,33 +132,35 @@ class StandardReadable(
         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;
+            # This avoids default dict merge behavior 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():
+                # fail early for unkwon types
                 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"
+                        if hints[key] != value:
+                            msg = f"Hints key {key} value may not be overridden"
+                            raise RuntimeError(msg)
                     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"
+                            if new_val in hints[key]:
+                                msg = f"Hint {key} {new_val} overrides existing hint"
+                                raise RuntimeError(msg)
                         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}' "
+                    msg = (
+                        f"{new_hint.name}: Unknown type for value '{value}'"
                         f" for key '{key}'"
                     )
+                    raise TypeError(msg)
 
         return hints
 
@@ -154,13 +169,12 @@ class StandardReadable(
         self,
         format: StandardReadableFormat = StandardReadableFormat.CHILD,
     ) -> Generator[None, None, None]:
-        """Context manager that calls `add_readables` on child Devices added within.
+        """Context manager that calls [](#add_readables) on child Devices added within.
 
-        Scans ``self.children()`` on entry and exit to context manager, and calls
-        `add_readables` on any that are added with the provided
+        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())
 
         yield
@@ -190,20 +204,22 @@ class StandardReadable(
         Use output from the given devices to contribute to the verbs of the following
         interfaces:
 
-        - `bluesky.protocols.Readable`
-        - `bluesky.protocols.Configurable`
-        - `bluesky.protocols.Stageable`
-        - `bluesky.protocols.HasHints`
-
-        Parameters
-        ----------
-        devices:
-            The devices to be added
-        format:
-            Determines which of the devices functions are added to which verb as per the
-            `StandardReadableFormat` documentation
+        - [](#bluesky.protocols.Readable)
+        - [](#bluesky.protocols.Configurable)
+        - [](#bluesky.protocols.Stageable)
+        - [](#bluesky.protocols.HasHints)
+
+        :param devices: The devices to be added
+        :param format:
+            Determines which of the devices functions are added to which verb as
+            per the [](#StandardReadableFormat) documentation
         """
 
+        def assert_device_is_signalr(device: Device) -> SignalR:
+            if not isinstance(device, SignalR):
+                raise TypeError(f"{device} is not a SignalR")
+            return device
+
         for device in devices:
             match format:
                 case StandardReadableFormat.CHILD:
@@ -218,24 +234,24 @@ class StandardReadable(
                     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,)
+                    signalr_device = assert_device_is_signalr(device=device)
+                    self._describe_config_funcs += (signalr_device.describe,)
+                    self._read_config_funcs += (signalr_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),)
+                    signalr_device = assert_device_is_signalr(device=device)
+                    self._describe_funcs += (signalr_device.describe,)
+                    self._read_funcs += (signalr_device.read,)
+                    self._stageables += (signalr_device,)
+                    self._has_hints += (_HintsFromName(signalr_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),)
+                    signalr_device = assert_device_is_signalr(device=device)
+                    self._describe_funcs += (signalr_device.describe,)
+                    self._read_funcs += (_UncachedRead(signalr_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),)
+                    signalr_device = assert_device_is_signalr(device=device)
+                    self._describe_funcs += (signalr_device.describe,)
+                    self._read_funcs += (_UncachedRead(signalr_device),)
+                    self._has_hints += (_HintsFromName(signalr_device),)
 
 
 class _UncachedRead:

ophyd_async/core/_settings.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from abc import abstractmethod
+from collections.abc import Callable, Iterator, MutableMapping
+from typing import Any, Generic
+
+from ._device import Device, DeviceT
+from ._signal import SignalRW
+from ._signal_backend import SignalDatatypeT
+
+
+class Settings(MutableMapping[SignalRW[Any], Any], Generic[DeviceT]):
+    """Used for supplying settings to signals.
+
+    :param device: The device that the settings are for.
+    :param settings: A dictionary of settings to start with.
+
+    :example:
+    ```python
+    # Settings are created from a dict of signals to values
+    settings1 = Settings(device, {device.sig1: 1, device.sig2: 2})
+    settings2 = Settings(device, {device.sig1: 10, device.sig3: 3})
+    # They act like a dictionaries
+    assert settings1[device.sig1] == 1
+    # Including the ability to "or" two settings together
+    settings = settings1 | settings2
+    assert dict(settings) == {
+        device.sig1: 10,
+        device.sig2: 2,
+        device.sig3: 3,
+    }
+    ```
+    """
+
+    def __init__(
+        self, device: DeviceT, settings: MutableMapping[SignalRW, Any] | None = None
+    ):
+        self.device = device
+        self._settings = {}
+        self.update(settings or {})
+
+    def __getitem__(self, key: SignalRW[SignalDatatypeT]) -> SignalDatatypeT:
+        return self._settings[key]
+
+    def _is_in_device(self, device: Device) -> bool:
+        while device.parent and device.parent is not self.device:
+            # While we have a parent that is not the right device
+            # continue searching up the tree
+            device = device.parent
+        return device.parent is self.device
+
+    def __setitem__(
+        self, key: SignalRW[SignalDatatypeT], value: SignalDatatypeT | None
+    ) -> None:
+        # Check the types on entry to dict to make sure we can't accidentally
+        # add a non-signal type
+        if not isinstance(key, SignalRW):
+            raise TypeError(f"Expected SignalRW, got {key}")
+        if not self._is_in_device(key):
+            raise KeyError(f"Signal {key} is not a child of {self.device}")
+        self._settings[key] = value
+
+    def __delitem__(self, key: SignalRW) -> None:
+        del self._settings[key]
+
+    def __iter__(self) -> Iterator[SignalRW]:
+        yield from iter(self._settings)
+
+    def __len__(self) -> int:
+        return len(self._settings)
+
+    def __or__(self, other: MutableMapping[SignalRW, Any]) -> Settings[DeviceT]:
+        """Create a new Settings that is the union of self overridden by other."""
+        if isinstance(other, Settings) and not self._is_in_device(other.device):
+            raise ValueError(f"{other.device} is not a child of {self.device}")
+        return Settings(self.device, self._settings | dict(other))
+
+    def partition(
+        self, predicate: Callable[[SignalRW], bool]
+    ) -> tuple[Settings[DeviceT], Settings[DeviceT]]:
+        """Partition into two Settings based on a predicate.
+
+        :param predicate:
+            Callable that takes each signal, and returns a boolean to say if it
+            should be in the first returned Settings
+        :returns:
+            `(where_true, where_false)` where each is a Settings object.
+            The first contains the signals for which the predicate returned True,
+            and the second contains the signals for which the predicate returned False.
+
+        :example:
+        ```python
+        settings = Settings(device, {device.special: 1, device.sig: 2})
+        specials, others = settings.partition(lambda sig: "special" in sig.name)
+        ```
+        """
+        where_true, where_false = Settings(self.device), Settings(self.device)
+        for signal, value in self.items():
+            dest = where_true if predicate(signal) else where_false
+            dest[signal] = value
+        return where_true, where_false
+
+
+class SettingsProvider:
+    """Base class for providing settings."""
+
+    @abstractmethod
+    async def store(self, name: str, data: dict[str, Any]):
+        """Store the data, associating it with the given name."""
+
+    @abstractmethod
+    async def retrieve(self, name: str) -> dict[str, Any]:
+        """Retrieve the data associated with the given name."""