ophyd-async 0.9.0a1__py3-none-any.whl → 0.10.0a1__py3-none-any.whl

ophyd_async/core/_utils.py

@@ -11,10 +11,12 @@ from unittest.mock import Mock
 import numpy as np
 
 T = TypeVar("T")
+V = TypeVar("V")
 P = ParamSpec("P")
 Callback = Callable[[T], None]
 DEFAULT_TIMEOUT = 10.0
-ErrorText = str | Mapping[str, Exception]
+
+logger = logging.getLogger("ophyd_async")
 
 
 class StrictEnumMeta(EnumMeta):
@@ -27,18 +29,33 @@ class StrictEnumMeta(EnumMeta):
 
 
 class StrictEnum(str, Enum, metaclass=StrictEnumMeta):
-    """All members should exist in the Backend, and there will be no extras"""
+    """All members should exist in the Backend, and there will be no extras."""
 
 
 class SubsetEnumMeta(StrictEnumMeta):
     def __call__(self, value, *args, **kwargs):  # type: ignore
+        """Return 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)
 
 
 class SubsetEnum(StrictEnum, metaclass=SubsetEnumMeta):
-    """All members should exist in the Backend, but there may be extras"""
+    """All members should exist in the Backend, but there may be extras."""
 
 
 CALCULATE_TIMEOUT = "CALCULATE_TIMEOUT"
@@ -53,22 +70,16 @@ CalculatableTimeout = float | None | Literal["CALCULATE_TIMEOUT"]
 
 
 class NotConnected(Exception):
-    """Exception to be raised if a `Device.connect` is cancelled"""
+    """Exception to be raised if a `Device.connect` is cancelled.
 
-    _indent_width = "    "
+    :param errors:
+        Mapping of device name to Exception or another NotConnected.
+        Alternatively a string with the signal error text.
+    """
 
-    def __init__(self, errors: ErrorText):
-        """
-        NotConnected holds a mapping of device/signal names to
-        errors.
-
-        Parameters
-        ----------
-        errors: ErrorText
-            Mapping of device name to Exception or another NotConnected.
-            Alternatively a string with the signal error text.
-        """
+    _indent_width = "    "
 
+    def __init__(self, errors: str | Mapping[str, Exception]):
         self._errors = errors
 
     @property
@@ -94,7 +105,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):
@@ -114,7 +125,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,
@@ -124,21 +135,38 @@ class NotConnected(Exception):
 
 @dataclass(frozen=True)
 class WatcherUpdate(Generic[T]):
-    """A dataclass such that, when expanded, it provides the kwargs for a watcher"""
+    """A dataclass such that, when expanded, it provides the kwargs for a watcher."""
 
     current: T
+    """The current value, where it currently is."""
+
     initial: T
+    """The initial value, where it was when it started."""
+
     target: T
+    """The target value, where it will be when it finishes."""
+
     name: str | None = None
+    """An optional name for the device, if available."""
+
     unit: str | None = None
+    """Units of the value, if applicable."""
+
     precision: float | None = None
+    """How many decimal places the value should be displayed to."""
+
     fraction: float | None = None
+    """The fraction of the way between initial and target."""
+
     time_elapsed: float | None = None
+    """The time elapsed since the start of the operation."""
+
     time_remaining: float | None = None
+    """The time remaining until the operation completes."""
 
 
 async def wait_for_connection(**coros: Awaitable[None]):
-    """Call many underlying signals, accumulating exceptions and returning them
+    """Call many underlying signals, accumulating exceptions and returning them.
 
     Expected kwargs should be a mapping of names to coroutine tasks to execute.
     """
@@ -162,12 +190,15 @@ async def wait_for_connection(**coros: Awaitable[None]):
 
 
 def get_dtype(datatype: type) -> np.dtype:
-    """Get the runtime dtype from a numpy ndarray type annotation
+    """Get the runtime dtype from a numpy ndarray type annotation.
 
+    ```python
     >>> from ophyd_async.core import Array1D
     >>> import numpy as np
     >>> get_dtype(Array1D[np.int8])
     dtype('int8')
+
+    ```
     """
     if not get_origin(datatype) == np.ndarray:
         raise TypeError(f"Expected Array1D[dtype], got {datatype}")
@@ -177,33 +208,46 @@ def get_dtype(datatype: type) -> np.dtype:
 
 
 def get_enum_cls(datatype: type | None) -> type[StrictEnum] | None:
-    """Get the runtime dtype from a numpy ndarray type annotation
-
-    >>> import numpy.typing as npt
-    >>> import numpy as np
-    >>> get_dtype(npt.NDArray[np.int8])
-    dtype('int8')
+    """Get the enum class from a datatype.
+
+    :raises TypeError: if type is not a [](#StrictEnum) or [](#SubsetEnum) subclass
+    ```python
+    >>> from ophyd_async.core import StrictEnum
+    >>> from collections.abc import Sequence
+    >>> class MyEnum(StrictEnum):
+    ...     A = "A value"
+    >>> get_enum_cls(str)
+    >>> get_enum_cls(MyEnum)
+    <enum 'MyEnum'>
+    >>> get_enum_cls(Sequence[MyEnum])
+    <enum 'MyEnum'>
+
+    ```
     """
     if get_origin(datatype) is Sequence:
         datatype = get_args(datatype)[0]
     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
+    return None
 
 
 def get_unique(values: dict[str, T], types: str) -> T:
-    """If all values are the same, return that value, otherwise raise TypeError
+    """If all values are the same, return that value, otherwise raise TypeError.
 
+    ```python
     >>> get_unique({"a": 1, "b": 1}, "integers")
     1
     >>> get_unique({"a": 1, "b": 2}, "integers")
     Traceback (most recent call last):
      ...
     TypeError: Differing integers: a has 1, b has 2
+
+    ```
     """
     set_values = set(values.values())
     if len(set_values) != 1:
@@ -217,9 +261,12 @@ async def merge_gathered_dicts(
 ) -> dict[str, T]:
     """Merge dictionaries produced by a sequence of coroutines.
 
-    Can be used for merging ``read()`` or ``describe``. For instance::
+    Can be used for merging `read()` or `describe()`.
 
-        combined_read = await merge_gathered_dicts(s.read() for s in signals)
+    :example:
+    ```python
+    combined_read = await merge_gathered_dicts(s.read() for s in signals)
+    ```
     """
     ret: dict[str, T] = {}
     for result in await asyncio.gather(*coros):
@@ -227,21 +274,18 @@ async def merge_gathered_dicts(
     return ret
 
 
-async def gather_list(coros: Iterable[Awaitable[T]]) -> list[T]:
-    return await asyncio.gather(*coros)
+async def gather_dict(coros: Mapping[T, Awaitable[V]]) -> dict[T, V]:
+    """Take named coros and return a dict of their name to their return value."""
+    values = await asyncio.gather(*coros.values())
+    return dict(zip(coros, values, strict=True))
 
 
 def in_micros(t: float) -> int:
-    """
-    Converts between a positive number of seconds and an equivalent
-    number of microseconds.
-
-    Args:
-        t (float): A time in seconds
-    Raises:
-        ValueError: if t < 0
-    Returns:
-        t (int): A time in microseconds, rounded up to the nearest whole microsecond,
+    """Convert between a seconds and microseconds.
+
+    :param t: A time in seconds
+    :return: A time in microseconds, rounded up to the nearest whole microsecond
+    :raises ValueError: if t < 0
     """
     if t < 0:
         raise ValueError(f"Expected a positive time in seconds, got {t!r}")
@@ -252,6 +296,7 @@ def get_origin_class(annotatation: Any) -> type | None:
     origin = get_origin(annotatation) or annotatation
     if isinstance(origin, type):
         return origin
+    return None
 
 
 class Reference(Generic[T]):
@@ -259,16 +304,16 @@ class Reference(Generic[T]):
 
     Used to opt out of the naming/parent-child relationship of `Device`.
 
-    For example::
-
-        class DeviceWithRefToSignal(Device):
-            def __init__(self, signal: SignalRW[int]):
-                self.signal_ref = Reference(signal)
-                super().__init__()
-
-            def set(self, value) -> AsyncStatus:
-                return self.signal_ref().set(value + 1)
+    :example:
+    ```python
+    class DeviceWithRefToSignal(Device):
+        def __init__(self, signal: SignalRW[int]):
+            self.signal_ref = Reference(signal)
+            super().__init__()
 
+        def set(self, value) -> AsyncStatus:
+            return self.signal_ref().set(value + 1)
+    ```
     """
 
     def __init__(self, obj: T):
@@ -287,6 +332,7 @@ class LazyMock:
     constructed so that when the leaf is created, so are its parents.
     Any calls to the child are then accessible from the parent mock.
 
+    ```python
     >>> parent = LazyMock()
     >>> child = parent.child("child")
     >>> child_mock = child()
@@ -295,6 +341,8 @@ class LazyMock:
     >>> parent_mock = parent()
     >>> parent_mock.mock_calls
     [call.child()]
+
+    ```
     """
 
     def __init__(self, name: str = "", parent: LazyMock | None = None) -> None:
@@ -303,6 +351,7 @@ class LazyMock:
         self._mock: Mock | None = None
 
     def child(self, name: str) -> LazyMock:
+        """Return a child of this LazyMock with the given name."""
         return LazyMock(name, self)
 
     def __call__(self) -> Mock:

ophyd_async/core/_yaml_settings.py

@@ -0,0 +1,66 @@
+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):
+    """For providing settings from yaml to signals."""
+
+    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/__init__.py

@@ -0,0 +1 @@
+"""EPICS support for Signals, and Devices that use them."""

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,51 @@
+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]):
+    """For controlling the Andor 2 detector."""
+
+    def __init__(
+        self,
+        driver: Andor2DriverIO,
+        good_states: frozenset[adcore.ADState] = 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.ADImageMode.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]

ophyd_async/epics/adandor/_andor_io.py

@@ -0,0 +1,34 @@
+from ophyd_async.core import StrictEnum, SubsetEnum
+from ophyd_async.epics.adcore import ADBaseIO
+from ophyd_async.epics.core import (
+    epics_signal_r,
+    epics_signal_rw,
+)
+
+
+class Andor2TriggerMode(StrictEnum):
+    INTERNAL = "Internal"
+    EXT_TRIGGER = "External"
+    EXT_START = "External Start"
+    EXT_EXPOSURE = "External Exposure"
+    EXT_FVP = "External FVP"
+    SOFTWARE = "Software"
+
+
+class Andor2DataType(SubsetEnum):
+    UINT16 = "UInt16"
+    UINT32 = "UInt32"
+    FLOAT32 = "Float32"
+    FLOAT64 = "Float64"
+
+
+class Andor2DriverIO(ADBaseIO):
+    """Epics pv for andor model:DU897_BV as deployed on p99."""
+
+    def __init__(self, prefix: str, name: str = "") -> None:
+        super().__init__(prefix, name=name)
+        self.trigger_mode = epics_signal_rw(Andor2TriggerMode, prefix + "TriggerMode")
+        self.data_type = epics_signal_r(Andor2DataType, prefix + "DataType_RBV")  # type: ignore
+        self.andor_accumulate_period = epics_signal_r(
+            float, prefix + "AndorAccumulatePeriod_RBV"
+        )

ophyd_async/epics/adaravis/__init__.py

@@ -1,9 +1,16 @@
+"""Support for the ADAravis areaDetector driver.
+
+https://github.com/areaDetector/ADAravis
+"""
+
 from ._aravis import AravisDetector
 from ._aravis_controller import AravisController
-from ._aravis_io import AravisDriverIO
+from ._aravis_io import AravisDriverIO, AravisTriggerMode, AravisTriggerSource
 
 __all__ = [
     "AravisDetector",
     "AravisController",
     "AravisDriverIO",
+    "AravisTriggerMode",
+    "AravisTriggerSource",
 ]

ophyd_async/epics/adaravis/_aravis.py

@@ -1,61 +1,43 @@
-from typing import get_args
+from collections.abc import Sequence
 
-from bluesky.protocols import HasHints, Hints
-
-from ophyd_async.core import PathProvider, StandardDetector
+from ophyd_async.core import PathProvider, SignalR
 from ophyd_async.epics import adcore
 
 from ._aravis_controller import AravisController
 from ._aravis_io import AravisDriverIO
 
 
-class AravisDetector(StandardDetector, HasHints):
-    """
-    Ophyd-async implementation of an ADAravis Detector.
+class AravisDetector(adcore.AreaDetector[AravisController]):
+    """Implementation of an ADAravis Detector.
+
     The detector may be configured for an external trigger on a GPIO port,
     which must be done prior to preparing the detector
     """
 
-    _controller: AravisController
-    _writer: adcore.ADHDFWriter
-
     def __init__(
         self,
         prefix: str,
         path_provider: PathProvider,
         drv_suffix="cam1:",
-        hdf_suffix="HDF1:",
-        name="",
-        gpio_number: AravisController.GPIO_NUMBER = 1,
+        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,
     ):
-        self.drv = AravisDriverIO(prefix + drv_suffix)
-        self.hdf = adcore.NDFileHDFIO(prefix + hdf_suffix)
-
+        driver = AravisDriverIO(prefix + drv_suffix)
+        controller = AravisController(driver)
+        writer = writer_cls.with_io(
+            prefix,
+            path_provider,
+            dataset_source=driver,
+            fileio_suffix=fileio_suffix,
+            plugins=plugins,
+        )
         super().__init__(
-            AravisController(self.drv, gpio_number=gpio_number),
-            adcore.ADHDFWriter(
-                self.hdf,
-                path_provider,
-                lambda: self.name,
-                adcore.ADBaseDatasetDescriber(self.drv),
-            ),
-            config_sigs=(self.drv.acquire_time,),
+            controller=controller,
+            writer=writer,
+            plugins=plugins,
             name=name,
+            config_sigs=config_sigs,
         )
-
-    def get_external_trigger_gpio(self):
-        return self._controller.gpio_number
-
-    def set_external_trigger_gpio(self, gpio_number: AravisController.GPIO_NUMBER):
-        supported_gpio_numbers = get_args(AravisController.GPIO_NUMBER)
-        if gpio_number not in supported_gpio_numbers:
-            raise ValueError(
-                f"{self.__class__.__name__} only supports the following GPIO "
-                f"indices: {supported_gpio_numbers} but was asked to "
-                f"use {gpio_number}"
-            )
-        self._controller.gpio_number = gpio_number
-
-    @property
-    def hints(self) -> Hints:
-        return self._writer.hints