ophyd-async 0.7.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

ophyd_async/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.7.0'
-__version_tuple__ = version_tuple = (0, 7, 0)
+__version__ = version = '0.8.0'
+__version_tuple__ = version_tuple = (0, 8, 0)

ophyd_async/core/__init__.py

@@ -5,7 +5,8 @@ from ._detector import (
     StandardDetector,
     TriggerInfo,
 )
-from ._device import Device, DeviceCollector, DeviceVector
+from ._device import Device, DeviceCollector, DeviceConnector, DeviceVector
+from ._device_filler import DeviceFiller
 from ._device_save_loader import (
     all_at_once,
     get_signal_values,
@@ -22,6 +23,7 @@ from ._log import config_ophyd_async_logging
 from ._mock_signal_backend import MockSignalBackend
 from ._mock_signal_utils import (
     callback_on_mock_put,
+    get_mock,
     get_mock_put,
     mock_puts_blocked,
     reset_mock_put_calls,
@@ -43,7 +45,12 @@ from ._providers import (
     UUIDFilenameProvider,
     YMDPathProvider,
 )
-from ._readable import ConfigSignal, HintedSignal, StandardReadable
+from ._readable import (
+    ConfigSignal,
+    HintedSignal,
+    StandardReadable,
+    StandardReadableFormat,
+)
 from ._signal import (
     Signal,
     SignalR,
@@ -54,6 +61,7 @@ from ._signal import (
     assert_emitted,
     assert_reading,
     assert_value,
+    observe_signals_value,
     observe_value,
     set_and_wait_for_other_value,
     set_and_wait_for_value,
@@ -62,9 +70,11 @@ from ._signal import (
     wait_for_value,
 )
 from ._signal_backend import (
-    RuntimeSubsetEnum,
+    Array1D,
     SignalBackend,
-    SubsetEnum,
+    SignalDatatype,
+    SignalDatatypeT,
+    make_datakey,
 )
 from ._soft_signal_backend import SignalMetadata, SoftSignalBackend
 from ._status import AsyncStatus, WatchableAsyncStatus, completed_status
@@ -73,14 +83,18 @@ from ._utils import (
     CALCULATE_TIMEOUT,
     DEFAULT_TIMEOUT,
     CalculatableTimeout,
+    Callback,
+    LazyMock,
     NotConnected,
-    ReadingValueCallback,
+    Reference,
+    StrictEnum,
+    SubsetEnum,
     T,
     WatcherUpdate,
     get_dtype,
+    get_enum_cls,
     get_unique,
     in_micros,
-    is_pydantic_model,
     wait_for_connection,
 )
 
@@ -91,8 +105,10 @@ __all__ = [
     "StandardDetector",
     "TriggerInfo",
     "Device",
+    "DeviceConnector",
     "DeviceCollector",
     "DeviceVector",
+    "DeviceFiller",
     "all_at_once",
     "get_signal_values",
     "load_device",
@@ -108,6 +124,7 @@ __all__ = [
     "config_ophyd_async_logging",
     "MockSignalBackend",
     "callback_on_mock_put",
+    "get_mock",
     "get_mock_put",
     "mock_puts_blocked",
     "reset_mock_put_calls",
@@ -131,6 +148,7 @@ __all__ = [
     "ConfigSignal",
     "HintedSignal",
     "StandardReadable",
+    "StandardReadableFormat",
     "Signal",
     "SignalR",
     "SignalRW",
@@ -141,30 +159,37 @@ __all__ = [
     "assert_reading",
     "assert_value",
     "observe_value",
+    "observe_signals_value",
     "set_and_wait_for_value",
     "set_and_wait_for_other_value",
     "soft_signal_r_and_setter",
     "soft_signal_rw",
     "wait_for_value",
-    "RuntimeSubsetEnum",
+    "Array1D",
     "SignalBackend",
+    "make_datakey",
+    "StrictEnum",
     "SubsetEnum",
+    "SignalDatatype",
+    "SignalDatatypeT",
     "SignalMetadata",
     "SoftSignalBackend",
     "AsyncStatus",
     "WatchableAsyncStatus",
     "DEFAULT_TIMEOUT",
     "CalculatableTimeout",
+    "Callback",
+    "LazyMock",
     "CALCULATE_TIMEOUT",
     "NotConnected",
-    "ReadingValueCallback",
+    "Reference",
     "Table",
     "T",
     "WatcherUpdate",
     "get_dtype",
+    "get_enum_cls",
     "get_unique",
     "in_micros",
-    "is_pydantic_model",
     "wait_for_connection",
     "completed_status",
 ]

ophyd_async/core/_detector.py

@@ -4,11 +4,7 @@ import asyncio
 import time
 from abc import ABC, abstractmethod
 from collections.abc import AsyncGenerator, AsyncIterator, Callable, Iterator, Sequence
-from enum import Enum
 from functools import cached_property
-from typing import (
-    Generic,
-)
 
 from bluesky.protocols import (
     Collectable,
@@ -23,14 +19,14 @@ from bluesky.protocols import (
 from event_model import DataKey
 from pydantic import BaseModel, Field, NonNegativeInt, computed_field
 
-from ._device import Device
+from ._device import Device, DeviceConnector
 from ._protocol import AsyncConfigurable, AsyncReadable
 from ._signal import SignalR
 from ._status import AsyncStatus, WatchableAsyncStatus
-from ._utils import DEFAULT_TIMEOUT, T, WatcherUpdate, merge_gathered_dicts
+from ._utils import DEFAULT_TIMEOUT, StrictEnum, WatcherUpdate, merge_gathered_dicts
 
 
-class DetectorTrigger(str, Enum):
+class DetectorTrigger(StrictEnum):
     """Type of mechanism for triggering a detector to take frames"""
 
     #: Detector generates internal trigger for given rate
@@ -172,7 +168,6 @@ class StandardDetector(
     Flyable,
     Collectable,
     WritesStreamAssets,
-    Generic[T],
 ):
     """
     Useful detector base class for step and fly scanning detectors.
@@ -185,6 +180,7 @@ class StandardDetector(
         writer: DetectorWriter,
         config_sigs: Sequence[SignalR] = (),
         name: str = "",
+        connector: DeviceConnector | None = None,
     ) -> None:
         """
         Constructor
@@ -213,8 +209,7 @@ class StandardDetector(
         self._completable_frames: int = 0
         self._number_of_triggers_iter: Iterator[int] | None = None
         self._initial_frame: int = 0
-
-        super().__init__(name)
+        super().__init__(name, connector=connector)
 
     @property
     def controller(self) -> DetectorController:

ophyd_async/core/_device.py

@@ -1,39 +1,82 @@
-"""Base device"""
+from __future__ import annotations
 
 import asyncio
 import sys
-from collections.abc import Coroutine, Generator, Iterator
+from collections.abc import Coroutine, Iterator, Mapping, MutableMapping
 from functools import cached_property
 from logging import LoggerAdapter, getLogger
-from typing import (
-    Any,
-    Optional,
-    TypeVar,
-)
+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 ._utils import DEFAULT_TIMEOUT, NotConnected, wait_for_connection
+from ._protocol import Connectable
+from ._utils import DEFAULT_TIMEOUT, LazyMock, NotConnected, wait_for_connection
 
 
-class Device(HasName):
-    """Common base class for all Ophyd Async Devices.
+class DeviceConnector:
+    """Defines how a `Device` should be connected and type hints processed."""
 
-    By default, names and connects all Device children.
-    """
+    def create_children_from_annotations(self, device: Device):
+        """Used when children can be created from introspecting the hardware.
+
+        Some control systems allow introspection of a device to determine what
+        children it has. To allow this to work nicely with typing we add these
+        hints to the Device like so::
+
+            my_signal: SignalRW[int]
+            my_device: MyDevice
+
+        This method will be run during ``Device.__init__``, and is responsible
+        for turning all of those type hints into real Signal and Device instances.
+
+        Subsequent runs of this function should do nothing, to allow it to be
+        called early in Devices that need to pass references to their children
+        during ``__init__``.
+        """
+
+    async def connect_mock(self, device: Device, mock: LazyMock):
+        # Connect serially, no errors to gather up as in mock mode
+        exceptions: dict[str, Exception] = {}
+        for name, child_device in device.children():
+            try:
+                await child_device.connect(mock=mock.child(name))
+            except Exception as e:
+                exceptions[name] = e
+        if exceptions:
+            raise NotConnected.with_other_exceptions_logged(exceptions)
+
+    async def connect_real(self, device: Device, timeout: float, force_reconnect: bool):
+        """Used during ``Device.connect``.
+
+        This is called when a previous connect has not been done, or has been
+        done in a different mock more. It should connect the Device and all its
+        children.
+        """
+        # Connect in parallel, gathering up NotConnected errors
+        coros = {
+            name: child_device.connect(timeout=timeout, force_reconnect=force_reconnect)
+            for name, child_device in device.children()
+        }
+        await wait_for_connection(**coros)
+
+
+class Device(HasName, Connectable):
+    """Common base class for all Ophyd Async Devices."""
 
     _name: str = ""
     #: The parent Device if it exists
-    parent: Optional["Device"] = None
+    parent: Device | None = None
     # None if connect hasn't started, a Task if it has
     _connect_task: asyncio.Task | None = None
+    # The mock if we have connected in mock mode
+    _mock: LazyMock | None = None
 
-    # Used to check if the previous connect was mocked,
-    # if the next mock value differs then we fail
-    _previous_connect_was_mock = None
-
-    def __init__(self, name: str = "") -> None:
+    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)
 
     @property
@@ -42,16 +85,18 @@ class Device(HasName):
         return self._name
 
     @cached_property
-    def log(self):
+    def _child_devices(self) -> dict[str, Device]:
+        return {}
+
+    def children(self) -> Iterator[tuple[str, Device]]:
+        yield from self._child_devices.items()
+
+    @cached_property
+    def log(self) -> LoggerAdapter:
         return LoggerAdapter(
             getLogger("ophyd_async.devices"), {"ophyd_async_device_name": self.name}
         )
 
-    def children(self) -> Iterator[tuple[str, "Device"]]:
-        for attr_name, attr in self.__dict__.items():
-            if attr_name != "parent" and isinstance(attr, Device):
-                yield attr_name, attr
-
     def set_name(self, name: str):
         """Set ``self.name=name`` and each ``self.child.name=name+"-child"``.
 
@@ -60,23 +105,37 @@ class Device(HasName):
         name:
             New name to set
         """
-
-        # Ensure self.log is recreated after a name change
-        if hasattr(self, "log"):
-            del self.log
-
         self._name = name
-        for attr_name, child in self.children():
-            child_name = f"{name}-{attr_name.rstrip('_')}" if name else ""
+        # 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)
-            child.parent = self
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        # Bear in mind that this function is called *a lot*, so
+        # we need to make sure nothing expensive happens in it...
+        if name == "parent":
+            if self.parent not in (value, None):
+                raise TypeError(
+                    f"Cannot set the parent of {self} to be {value}: "
+                    f"it is already a child of {self.parent}"
+                )
+        # ...hence not doing an isinstance check for attributes we
+        # know not to be Devices
+        elif name not in _not_device_attrs and isinstance(value, Device):
+            value.parent = self
+            self._child_devices[name] = value
+        # ...and avoiding the super call as we know it resolves to `object`
+        return object.__setattr__(self, name, value)
 
     async def connect(
         self,
-        mock: bool = False,
+        mock: bool | LazyMock = False,
         timeout: float = DEFAULT_TIMEOUT,
         force_reconnect: bool = False,
-    ):
+    ) -> None:
         """Connect self and all child Devices.
 
         Contains a timeout that gets propagated to child.connect methods.
@@ -88,41 +147,45 @@ class Device(HasName):
         timeout:
             Time to wait before failing with a TimeoutError.
         """
-
-        if (
-            self._previous_connect_was_mock is not None
-            and self._previous_connect_was_mock != mock
-        ):
-            raise RuntimeError(
-                f"`connect(mock={mock})` called on a `Device` where the previous "
-                f"connect was `mock={self._previous_connect_was_mock}`. Changing mock "
-                "value between connects is not permitted."
+        if mock:
+            # Always connect in mock mode serially
+            if isinstance(mock, LazyMock):
+                # Use the provided mock
+                self._mock = mock
+            elif not self._mock:
+                # Make one
+                self._mock = LazyMock()
+            await self._connector.connect_mock(self, self._mock)
+        else:
+            # Try to cache the connect in real mode
+            can_use_previous_connect = (
+                self._mock is None
+                and self._connect_task
+                and not (self._connect_task.done() and self._connect_task.exception())
             )
-        self._previous_connect_was_mock = mock
+            if force_reconnect or not can_use_previous_connect:
+                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"
+            # Wait for it to complete
+            await self._connect_task
 
-        # If previous connect with same args has started and not errored, can use it
-        can_use_previous_connect = self._connect_task and not (
-            self._connect_task.done() and self._connect_task.exception()
-        )
-        if force_reconnect or not can_use_previous_connect:
-            # Kick off a connection
-            coros = {
-                name: child_device.connect(
-                    mock, timeout=timeout, force_reconnect=force_reconnect
-                )
-                for name, child_device in self.children()
-            }
-            self._connect_task = asyncio.create_task(wait_for_connection(**coros))
 
-        assert self._connect_task, "Connect task not created, this shouldn't happen"
-        # Wait for it to complete
-        await self._connect_task
+_not_device_attrs = {
+    "_name",
+    "_children",
+    "_connector",
+    "_timeout",
+    "_mock",
+    "_connect_task",
+}
 
 
-VT = TypeVar("VT", bound=Device)
+DeviceT = TypeVar("DeviceT", bound=Device)
 
 
-class DeviceVector(dict[int, VT], Device):
+class DeviceVector(MutableMapping[int, DeviceT], Device):
     """
     Defines device components with indices.
 
@@ -131,10 +194,49 @@ class DeviceVector(dict[int, VT], Device):
     :class:`~ophyd_async.epics.demo.DynamicSensorGroup`
     """
 
-    def children(self) -> Generator[tuple[str, Device], None, None]:
-        for attr_name, attr in self.items():
-            if isinstance(attr, Device):
-                yield str(attr_name), attr
+    def __init__(
+        self,
+        children: Mapping[int, DeviceT],
+        name: str = "",
+    ) -> None:
+        self._children: dict[int, DeviceT] = {}
+        self.update(children)
+        super().__init__(name=name)
+
+    def __setattr__(self, name: str, child: Any) -> None:
+        if name != "parent" and isinstance(child, Device):
+            raise AttributeError(
+                "DeviceVector can only have integer named children, "
+                "set via device_vector[i] = child"
+            )
+        super().__setattr__(name, child)
+
+    def __getitem__(self, key: int) -> DeviceT:
+        return self._children[key]
+
+    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}"
+        self._children[key] = value
+        value.parent = self
+
+    def __delitem__(self, key: int) -> None:
+        del self._children[key]
+
+    def __iter__(self) -> Iterator[int]:
+        yield from self._children
+
+    def __len__(self) -> int:
+        return len(self._children)
+
+    def children(self) -> Iterator[tuple[str, Device]]:
+        for key, child in self._children.items():
+            yield str(key), child
+
+    def __hash__(self):  # to allow DeviceVector to be used as dict keys and in sets
+        return hash(id(self))
 
 
 class DeviceCollector:
@@ -195,12 +297,12 @@ class DeviceCollector:
                 ), "No previous frame to the one with self in it, this shouldn't happen"
             return caller_frame.f_locals
 
-    def __enter__(self) -> "DeviceCollector":
+    def __enter__(self) -> DeviceCollector:
         # Stash the names that were defined before we were called
         self._names_on_enter = set(self._caller_locals())
         return self
 
-    async def __aenter__(self) -> "DeviceCollector":
+    async def __aenter__(self) -> DeviceCollector:
         return self.__enter__()
 
     async def _on_exit(self) -> None: