ophyd-async 0.8.0a6__py3-none-any.whl → 0.9.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.8.0a6'
-__version_tuple__ = version_tuple = (0, 8, 0)
+__version__ = version = '0.9.0'
+__version_tuple__ = version_tuple = (0, 9, 0)

ophyd_async/core/__init__.py

@@ -1,36 +1,17 @@
 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
 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,
-    set_mock_put_proceeds,
-    set_mock_value,
-    set_mock_values,
-)
 from ._protocol import AsyncConfigurable, AsyncReadable, AsyncStageable
 from ._providers import (
     AutoIncrementFilenameProvider,
@@ -51,16 +32,14 @@ from ._readable import (
     StandardReadable,
     StandardReadableFormat,
 )
+from ._settings import Settings, SettingsProvider
 from ._signal import (
     Signal,
+    SignalConnector,
     SignalR,
     SignalRW,
     SignalW,
     SignalX,
-    assert_configuration,
-    assert_emitted,
-    assert_reading,
-    assert_value,
     observe_signals_value,
     observe_value,
     set_and_wait_for_other_value,
@@ -68,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,
@@ -97,40 +78,26 @@ 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",
     "HDFFile",
     "config_ophyd_async_logging",
     "MockSignalBackend",
-    "callback_on_mock_put",
-    "get_mock",
-    "get_mock_put",
-    "mock_puts_blocked",
-    "reset_mock_put_calls",
-    "set_mock_put_proceeds",
-    "set_mock_value",
-    "set_mock_values",
     "AsyncConfigurable",
     "AsyncReadable",
     "AsyncStageable",
@@ -149,15 +116,14 @@ __all__ = [
     "HintedSignal",
     "StandardReadable",
     "StandardReadableFormat",
+    "Settings",
+    "SettingsProvider",
     "Signal",
+    "SignalConnector",
     "SignalR",
     "SignalRW",
     "SignalW",
     "SignalX",
-    "assert_configuration",
-    "assert_emitted",
-    "assert_reading",
-    "assert_value",
     "observe_value",
     "observe_signals_value",
     "set_and_wait_for_value",
@@ -165,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",
@@ -192,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,
@@ -30,13 +35,13 @@ class DetectorTrigger(StrictEnum):
     """Type of mechanism for triggering a detector to take frames"""
 
     #: Detector generates internal trigger for given rate
-    internal = "internal"
+    INTERNAL = "internal"
     #: Expect a series of arbitrary length trigger signals
-    edge_trigger = "edge_trigger"
+    EDGE_TRIGGER = "edge_trigger"
     #: Expect a series of constant width external gate signals
-    constant_gate = "constant_gate"
+    CONSTANT_GATE = "constant_gate"
     #: Expect a series of variable width external gate signals
-    variable_gate = "variable_gate"
+    VARIABLE_GATE = "variable_gate"
 
 
 class TriggerInfo(BaseModel):
@@ -53,7 +58,7 @@ class TriggerInfo(BaseModel):
     #:     - 3 times for final flat field images
     number_of_triggers: NonNegativeInt | list[NonNegativeInt]
     #: Sort of triggers that will be sent
-    trigger: DetectorTrigger = Field(default=DetectorTrigger.internal)
+    trigger: DetectorTrigger = Field(default=DetectorTrigger.INTERNAL)
     #: What is the minimum deadtime between triggers
     deadtime: float | None = Field(default=None, ge=0)
     #: What is the maximum high time of the triggers
@@ -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)
@@ -265,21 +280,25 @@ class StandardDetector(
             await self.prepare(
                 TriggerInfo(
                     number_of_triggers=1,
-                    trigger=DetectorTrigger.internal,
+                    trigger=DetectorTrigger.INTERNAL,
                     deadtime=None,
                     livetime=None,
                     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()
+        if value.trigger != DetectorTrigger.INTERNAL:
+            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