ophyd-async 0.8.0a5__py3-none-any.whl → 0.9.0__py3-none-any.whl

ophyd_async/core/_device.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import asyncio
 import sys
-from collections.abc import Coroutine, Iterator, Mapping, MutableMapping
+from collections.abc import Awaitable, Callable, Iterator, Mapping, MutableMapping
 from functools import cached_property
 from logging import LoggerAdapter, getLogger
 from typing import Any, TypeVar
@@ -10,7 +10,6 @@ from typing import Any, TypeVar
 from bluesky.protocols import HasName
 from bluesky.run_engine import call_in_bluesky_event_loop, in_bluesky_event_loop
 
-from ._protocol import Connectable
 from ._utils import DEFAULT_TIMEOUT, LazyMock, NotConnected, wait_for_connection
 
 
@@ -61,7 +60,7 @@ class DeviceConnector:
         await wait_for_connection(**coros)
 
 
-class Device(HasName, Connectable):
+class Device(HasName):
     """Common base class for all Ophyd Async Devices."""
 
     _name: str = ""
@@ -71,13 +70,16 @@ class Device(HasName, Connectable):
     _connect_task: asyncio.Task | None = None
     # The mock if we have connected in mock mode
     _mock: LazyMock | None = None
+    # The separator to use when making child names
+    _child_name_separator: str = "-"
 
     def __init__(
         self, name: str = "", connector: DeviceConnector | None = None
     ) -> None:
         self._connector = connector or DeviceConnector()
         self._connector.create_children_from_annotations(self)
-        self.set_name(name)
+        if name:
+            self.set_name(name)
 
     @property
     def name(self) -> str:
@@ -97,21 +99,30 @@ class Device(HasName, Connectable):
             getLogger("ophyd_async.devices"), {"ophyd_async_device_name": self.name}
         )
 
-    def set_name(self, name: str):
+    def set_name(self, name: str, *, child_name_separator: str | None = None) -> None:
         """Set ``self.name=name`` and each ``self.child.name=name+"-child"``.
 
         Parameters
         ----------
         name:
             New name to set
+        child_name_separator:
+            Use this as a separator instead of "-". Use "_" instead to make the same
+            names as the equivalent ophyd sync device.
         """
         self._name = name
+        if child_name_separator:
+            self._child_name_separator = child_name_separator
         # Ensure logger is recreated after a name change
         if "log" in self.__dict__:
             del self.log
-        for child_name, child in self.children():
-            child_name = f"{self.name}-{child_name.strip('_')}" if self.name else ""
-            child.set_name(child_name)
+        for attr_name, child in self.children():
+            child_name = (
+                f"{self.name}{self._child_name_separator}{attr_name}"
+                if self.name
+                else ""
+            )
+            child.set_name(child_name, child_name_separator=self._child_name_separator)
 
     def __setattr__(self, name: str, value: Any) -> None:
         # Bear in mind that this function is called *a lot*, so
@@ -147,6 +158,12 @@ class Device(HasName, Connectable):
         timeout:
             Time to wait before failing with a TimeoutError.
         """
+        if not hasattr(self, "_connector"):
+            msg = (
+                f"{self}: doesn't have attribute `_connector`,"
+                " did you call `super().__init__` in your `__init__` method?"
+            )
+            raise RuntimeError(msg)
         if mock:
             # Always connect in mock mode serially
             if isinstance(mock, LazyMock):
@@ -167,7 +184,9 @@ class Device(HasName, Connectable):
                 self._mock = None
                 coro = self._connector.connect_real(self, timeout, force_reconnect)
                 self._connect_task = asyncio.create_task(coro)
-            assert self._connect_task, "Connect task not created, this shouldn't happen"
+            if not self._connect_task:
+                msg = "Connect task not created, this shouldn't happen"
+                raise RuntimeError(msg)
             # Wait for it to complete
             await self._connect_task
 
@@ -191,7 +210,7 @@ class DeviceVector(MutableMapping[int, DeviceT], Device):
 
     In the below example, foos becomes a dictionary on the parent device
     at runtime, so parent.foos[2] returns a FooDevice. For example usage see
-    :class:`~ophyd_async.epics.demo.DynamicSensorGroup`
+    :class:`~ophyd_async.epics.sim.DynamicSensorGroup`
     """
 
     def __init__(
@@ -217,8 +236,12 @@ class DeviceVector(MutableMapping[int, DeviceT], Device):
     def __setitem__(self, key: int, value: DeviceT) -> None:
         # Check the types on entry to dict to make sure we can't accidentally
         # make a non-integer named child
-        assert isinstance(key, int), f"Expected int, got {key}"
-        assert isinstance(value, Device), f"Expected Device, got {value}"
+        if not isinstance(key, int):
+            msg = f"Expected int, got {key}"
+            raise TypeError(msg)
+        if not isinstance(value, Device):
+            msg = f"Expected Device, got {value}"
+            raise TypeError(msg)
         self._children[key] = value
         value.parent = self
 
@@ -239,90 +262,49 @@ class DeviceVector(MutableMapping[int, DeviceT], Device):
         return hash(id(self))
 
 
-class DeviceCollector:
-    """Collector of top level Device instances to be used as a context manager
-
-    Parameters
-    ----------
-    set_name:
-        If True, call ``device.set_name(variable_name)`` on all collected
-        Devices
-    connect:
-        If True, call ``device.connect(mock)`` in parallel on all
-        collected Devices
-    mock:
-        If True, connect Signals in simulation mode
-    timeout:
-        How long to wait for connect before logging an exception
-
-    Notes
-    -----
-    Example usage::
-
-        [async] with DeviceCollector():
-            t1x = motor.Motor("BLxxI-MO-TABLE-01:X")
-            t1y = motor.Motor("pva://BLxxI-MO-TABLE-01:Y")
-            # Names and connects devices here
-        assert t1x.comm.velocity.source
-        assert t1x.name == "t1x"
+class DeviceProcessor:
+    """Sync/Async Context Manager that finds all the Devices declared within it.
 
+    Used in `init_devices`
     """
 
-    def __init__(
-        self,
-        set_name=True,
-        connect=True,
-        mock=False,
-        timeout: float = 10.0,
-    ):
-        self._set_name = set_name
-        self._connect = connect
-        self._mock = mock
-        self._timeout = timeout
-        self._names_on_enter: set[str] = set()
-        self._objects_on_exit: dict[str, Any] = {}
-
-    def _caller_locals(self):
+    def __init__(self, process_devices: Callable[[dict[str, Device]], Awaitable[None]]):
+        self._process_devices = process_devices
+        self._locals_on_enter: dict[str, Any] = {}
+        self._locals_on_exit: dict[str, Any] = {}
+
+    def _caller_locals(self) -> dict[str, Any]:
         """Walk up until we find a stack frame that doesn't have us as self"""
         try:
             raise ValueError
         except ValueError:
             _, _, tb = sys.exc_info()
-            assert tb, "Can't get traceback, this shouldn't happen"
+            if not tb:
+                msg = "Can't get traceback, this shouldn't happen"
+                raise RuntimeError(msg)  # noqa: B904
             caller_frame = tb.tb_frame
             while caller_frame.f_locals.get("self", None) is self:
                 caller_frame = caller_frame.f_back
-                assert (
-                    caller_frame
-                ), "No previous frame to the one with self in it, this shouldn't happen"
-            return caller_frame.f_locals
+                if not caller_frame:
+                    msg = (
+                        "No previous frame to the one with self in it, "
+                        "this shouldn't happen"
+                    )
+                    raise RuntimeError(  # noqa: B904
+                        msg
+                    )
+            return caller_frame.f_locals.copy()
 
-    def __enter__(self) -> DeviceCollector:
+    def __enter__(self) -> DeviceProcessor:
         # Stash the names that were defined before we were called
-        self._names_on_enter = set(self._caller_locals())
+        self._locals_on_enter = self._caller_locals()
         return self
 
-    async def __aenter__(self) -> DeviceCollector:
+    async def __aenter__(self) -> DeviceProcessor:
         return self.__enter__()
 
-    async def _on_exit(self) -> None:
-        # Name and kick off connect for devices
-        connect_coroutines: dict[str, Coroutine] = {}
-        for name, obj in self._objects_on_exit.items():
-            if name not in self._names_on_enter and isinstance(obj, Device):
-                if self._set_name and not obj.name:
-                    obj.set_name(name)
-                if self._connect:
-                    connect_coroutines[name] = obj.connect(
-                        self._mock, timeout=self._timeout
-                    )
-
-        # Connect to all the devices
-        if connect_coroutines:
-            await wait_for_connection(**connect_coroutines)
-
     async def __aexit__(self, type, value, traceback):
-        self._objects_on_exit = self._caller_locals()
+        self._locals_on_exit = self._caller_locals()
         await self._on_exit()
 
     def __exit__(self, type_, value, traceback):
@@ -331,7 +313,7 @@ class DeviceCollector:
                 "Cannot use DeviceConnector inside a plan, instead use "
                 "`yield from ophyd_async.plan_stubs.ensure_connected(device)`"
             )
-        self._objects_on_exit = self._caller_locals()
+        self._locals_on_exit = self._caller_locals()
         try:
             fut = call_in_bluesky_event_loop(self._on_exit())
         except RuntimeError as e:
@@ -341,3 +323,62 @@ class DeviceCollector:
                 "user/explanations/event-loop-choice.html for more info."
             ) from e
         return fut
+
+    async def _on_exit(self) -> None:
+        # Find all the devices
+        devices = {
+            name: obj
+            for name, obj in self._locals_on_exit.items()
+            if isinstance(obj, Device) and self._locals_on_enter.get(name) is not obj
+        }
+        # Call the provided process function on them
+        await self._process_devices(devices)
+
+
+def init_devices(
+    set_name=True,
+    child_name_separator: str = "-",
+    connect=True,
+    mock=False,
+    timeout: float = 10.0,
+) -> DeviceProcessor:
+    """Auto initialise top level Device instances to be used as a context manager
+
+    Parameters
+    ----------
+    set_name:
+        If True, call ``device.set_name(variable_name)`` on all Devices
+        created within the context manager that have an empty ``name``
+    child_name_separator:
+        Use this as a separator if we call ``set_name``.
+    connect:
+        If True, call ``device.connect(mock, timeout)`` in parallel on all
+        Devices created within the context manager
+    mock:
+        If True, connect Signals in mock mode
+    timeout:
+        How long to wait for connect before logging an exception
+
+    Notes
+    -----
+    Example usage::
+
+        [async] with init_devices():
+            t1x = motor.Motor("BLxxI-MO-TABLE-01:X")
+            t1y = motor.Motor("pva://BLxxI-MO-TABLE-01:Y")
+            # Names and connects devices here
+        assert t1x.name == "t1x"
+    """
+
+    async def process_devices(devices: dict[str, Device]):
+        if set_name:
+            for name, device in devices.items():
+                if not device.name:
+                    device.set_name(name, child_name_separator=child_name_separator)
+        if connect:
+            coros = {
+                name: device.connect(mock, timeout) for name, device in devices.items()
+            }
+            await wait_for_connection(**coros)
+
+    return DeviceProcessor(process_devices)

ophyd_async/core/_device_filler.py

@@ -39,6 +39,13 @@ def _logical(name: UniqueName) -> LogicalName:
     return LogicalName(name.rstrip("_"))
 
 
+def _check_device_annotation(annotation: Any) -> DeviceAnnotation:
+    if not isinstance(annotation, DeviceAnnotation):
+        msg = f"Annotation {annotation} is not a DeviceAnnotation"
+        raise TypeError(msg)
+    return annotation
+
+
 @runtime_checkable
 class DeviceAnnotation(Protocol):
     @abstractmethod
@@ -150,8 +157,8 @@ class DeviceFiller(Generic[SignalBackendT, DeviceConnectorT]):
             yield backend, extras
             signal = child_type(backend)
             for anno in extras:
-                assert isinstance(anno, DeviceAnnotation), anno
-                anno(self._device, signal)
+                device_annotation = _check_device_annotation(annotation=anno)
+                device_annotation(self._device, signal)
             setattr(self._device, name, signal)
             dest = self._filled_backends if filled else self._unfilled_backends
             dest[_logical(name)] = (backend, child_type)
@@ -167,15 +174,17 @@ class DeviceFiller(Generic[SignalBackendT, DeviceConnectorT]):
             yield connector, extras
             device = child_type(connector=connector)
             for anno in extras:
-                assert isinstance(anno, DeviceAnnotation), anno
-                anno(self._device, device)
+                device_annotation = _check_device_annotation(annotation=anno)
+                device_annotation(self._device, device)
             setattr(self._device, name, device)
             dest = self._filled_connectors if filled else self._unfilled_connectors
             dest[_logical(name)] = connector
 
     def create_device_vector_entries_to_mock(self, num: int):
         for name, cls in self._vector_device_type.items():
-            assert cls, "Shouldn't happen"
+            if not cls:
+                msg = "Malformed device vector"
+                raise TypeError(msg)
             for i in range(1, num + 1):
                 if issubclass(cls, Signal):
                     self.fill_child_signal(name, cls, i)
@@ -254,9 +263,9 @@ class DeviceFiller(Generic[SignalBackendT, DeviceConnectorT]):
             # We need to add a new entry to a DeviceVector
             vector = self._ensure_device_vector(name)
             vector_device_type = self._vector_device_type[name] or device_type
-            assert issubclass(
-                vector_device_type, Device
-            ), f"{vector_device_type} is not a Device"
+            if not issubclass(vector_device_type, Device):
+                msg = f"{vector_device_type} is not a Device"
+                raise TypeError(msg)
             connector = self._device_connector_factory()
             vector[vector_index] = vector_device_type(connector=connector)
         elif child := getattr(self._device, name, None):

ophyd_async/core/_flyer.py

@@ -1,5 +1,5 @@
 from abc import ABC, abstractmethod
-from typing import Generic
+from typing import Any, Generic
 
 from bluesky.protocols import Flyable, Preparable, Stageable
 
@@ -10,7 +10,7 @@ from ._utils import T
 
 class FlyerController(ABC, Generic[T]):
     @abstractmethod
-    async def prepare(self, value: T):
+    async def prepare(self, value: T) -> Any:
         """Move to the start of the flyscan"""
 
     @abstractmethod

ophyd_async/core/_protocol.py

@@ -13,38 +13,10 @@ from typing import (
 from bluesky.protocols import HasName, Reading
 from event_model import DataKey
 
-from ._utils import DEFAULT_TIMEOUT
-
 if TYPE_CHECKING:
-    from unittest.mock import Mock
-
     from ._status import AsyncStatus
 
 
-@runtime_checkable
-class Connectable(Protocol):
-    @abstractmethod
-    async def connect(
-        self,
-        mock: bool | Mock = False,
-        timeout: float = DEFAULT_TIMEOUT,
-        force_reconnect: bool = False,
-    ):
-        """Connect self and all child Devices.
-
-        Contains a timeout that gets propagated to child.connect methods.
-
-        Parameters
-        ----------
-        mock:
-            If True then use ``MockSignalBackend`` for all Signals
-        timeout:
-            Time to wait before failing with a TimeoutError.
-        force_reconnect:
-            Reconnect even if previous connect was successful.
-        """
-
-
 @runtime_checkable
 class AsyncReadable(HasName, Protocol):
     @abstractmethod

ophyd_async/core/_readable.py

@@ -123,29 +123,31 @@ class StandardReadable(
             # 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
 
@@ -204,6 +206,11 @@ class StandardReadable(
             `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 +225,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,104 @@
+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]):
+    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.
+
+        For example::
+
+            settings1 = Settings(device, {device.sig1: 1, device.sig2: 2})
+            settings2 = Settings(device, {device.sig1: 10, device.sig3: 3})
+            settings = settings1 | settings2
+            assert dict(settings) == {
+                device.sig1: 10,
+                device.sig2: 2,
+                device.sig3: 3,
+            }
+        """
+        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.
+
+        Parameters
+        ----------
+        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)
+
+        For example::
+
+            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:
+    @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."""
+        ...