ophyd-async 0.7.0a1__py3-none-any.whl → 0.8.0a3__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.0a1'
-__version_tuple__ = version_tuple = (0, 7, 0)
+__version__ = version = '0.8.0a3'
+__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,
@@ -62,9 +69,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 +82,17 @@ from ._utils import (
     CALCULATE_TIMEOUT,
     DEFAULT_TIMEOUT,
     CalculatableTimeout,
+    Callback,
     NotConnected,
-    ReadingValueCallback,
+    Reference,
+    StrictEnum,
+    SubsetEnum,
     T,
     WatcherUpdate,
     get_dtype,
+    get_enum_cls,
     get_unique,
     in_micros,
-    is_pydantic_model,
     wait_for_connection,
 )
 
@@ -91,8 +103,10 @@ __all__ = [
     "StandardDetector",
     "TriggerInfo",
     "Device",
+    "DeviceConnector",
     "DeviceCollector",
     "DeviceVector",
+    "DeviceFiller",
     "all_at_once",
     "get_signal_values",
     "load_device",
@@ -108,6 +122,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 +146,7 @@ __all__ = [
     "ConfigSignal",
     "HintedSignal",
     "StandardReadable",
+    "StandardReadableFormat",
     "Signal",
     "SignalR",
     "SignalRW",
@@ -146,25 +162,30 @@ __all__ = [
     "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",
     "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,81 @@
-"""Base device"""
+from __future__ import annotations
 
 import asyncio
 import sys
-from collections.abc import Coroutine, Generator, Iterator
-from functools import cached_property
+from collections.abc import Coroutine, Iterator, Mapping, MutableMapping
 from logging import LoggerAdapter, getLogger
-from typing import (
-    Any,
-    Optional,
-    TypeVar,
-)
+from typing import Any, TypeVar
+from unittest.mock import Mock
 
 from bluesky.protocols import HasName
-from bluesky.run_engine import call_in_bluesky_event_loop
+from bluesky.run_engine import call_in_bluesky_event_loop, in_bluesky_event_loop
 
+from ._protocol import Connectable
 from ._utils import DEFAULT_TIMEOUT, NotConnected, wait_for_connection
 
+_device_mocks: dict[Device, Mock] = {}
 
-class Device(HasName):
-    """Common base class for all Ophyd Async Devices.
 
-    By default, names and connects all Device children.
-    """
+class DeviceConnector:
+    """Defines how a `Device` should be connected and type hints processed."""
+
+    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(
+        self,
+        device: Device,
+        mock: bool | Mock,
+        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.
+        """
+        coros = {}
+        for name, child_device in device.children():
+            child_mock = getattr(mock, name) if mock else mock  # Mock() or False
+            coros[name] = child_device.connect(
+                mock=child_mock, timeout=timeout, force_reconnect=force_reconnect
+            )
+        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
+    # If not None, then this is the mock arg of the previous connect
+    # to let us know if we can reuse an existing connection
+    _connect_mock_arg: bool | 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
@@ -41,13 +83,7 @@ class Device(HasName):
         """Return the name of the Device"""
         return self._name
 
-    @cached_property
-    def log(self):
-        return LoggerAdapter(
-            getLogger("ophyd_async.devices"), {"ophyd_async_device_name": self.name}
-        )
-
-    def children(self) -> Iterator[tuple[str, "Device"]]:
+    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
@@ -60,23 +96,32 @@ 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 self.log is recreated after a name change
+        self.log = LoggerAdapter(
+            getLogger("ophyd_async.devices"), {"ophyd_async_device_name": self.name}
+        )
+        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:
+        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}"
+                )
+        elif isinstance(value, Device):
+            value.parent = self
+        return super().__setattr__(name, value)
 
     async def connect(
         self,
-        mock: bool = False,
+        mock: bool | Mock = 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 +133,32 @@ 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."
-            )
-        self._previous_connect_was_mock = mock
-
-        # 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()
+        uses_mock = bool(mock)
+        can_use_previous_connect = (
+            uses_mock is self._connect_mock_arg
+            and self._connect_task
+            and not (self._connect_task.done() and self._connect_task.exception())
         )
+        if mock is True:
+            mock = Mock()  # create a new Mock if one not provided
         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))
+            self._connect_mock_arg = uses_mock
+            if self._connect_mock_arg:
+                _device_mocks[self] = mock
+            coro = self._connector.connect(
+                device=self, mock=mock, timeout=timeout, force_reconnect=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
 
 
-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 +167,48 @@ 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(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 +269,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:
@@ -224,6 +298,11 @@ class DeviceCollector:
         await self._on_exit()
 
     def __exit__(self, type_, value, traceback):
+        if in_bluesky_event_loop():
+            raise RuntimeError(
+                "Cannot use DeviceConnector inside a plan, instead use "
+                "`yield from ophyd_async.plan_stubs.ensure_connected(device)`"
+            )
         self._objects_on_exit = self._caller_locals()
         try:
             fut = call_in_bluesky_event_loop(self._on_exit())