ophyd-async 0.9.0a1__py3-none-any.whl → 0.9.0a2__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.9.0a1'
+__version__ = version = '0.9.0a2'
 __version_tuple__ = version_tuple = (0, 9, 0)

ophyd_async/core/__init__.py

@@ -1,22 +1,13 @@
 from ._detector import (
     DetectorController,
+    DetectorControllerT,
     DetectorTrigger,
     DetectorWriter,
     StandardDetector,
     TriggerInfo,
 )
-from ._device import Device, DeviceCollector, DeviceConnector, DeviceVector
+from ._device import Device, DeviceConnector, DeviceVector, init_devices
 from ._device_filler import DeviceFiller
-from ._device_save_loader import (
-    all_at_once,
-    get_signal_values,
-    load_device,
-    load_from_yaml,
-    save_device,
-    save_to_yaml,
-    set_signal_values,
-    walk_rw_signals,
-)
 from ._flyer import FlyerController, StandardFlyer
 from ._hdf_dataset import HDFDataset, HDFFile
 from ._log import config_ophyd_async_logging
@@ -41,6 +32,7 @@ from ._readable import (
     StandardReadable,
     StandardReadableFormat,
 )
+from ._settings import Settings, SettingsProvider
 from ._signal import (
     Signal,
     SignalConnector,
@@ -55,9 +47,11 @@ from ._signal import (
     soft_signal_r_and_setter,
     soft_signal_rw,
     wait_for_value,
+    walk_rw_signals,
 )
 from ._signal_backend import (
     Array1D,
+    DTypeScalar_co,
     SignalBackend,
     SignalDatatype,
     SignalDatatypeT,
@@ -84,26 +78,20 @@ from ._utils import (
     in_micros,
     wait_for_connection,
 )
+from ._yaml_settings import YamlSettingsProvider
 
 __all__ = [
     "DetectorController",
+    "DetectorControllerT",
     "DetectorTrigger",
     "DetectorWriter",
     "StandardDetector",
     "TriggerInfo",
     "Device",
     "DeviceConnector",
-    "DeviceCollector",
+    "init_devices",
     "DeviceVector",
     "DeviceFiller",
-    "all_at_once",
-    "get_signal_values",
-    "load_device",
-    "load_from_yaml",
-    "save_device",
-    "save_to_yaml",
-    "set_signal_values",
-    "walk_rw_signals",
     "StandardFlyer",
     "FlyerController",
     "HDFDataset",
@@ -128,6 +116,8 @@ __all__ = [
     "HintedSignal",
     "StandardReadable",
     "StandardReadableFormat",
+    "Settings",
+    "SettingsProvider",
     "Signal",
     "SignalConnector",
     "SignalR",
@@ -141,7 +131,9 @@ __all__ = [
     "soft_signal_r_and_setter",
     "soft_signal_rw",
     "wait_for_value",
+    "walk_rw_signals",
     "Array1D",
+    "DTypeScalar_co",
     "SignalBackend",
     "make_datakey",
     "StrictEnum",
@@ -168,4 +160,5 @@ __all__ = [
     "in_micros",
     "wait_for_connection",
     "completed_status",
+    "YamlSettingsProvider",
 ]

ophyd_async/core/_detector.py

@@ -5,10 +5,15 @@ import time
 from abc import ABC, abstractmethod
 from collections.abc import AsyncGenerator, AsyncIterator, Callable, Iterator, Sequence
 from functools import cached_property
+from typing import (
+    Generic,
+    TypeVar,
+)
 
 from bluesky.protocols import (
     Collectable,
     Flyable,
+    Hints,
     Preparable,
     Reading,
     Stageable,
@@ -87,7 +92,7 @@ class DetectorController(ABC):
         """For a given exposure, how long should the time between exposures be"""
 
     @abstractmethod
-    async def prepare(self, trigger_info: TriggerInfo):
+    async def prepare(self, trigger_info: TriggerInfo) -> None:
         """
         Do all necessary steps to prepare the detector for triggers.
 
@@ -157,6 +162,23 @@ class DetectorWriter(ABC):
     async def close(self) -> None:
         """Close writer, blocks until I/O is complete"""
 
+    @property
+    def hints(self) -> Hints:
+        return {}
+
+
+# Add type var for controller so we can define
+# StandardDetector[KinetixController, ADWriter] for example
+DetectorControllerT = TypeVar("DetectorControllerT", bound=DetectorController)
+DetectorWriterT = TypeVar("DetectorWriterT", bound=DetectorWriter)
+
+
+def _ensure_trigger_info_exists(trigger_info: TriggerInfo | None) -> TriggerInfo:
+    # make absolute sure we realy have a valid TriggerInfo ... mostly for pylance
+    if trigger_info is None:
+        raise RuntimeError("Trigger info must be set before calling this method.")
+    return trigger_info
+
 
 class StandardDetector(
     Device,
@@ -168,6 +190,7 @@ class StandardDetector(
     Flyable,
     Collectable,
     WritesStreamAssets,
+    Generic[DetectorControllerT, DetectorWriterT],
 ):
     """
     Useful detector base class for step and fly scanning detectors.
@@ -176,8 +199,8 @@ class StandardDetector(
 
     def __init__(
         self,
-        controller: DetectorController,
-        writer: DetectorWriter,
+        controller: DetectorControllerT,
+        writer: DetectorWriterT,
         config_sigs: Sequence[SignalR] = (),
         name: str = "",
         connector: DeviceConnector | None = None,
@@ -211,19 +234,11 @@ class StandardDetector(
         self._initial_frame: int = 0
         super().__init__(name, connector=connector)
 
-    @property
-    def controller(self) -> DetectorController:
-        return self._controller
-
-    @property
-    def writer(self) -> DetectorWriter:
-        return self._writer
-
     @AsyncStatus.wrap
     async def stage(self) -> None:
         # Disarm the detector, stop file writing.
         await self._check_config_sigs()
-        await asyncio.gather(self.writer.close(), self.controller.disarm())
+        await asyncio.gather(self._writer.close(), self._controller.disarm())
         self._trigger_info = None
 
     async def _check_config_sigs(self):
@@ -244,7 +259,7 @@ class StandardDetector(
     @AsyncStatus.wrap
     async def unstage(self) -> None:
         # Stop data writing.
-        await asyncio.gather(self.writer.close(), self.controller.disarm())
+        await asyncio.gather(self._writer.close(), self._controller.disarm())
 
     async def read_configuration(self) -> dict[str, Reading]:
         return await merge_gathered_dicts(sig.read() for sig in self._config_sigs)
@@ -271,15 +286,19 @@ class StandardDetector(
                     frame_timeout=None,
                 )
             )
-        assert self._trigger_info
-        assert self._trigger_info.trigger is DetectorTrigger.INTERNAL
+
+        self._trigger_info = _ensure_trigger_info_exists(self._trigger_info)
+        if self._trigger_info.trigger is not DetectorTrigger.INTERNAL:
+            msg = "The trigger method can only be called with INTERNAL triggering"
+            raise ValueError(msg)
+
         # Arm the detector and wait for it to finish.
-        indices_written = await self.writer.get_indices_written()
-        await self.controller.arm()
-        await self.controller.wait_for_idle()
+        indices_written = await self._writer.get_indices_written()
+        await self._controller.arm()
+        await self._controller.wait_for_idle()
         end_observation = indices_written + 1
 
-        async for index in self.writer.observe_indices_written(
+        async for index in self._writer.observe_indices_written(
             DEFAULT_TIMEOUT
             + (self._trigger_info.livetime or 0)
             + (self._trigger_info.deadtime or 0)
@@ -303,28 +322,29 @@ class StandardDetector(
         Args:
             value: TriggerInfo describing how to trigger the detector
         """
-        if value.trigger != DetectorTrigger.INTERNAL:
-            assert (
-                value.deadtime
-            ), "Deadtime must be supplied when in externally triggered mode"
-        if value.deadtime:
-            required = self.controller.get_deadtime(value.livetime)
-            assert required <= value.deadtime, (
-                f"Detector {self.controller} needs at least {required}s deadtime, "
-                f"but trigger logic provides only {value.deadtime}s"
+        if value.trigger != DetectorTrigger.INTERNAL and not value.deadtime:
+            msg = "Deadtime must be supplied when in externally triggered mode"
+            raise ValueError(msg)
+        required_deadtime = self._controller.get_deadtime(value.livetime)
+        if value.deadtime and required_deadtime > value.deadtime:
+            msg = (
+                f"Detector {self._controller} needs at least {required_deadtime}s "
+                f"deadtime, but trigger logic provides only {value.deadtime}s"
             )
+            raise ValueError(msg)
+
         self._trigger_info = value
         self._number_of_triggers_iter = iter(
             self._trigger_info.number_of_triggers
             if isinstance(self._trigger_info.number_of_triggers, list)
             else [self._trigger_info.number_of_triggers]
         )
-        self._initial_frame = await self.writer.get_indices_written()
+        self._initial_frame = await self._writer.get_indices_written()
         self._describe, _ = await asyncio.gather(
-            self.writer.open(value.multiplier), self.controller.prepare(value)
+            self._writer.open(value.multiplier), self._controller.prepare(value)
         )
         if value.trigger != DetectorTrigger.INTERNAL:
-            await self.controller.arm()
+            await self._controller.arm()
             self._fly_start = time.monotonic()
 
     @AsyncStatus.wrap
@@ -342,8 +362,8 @@ class StandardDetector(
 
     @WatchableAsyncStatus.wrap
     async def complete(self):
-        assert self._trigger_info
-        indices_written = self.writer.observe_indices_written(
+        self._trigger_info = _ensure_trigger_info_exists(self._trigger_info)
+        indices_written = self._writer.observe_indices_written(
             self._trigger_info.frame_timeout
             or (
                 DEFAULT_TIMEOUT
@@ -372,7 +392,7 @@ class StandardDetector(
                 self._completable_frames = 0
                 self._frames_to_complete = 0
                 self._number_of_triggers_iter = None
-                await self.controller.wait_for_idle()
+                await self._controller.wait_for_idle()
 
     async def describe_collect(self) -> dict[str, DataKey]:
         return self._describe
@@ -384,9 +404,13 @@ class StandardDetector(
         # The index is optional, and provided for fly scans, however this needs to be
         # retrieved for step scans.
         if index is None:
-            index = await self.writer.get_indices_written()
-        async for doc in self.writer.collect_stream_docs(index):
+            index = await self._writer.get_indices_written()
+        async for doc in self._writer.collect_stream_docs(index):
             yield doc
 
     async def get_index(self) -> int:
-        return await self.writer.get_indices_written()
+        return await self._writer.get_indices_written()
+
+    @property
+    def hints(self) -> Hints:
+        return self._writer.hints

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
@@ -158,10 +158,12 @@ class Device(HasName):
         timeout:
             Time to wait before failing with a TimeoutError.
         """
-        assert hasattr(self, "_connector"), (
-            f"{self}: doesn't have attribute `_connector`,"
-            " did you call `super().__init__` in your `__init__` method?"
-        )
+        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):
@@ -182,7 +184,9 @@ class Device(HasName):
                 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
 
@@ -206,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__(
@@ -232,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
 
@@ -254,94 +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
-    child_name_separator:
-        Use this as a separator if we call ``set_name``.
-    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,
-        child_name_separator: str = "-",
-        connect=True,
-        mock=False,
-        timeout: float = 10.0,
-    ):
-        self._set_name = set_name
-        self._child_name_separator = child_name_separator
-        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, child_name_separator=self._child_name_separator)
-                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):
@@ -350,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:
@@ -360,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