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

ophyd_async/core/_signal.py

@@ -2,7 +2,8 @@ from __future__ import annotations
 
 import asyncio
 import functools
-from collections.abc import AsyncGenerator, Awaitable, Callable, Mapping
+import time
+from collections.abc import AsyncGenerator, Awaitable, Callable
 from typing import Any, Generic, cast
 
 from bluesky.protocols import (
@@ -17,7 +18,6 @@ from event_model import DataKey
 from ._device import Device, DeviceConnector
 from ._mock_signal_backend import MockSignalBackend
 from ._protocol import (
-    AsyncConfigurable,
     AsyncReadable,
     AsyncStageable,
     Reading,
@@ -97,32 +97,37 @@ class Signal(Device, Generic[SignalDatatypeT]):
 
 
 class _SignalCache(Generic[SignalDatatypeT]):
-    def __init__(self, backend: SignalBackend[SignalDatatypeT], signal: Signal):
-        self._signal = signal
+    def __init__(self, backend: SignalBackend[SignalDatatypeT], signal: Signal) -> None:
+        self._signal: Signal[Any] = signal
         self._staged = False
         self._listeners: dict[Callback, bool] = {}
         self._valid = asyncio.Event()
         self._reading: Reading[SignalDatatypeT] | None = None
-        self.backend = backend
+        self.backend: SignalBackend[SignalDatatypeT] = backend
         signal.log.debug(f"Making subscription on source {signal.source}")
         backend.set_callback(self._callback)
 
-    def close(self):
+    def close(self) -> None:
         self.backend.set_callback(None)
         self._signal.log.debug(f"Closing subscription on source {self._signal.source}")
 
+    def _ensure_reading(self) -> Reading[SignalDatatypeT]:
+        if not self._reading:
+            msg = "Monitor not working"
+            raise RuntimeError(msg)
+        return self._reading
+
     async def get_reading(self) -> Reading[SignalDatatypeT]:
         await self._valid.wait()
-        assert self._reading is not None, "Monitor not working"
-        return self._reading
+        return self._ensure_reading()
 
     async def get_value(self) -> SignalDatatypeT:
-        reading = await self.get_reading()
+        reading: Reading[SignalDatatypeT] = await self.get_reading()
         return reading["value"]
 
-    def _callback(self, reading: Reading[SignalDatatypeT]):
+    def _callback(self, reading: Reading[SignalDatatypeT]) -> None:
         self._signal.log.debug(
-            f"Updated subscription: reading of source {self._signal.source} changed"
+            f"Updated subscription: reading of source {self._signal.source} changed "
             f"from {self._reading} to {reading}"
         )
         self._reading = reading
@@ -134,12 +139,10 @@ class _SignalCache(Generic[SignalDatatypeT]):
         self,
         function: Callback[dict[str, Reading[SignalDatatypeT]] | SignalDatatypeT],
         want_value: bool,
-    ):
-        assert self._reading, "Monitor not working"
-        if want_value:
-            function(self._reading["value"])
-        else:
-            function({self._signal.name: self._reading})
+    ) -> None:
+        function(self._ensure_reading()["value"]) if want_value else function(
+            {self._signal.name: self._ensure_reading()}
+        )
 
     def subscribe(self, function: Callback, want_value: bool) -> None:
         self._listeners[function] = want_value
@@ -150,7 +153,7 @@ class _SignalCache(Generic[SignalDatatypeT]):
         self._listeners.pop(function)
         return self._staged or bool(self._listeners)
 
-    def set_staged(self, staged: bool):
+    def set_staged(self, staged: bool) -> bool:
         self._staged = staged
         return self._staged or bool(self._listeners)
 
@@ -167,7 +170,10 @@ class SignalR(Signal[SignalDatatypeT], AsyncReadable, AsyncStageable, Subscribab
         if cached is None:
             cached = self._cache is not None
         if cached:
-            assert self._cache, f"{self.source} not being monitored"
+            if not self._cache:
+                msg = f"{self.source} not being monitored"
+                raise RuntimeError(msg)
+            # assert self._cache, f"{self.source} not being monitored"
             return self._cache
         else:
             return self._connector.backend
@@ -301,130 +307,11 @@ def soft_signal_r_and_setter(
     return (signal, backend.set_value)
 
 
-def _generate_assert_error_msg(name: str, expected_result, actual_result) -> str:
-    WARNING = "\033[93m"
-    FAIL = "\033[91m"
-    ENDC = "\033[0m"
-    return (
-        f"Expected {WARNING}{name}{ENDC} to produce"
-        + f"\n{FAIL}{expected_result}{ENDC}"
-        + f"\nbut actually got \n{FAIL}{actual_result}{ENDC}"
-    )
-
-
-async def assert_value(signal: SignalR[SignalDatatypeT], value: Any) -> None:
-    """Assert a signal's value and compare it an expected signal.
-
-    Parameters
-    ----------
-    signal:
-        signal with get_value.
-    value:
-        The expected value from the signal.
-
-    Notes
-    -----
-    Example usage::
-        await assert_value(signal, value)
-
-    """
-    actual_value = await signal.get_value()
-    assert actual_value == value, _generate_assert_error_msg(
-        name=signal.name,
-        expected_result=value,
-        actual_result=actual_value,
-    )
-
-
-async def assert_reading(
-    readable: AsyncReadable, expected_reading: Mapping[str, Reading]
-) -> None:
-    """Assert readings from readable.
-
-    Parameters
-    ----------
-    readable:
-        Callable with readable.read function that generate readings.
-
-    reading:
-        The expected readings from the readable.
-
-    Notes
-    -----
-    Example usage::
-        await assert_reading(readable, reading)
-
-    """
-    actual_reading = await readable.read()
-    assert expected_reading == actual_reading, _generate_assert_error_msg(
-        name=readable.name,
-        expected_result=expected_reading,
-        actual_result=actual_reading,
-    )
-
-
-async def assert_configuration(
-    configurable: AsyncConfigurable,
-    configuration: Mapping[str, Reading],
-) -> None:
-    """Assert readings from Configurable.
-
-    Parameters
-    ----------
-    configurable:
-        Configurable with Configurable.read function that generate readings.
-
-    configuration:
-        The expected readings from configurable.
-
-    Notes
-    -----
-    Example usage::
-        await assert_configuration(configurable configuration)
-
-    """
-    actual_configurable = await configurable.read_configuration()
-    assert configuration == actual_configurable, _generate_assert_error_msg(
-        name=configurable.name,
-        expected_result=configuration,
-        actual_result=actual_configurable,
-    )
-
-
-def assert_emitted(docs: Mapping[str, list[dict]], **numbers: int):
-    """Assert emitted document generated by running a Bluesky plan
-
-    Parameters
-    ----------
-    Doc:
-        A dictionary
-
-    numbers:
-        expected emission in kwarg from
-
-    Notes
-    -----
-    Example usage::
-        assert_emitted(docs, start=1, descriptor=1,
-        resource=1, datum=1, event=1, stop=1)
-    """
-    assert list(docs) == list(numbers), _generate_assert_error_msg(
-        name="documents",
-        expected_result=list(numbers),
-        actual_result=list(docs),
-    )
-    actual_numbers = {name: len(d) for name, d in docs.items()}
-    assert actual_numbers == numbers, _generate_assert_error_msg(
-        name="emitted",
-        expected_result=numbers,
-        actual_result=actual_numbers,
-    )
-
-
 async def observe_value(
     signal: SignalR[SignalDatatypeT],
     timeout: float | None = None,
     done_status: Status | None = None,
+    done_timeout: float | None = None,
 ) -> AsyncGenerator[SignalDatatypeT, None]:
     """Subscribe to the value of a signal so it can be iterated from.
 
@@ -439,9 +326,17 @@ async def observe_value(
     done_status:
         If this status is complete, stop observing and make the iterator return.
         If it raises an exception then this exception will be raised by the iterator.
+    done_timeout:
+        If given, the maximum time to watch a signal, in seconds. If the loop is still
+        being watched after this length, raise asyncio.TimeoutError. This should be used
+        instead of on an 'asyncio.wait_for' timeout
 
     Notes
     -----
+    Due to a rare condition with busy signals, it is not recommended to use this
+    function with asyncio.timeout, including in an 'asyncio.wait_for' loop. Instead,
+    this timeout should be given to the done_timeout parameter.
+
     Example usage::
 
         async for value in observe_value(sig):
@@ -449,15 +344,26 @@ async def observe_value(
     """
 
     async for _, value in observe_signals_value(
-        signal, timeout=timeout, done_status=done_status
+        signal,
+        timeout=timeout,
+        done_status=done_status,
+        done_timeout=done_timeout,
     ):
         yield value
 
 
+def _get_iteration_timeout(
+    timeout: float | None, overall_deadline: float | None
+) -> float | None:
+    overall_deadline = overall_deadline - time.monotonic() if overall_deadline else None
+    return min([x for x in [overall_deadline, timeout] if x is not None], default=None)
+
+
 async def observe_signals_value(
     *signals: SignalR[SignalDatatypeT],
     timeout: float | None = None,
     done_status: Status | None = None,
+    done_timeout: float | None = None,
 ) -> AsyncGenerator[tuple[SignalR[SignalDatatypeT], SignalDatatypeT], None]:
     """Subscribe to the value of a signal so it can be iterated from.
 
@@ -472,6 +378,10 @@ async def observe_signals_value(
     done_status:
         If this status is complete, stop observing and make the iterator return.
         If it raises an exception then this exception will be raised by the iterator.
+    done_timeout:
+        If given, the maximum time to watch a signal, in seconds. If the loop is still
+        being watched after this length, raise asyncio.TimeoutError. This should be used
+        instead of on an 'asyncio.wait_for' timeout
 
     Notes
     -----
@@ -486,12 +396,6 @@ async def observe_signals_value(
     q: asyncio.Queue[tuple[SignalR[SignalDatatypeT], SignalDatatypeT] | Status] = (
         asyncio.Queue()
     )
-    if timeout is None:
-        get_value = q.get
-    else:
-
-        async def get_value():
-            return await asyncio.wait_for(q.get(), timeout)
 
     cbs: dict[SignalR, Callback] = {}
     for signal in signals:
@@ -504,13 +408,17 @@ async def observe_signals_value(
 
     if done_status is not None:
         done_status.add_callback(q.put_nowait)
-
+    overall_deadline = time.monotonic() + done_timeout if done_timeout else None
     try:
         while True:
-            # yield here in case something else is filling the queue
-            # like in test_observe_value_times_out_with_no_external_task()
-            await asyncio.sleep(0)
-            item = await get_value()
+            if overall_deadline and time.monotonic() >= overall_deadline:
+                raise asyncio.TimeoutError(
+                    f"observe_value was still observing signals "
+                    f"{[signal.source for signal in signals]} after "
+                    f"timeout {done_timeout}s"
+                )
+            iteration_timeout = _get_iteration_timeout(timeout, overall_deadline)
+            item = await asyncio.wait_for(q.get(), iteration_timeout)
             if done_status and item is done_status:
                 if exc := done_status.exception():
                     raise exc
@@ -696,3 +604,35 @@ async def set_and_wait_for_value(
         status_timeout,
         wait_for_set_completion,
     )
+
+
+def walk_rw_signals(device: Device, path_prefix: str = "") -> dict[str, SignalRW[Any]]:
+    """Retrieve all SignalRWs from a device.
+
+    Stores retrieved signals with their dotted attribute paths in a dictionary. Used as
+    part of saving and loading a device.
+
+    Parameters
+    ----------
+    device : Device
+        Ophyd device to retrieve read-write signals from.
+
+    path_prefix : str
+        For internal use, leave blank when calling the method.
+
+    Returns
+    -------
+    SignalRWs : dict
+        A dictionary matching the string attribute path of a SignalRW with the
+        signal itself.
+
+    """
+    signals: dict[str, SignalRW[Any]] = {}
+
+    for attr_name, attr in device.children():
+        dot_path = f"{path_prefix}{attr_name}"
+        if type(attr) is SignalRW:
+            signals[dot_path] = attr
+        attr_signals = walk_rw_signals(attr, path_prefix=dot_path + ".")
+        signals.update(attr_signals)
+    return signals

ophyd_async/core/_signal_backend.py

@@ -10,7 +10,10 @@ from ._table import Table
 from ._utils import Callback, StrictEnum, T
 
 DTypeScalar_co = TypeVar("DTypeScalar_co", covariant=True, bound=np.generic)
-Array1D = np.ndarray[tuple[int], np.dtype[DTypeScalar_co]]
+# To be a 1D array shape should really be tuple[int], but np.array()
+# currently produces tuple[int, ...] even when it has 1D input args
+# https://github.com/numpy/numpy/issues/28077#issuecomment-2566485178
+Array1D = np.ndarray[tuple[int, ...], np.dtype[DTypeScalar_co]]
 Primitive = bool | int | float | str
 # NOTE: if you change this union then update the docs to match
 SignalDatatype = (

ophyd_async/core/_soft_signal_backend.py

@@ -175,7 +175,8 @@ class SoftSignalBackend(SignalBackend[SignalDatatypeT]):
         return self.reading["value"]
 
     def set_callback(self, callback: Callback[Reading[SignalDatatypeT]] | None) -> None:
+        if callback and self.callback:
+            raise RuntimeError("Cannot set a callback when one is already set")
         if callback:
-            assert not self.callback, "Cannot set a callback when one is already set"
             callback(self.reading)
         self.callback = callback

ophyd_async/core/_table.py

@@ -39,6 +39,11 @@ class Table(BaseModel):
     # so it is strictly checked against the BaseModel we are supplied.
     model_config = ConfigDict(extra="allow")
 
+    # Add an init method to match the above model config, otherwise the type
+    # checker will not think we can pass arbitrary kwargs into the base class init
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+
     @classmethod
     def __init_subclass__(cls):
         # But forbit extra in subclasses so it gets validated
@@ -78,9 +83,6 @@ class Table(BaseModel):
             }
         )
 
-    def __eq__(self, value: object) -> bool:
-        return super().__eq__(value)
-
     def numpy_dtype(self) -> np.dtype:
         dtype = []
         for k, v in self:
@@ -99,8 +101,10 @@ class Table(BaseModel):
                 v = v[selection]
             if array is None:
                 array = np.empty(v.shape, dtype=self.numpy_dtype())
-            array[k] = v
-        assert array is not None
+            array[k] = v  # type: ignore
+        if array is None:
+            msg = "No arrays found in table"
+            raise ValueError(msg)
         return array
 
     @model_validator(mode="before")
@@ -123,10 +127,12 @@ class Table(BaseModel):
                 # Convert to correct dtype, but only if we don't lose precision
                 # as a result
                 cast_value = np.array(data_value).astype(expected_dtype)
-                assert np.array_equal(data_value, cast_value), (
-                    f"{field_name}: Cannot cast {data_value} to {expected_dtype} "
-                    "without losing precision"
-                )
+                if not np.array_equal(data_value, cast_value):
+                    msg = (
+                        f"{field_name}: Cannot cast {data_value} to {expected_dtype} "
+                        "without losing precision"
+                    )
+                    raise ValueError(msg)
                 data_dict[field_name] = cast_value
         return data_dict
 
@@ -135,7 +141,9 @@ class Table(BaseModel):
         lengths: dict[int, set[str]] = {}
         for field_name, field_value in self:
             lengths.setdefault(len(field_value), set()).add(field_name)
-        assert len(lengths) <= 1, f"Columns should be same length, got {lengths=}"
+        if len(lengths) > 1:
+            msg = f"Columns should be same length, got {lengths=}"
+            raise ValueError(msg)
         return self
 
     def __len__(self) -> int:

ophyd_async/core/_utils.py

@@ -16,13 +16,38 @@ Callback = Callable[[T], None]
 DEFAULT_TIMEOUT = 10.0
 ErrorText = str | Mapping[str, Exception]
 
+logger = logging.getLogger("ophyd_async")
 
-class StrictEnum(str, Enum):
+
+class StrictEnumMeta(EnumMeta):
+    def __new__(metacls, *args, **kwargs):
+        ret = super().__new__(metacls, *args, **kwargs)
+        lowercase_names = [x.name for x in ret if not x.name.isupper()]  # type: ignore
+        if lowercase_names:
+            raise TypeError(f"Names {lowercase_names} should be uppercase")
+        return ret
+
+
+class StrictEnum(str, Enum, metaclass=StrictEnumMeta):
     """All members should exist in the Backend, and there will be no extras"""
 
 
-class SubsetEnumMeta(EnumMeta):
+class SubsetEnumMeta(StrictEnumMeta):
     def __call__(self, value, *args, **kwargs):  # type: ignore
+        """
+        Returns given value if it is a string and not a member of the enum.
+        If the value is not a string or is an enum member, default enum behavior
+        is applied. Type checking will complain if provided arbitrary string.
+
+        Returns:
+            Union[str, SubsetEnum]: If the value is a string and not a member of the
+            enum, the string is returned as is. Otherwise, the corresponding enum
+            member is returned.
+
+        Raises:
+            ValueError: If the value is not a string and cannot be converted to an enum
+            member.
+        """
         if isinstance(value, str) and not isinstance(value, self):
             return value
         return super().__call__(value, *args, **kwargs)
@@ -85,7 +110,7 @@ class NotConnected(Exception):
     def format_error_string(self, indent="") -> str:
         if not isinstance(self._errors, dict) and not isinstance(self._errors, str):
             raise RuntimeError(
-                f"Unexpected type `{type(self._errors)}` " "expected `str` or `dict`"
+                f"Unexpected type `{type(self._errors)}` expected `str` or `dict`"
             )
 
         if isinstance(self._errors, str):
@@ -105,7 +130,7 @@ class NotConnected(Exception):
     ) -> NotConnected:
         for name, exception in exceptions.items():
             if not isinstance(exception, NotConnected):
-                logging.exception(
+                logger.exception(
                     f"device `{name}` raised unexpected exception "
                     f"{type(exception).__name__}",
                     exc_info=exception,
@@ -180,7 +205,7 @@ def get_enum_cls(datatype: type | None) -> type[StrictEnum] | None:
     if datatype and issubclass(datatype, Enum):
         if not issubclass(datatype, StrictEnum):
             raise TypeError(
-                f"{datatype} should inherit from .SubsetEnum "
+                f"{datatype} should inherit from ophyd_async.core.SubsetEnum "
                 "or ophyd_async.core.StrictEnum"
             )
         return datatype

ophyd_async/core/_yaml_settings.py

@@ -0,0 +1,64 @@
+import warnings
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+import yaml
+from pydantic import BaseModel
+
+from ._settings import SettingsProvider
+
+
+def ndarray_representer(dumper: yaml.Dumper, array: npt.NDArray[Any]) -> yaml.Node:
+    return dumper.represent_sequence(
+        "tag:yaml.org,2002:seq", array.tolist(), flow_style=True
+    )
+
+
+def pydantic_model_abstraction_representer(
+    dumper: yaml.Dumper, model: BaseModel
+) -> yaml.Node:
+    return dumper.represent_data(model.model_dump(mode="python"))
+
+
+def enum_representer(dumper: yaml.Dumper, enum: Enum) -> yaml.Node:
+    return dumper.represent_data(enum.value)
+
+
+class YamlSettingsProvider(SettingsProvider):
+    def __init__(self, directory: Path | str):
+        self._directory = Path(directory)
+
+    def _file_path(self, name: str) -> Path:
+        return self._directory / (name + ".yaml")
+
+    async def store(self, name: str, data: dict[str, Any]):
+        yaml.add_representer(np.ndarray, ndarray_representer, Dumper=yaml.Dumper)
+        yaml.add_multi_representer(
+            BaseModel,
+            pydantic_model_abstraction_representer,
+            Dumper=yaml.Dumper,
+        )
+        yaml.add_multi_representer(Enum, enum_representer, Dumper=yaml.Dumper)
+        with open(self._file_path(name), "w") as file:
+            yaml.dump(data, file)
+
+    async def retrieve(self, name: str) -> dict[str, Any]:
+        with open(self._file_path(name)) as file:
+            data = yaml.full_load(file)
+        if isinstance(data, list):
+            warnings.warn(
+                DeprecationWarning(
+                    "Found old save file. Re-save your yaml settings file "
+                    f"{self._file_path(name)} using "
+                    "ophyd_async.plan_stubs.store_settings"
+                ),
+                stacklevel=2,
+            )
+            merge = {}
+            for d in data:
+                merge.update(d)
+            return merge
+        return data

ophyd_async/epics/adandor/__init__.py

@@ -0,0 +1,9 @@
+from ._andor import Andor2Detector
+from ._andor_controller import Andor2Controller
+from ._andor_io import Andor2DriverIO
+
+__all__ = [
+    "Andor2Detector",
+    "Andor2Controller",
+    "Andor2DriverIO",
+]

ophyd_async/epics/adandor/_andor.py

@@ -0,0 +1,45 @@
+from collections.abc import Sequence
+
+from ophyd_async.core import PathProvider
+from ophyd_async.core._signal import SignalR
+from ophyd_async.epics import adcore
+
+from ._andor_controller import Andor2Controller
+from ._andor_io import Andor2DriverIO
+
+
+class Andor2Detector(adcore.AreaDetector[Andor2Controller]):
+    """
+    Andor 2 area detector device (CCD detector 56fps with full chip readout).
+    Andor model:DU897_BV.
+    """
+
+    def __init__(
+        self,
+        prefix: str,
+        path_provider: PathProvider,
+        drv_suffix="cam1:",
+        writer_cls: type[adcore.ADWriter] = adcore.ADHDFWriter,
+        fileio_suffix: str | None = None,
+        name: str = "",
+        config_sigs: Sequence[SignalR] = (),
+        plugins: dict[str, adcore.NDPluginBaseIO] | None = None,
+    ):
+        driver = Andor2DriverIO(prefix + drv_suffix)
+        controller = Andor2Controller(driver)
+
+        writer = writer_cls.with_io(
+            prefix,
+            path_provider,
+            dataset_source=driver,
+            fileio_suffix=fileio_suffix,
+            plugins=plugins,
+        )
+
+        super().__init__(
+            controller=controller,
+            writer=writer,
+            plugins=plugins,
+            name=name,
+            config_sigs=config_sigs,
+        )

ophyd_async/epics/adandor/_andor_controller.py

@@ -0,0 +1,49 @@
+import asyncio
+
+from ophyd_async.core import (
+    DetectorTrigger,
+    TriggerInfo,
+)
+from ophyd_async.epics import adcore
+
+from ._andor_io import Andor2DriverIO, Andor2TriggerMode
+
+_MIN_DEAD_TIME = 0.1
+_MAX_NUM_IMAGE = 999_999
+
+
+class Andor2Controller(adcore.ADBaseController[Andor2DriverIO]):
+    def __init__(
+        self,
+        driver: Andor2DriverIO,
+        good_states: frozenset[adcore.DetectorState] = adcore.DEFAULT_GOOD_STATES,
+    ) -> None:
+        super().__init__(driver, good_states=good_states)
+
+    def get_deadtime(self, exposure: float | None) -> float:
+        return _MIN_DEAD_TIME + (exposure or 0)
+
+    async def prepare(self, trigger_info: TriggerInfo):
+        await self.set_exposure_time_and_acquire_period_if_supplied(
+            trigger_info.livetime
+        )
+        await asyncio.gather(
+            self.driver.trigger_mode.set(self._get_trigger_mode(trigger_info.trigger)),
+            self.driver.num_images.set(
+                trigger_info.total_number_of_triggers or _MAX_NUM_IMAGE
+            ),
+            self.driver.image_mode.set(adcore.ImageMode.MULTIPLE),
+        )
+
+    def _get_trigger_mode(self, trigger: DetectorTrigger) -> Andor2TriggerMode:
+        supported_trigger_types = {
+            DetectorTrigger.INTERNAL: Andor2TriggerMode.INTERNAL,
+            DetectorTrigger.EDGE_TRIGGER: Andor2TriggerMode.EXT_TRIGGER,
+        }
+        if trigger not in supported_trigger_types:
+            raise ValueError(
+                f"{self.__class__.__name__} only supports the following trigger "
+                f"types: {supported_trigger_types} but was asked to "
+                f"use {trigger}"
+            )
+        return supported_trigger_types[trigger]