dls-dodal 1.36.0__py3-none-any.whl → 1.36.2__py3-none-any.whl

dodal/utils.py

@@ -1,3 +1,4 @@
+import functools
 import importlib
 import inspect
 import os
@@ -6,13 +7,14 @@ import socket
 import string
 from collections.abc import Callable, Iterable, Mapping
 from dataclasses import dataclass
-from functools import wraps
+from functools import update_wrapper, wraps
 from importlib import import_module
 from inspect import signature
 from os import environ
 from types import ModuleType
 from typing import (
     Any,
+    Generic,
     Protocol,
     TypeGuard,
     TypeVar,
@@ -35,6 +37,7 @@ from bluesky.protocols import (
     Triggerable,
     WritesExternalAssets,
 )
+from bluesky.run_engine import call_in_bluesky_event_loop
 from ophyd.device import Device as OphydV1Device
 from ophyd_async.core import Device as OphydV2Device
 
@@ -99,6 +102,8 @@ class BeamlinePrefix:
 
 
 T = TypeVar("T", bound=AnyDevice)
+D = TypeVar("D", bound=OphydV2Device)
+SkipType = bool | Callable[[], bool]
 
 
 def skip_device(precondition=lambda: True):
@@ -114,6 +119,91 @@ def skip_device(precondition=lambda: True):
     return decorator
 
 
+class DeviceInitializationController(Generic[D]):
+    def __init__(
+        self,
+        factory: Callable[[], D],
+        use_factory_name: bool,
+        timeout: float,
+        mock: bool,
+        skip: SkipType,
+    ):
+        self._factory: Callable[[], D] = functools.cache(factory)
+        self._use_factory_name = use_factory_name
+        self._timeout = timeout
+        self._mock = mock
+        self._skip = skip
+        update_wrapper(self, factory)
+
+    @property
+    def skip(self) -> bool:
+        return self._skip() if callable(self._skip) else self._skip
+
+    def cache_clear(self) -> None:
+        """Clears the controller's internal cached instance of the device, if present.
+        Noop if not."""
+
+        # Functools adds the cache_clear function via setattr so the type checker
+        # does not pick it up.
+        self._factory.cache_clear()  # type: ignore
+
+    def __call__(
+        self,
+        connect_immediately: bool = False,
+        name: str | None = None,
+        connection_timeout: float | None = None,
+        mock: bool | None = None,
+    ) -> D:
+        """Returns an instance of the Device the wrapped factory produces: the same
+        instance will be returned if this method is called multiple times, and arguments
+        may be passed to override this Controller's configuration.
+        Once the device is connected, the value of mock must be consistent, or connect
+        must be False.
+
+
+        Args:
+            connect_immediately (bool, default False): whether to call connect on the
+              device before returning it- connect is idempotent for ophyd-async devices.
+              Not connecting to the device allows for the instance to be created prior
+              to the RunEngine event loop being configured or for connect to be called
+              lazily e.g. by the `ensure_connected` stub.
+            name (str | None, optional): an override name to give the device, which is
+              also used to name its children. Defaults to None, which does not name the
+              device unless the device has no name and this Controller is configured to
+              use_factory_name, which propagates the name of the wrapped factory
+              function to the device instance.
+            connection_timeout (float | None, optional): an override timeout length in
+              seconds for the connect method, if it is called. Defaults to None, which
+              defers to the timeout configured for this Controller: the default uses
+              ophyd_async's DEFAULT_TIMEOUT.
+            mock (bool | None, optional): overrides whether to connect to Mock signal
+              backends, if connect is called. Defaults to None, which uses the mock
+              parameter of this Controller. This value must be used consistently when
+              connect is called on the Device.
+
+        Returns:
+            D: a singleton instance of the Device class returned by the wrapped factory.
+        """
+        device = self._factory()
+
+        if connect_immediately:
+            call_in_bluesky_event_loop(
+                device.connect(
+                    timeout=connection_timeout
+                    if connection_timeout is not None
+                    else self._timeout,
+                    mock=mock if mock is not None else self._mock,
+                )
+            )
+
+        if name:
+            device.set_name(name)
+        elif not device.name and self._use_factory_name:
+            device.set_name(self._factory.__name__)
+
+        return device
+
+
 def make_device(
     module: str | ModuleType,
     device_name: str,
@@ -206,7 +296,33 @@ def invoke_factories(
         dependent_name = leaves.pop()
         params = {name: devices[name] for name in dependencies[dependent_name]}
         try:
-            devices[dependent_name] = factories[dependent_name](**params, **kwargs)
+            factory = factories[dependent_name]
+            if isinstance(factory, DeviceInitializationController):
+                # For now we translate the old-style parameters that
+                # device_instantiation expects. Once device_instantiation is gone and
+                # replaced with DeviceInitializationController we can formalise the
+                # API of make_all_devices and make these parameters explicit.
+                # https://github.com/DiamondLightSource/dodal/issues/844
+                mock = kwargs.get(
+                    "mock",
+                    kwargs.get(
+                        "fake_with_ophyd_sim",
+                        False,
+                    ),
+                )
+                connect_immediately = kwargs.get(
+                    "connect_immediately",
+                    kwargs.get(
+                        "wait_for_connection",
+                        False,
+                    ),
+                )
+                devices[dependent_name] = factory(
+                    mock=mock,
+                    connect_immediately=connect_immediately,
+                )
+            else:
+                devices[dependent_name] = factory(**params, **kwargs)
         except Exception as e:
             exceptions[dependent_name] = e
 
@@ -268,6 +384,8 @@ def collect_factories(
 
 
 def _is_device_skipped(func: AnyDeviceFactory) -> bool:
+    if isinstance(func, DeviceInitializationController):
+        return func.skip
     return getattr(func, "__skip__", False)
 
 
@@ -301,6 +419,37 @@ def is_v1_device_type(obj: type[Any]) -> bool:
     return is_class and follows_protocols and not is_v2_device_type(obj)
 
 
+def filter_ophyd_devices(
+    devices: Mapping[str, AnyDevice],
+) -> tuple[Mapping[str, OphydV1Device], Mapping[str, OphydV2Device]]:
+    """
+    Split a dictionary of ophyd and ophyd-async devices
+    (i.e. the output of make_all_devices) into 2 separate dictionaries of the
+    different types. Useful when special handling is needed for each type of device.
+
+    Args:
+        devices: Dictionary of device name to ophyd or ophyd-async device.
+
+    Raises:
+        ValueError: If anything in the dictionary doesn't come from either library.
+
+    Returns:
+        Tuple of two dictionaries, one mapping names to ophyd devices and one mapping
+        names to ophyd-async devices.
+    """
+
+    ophyd_devices = {}
+    ophyd_async_devices = {}
+    for name, device in devices.items():
+        if isinstance(device, OphydV1Device):
+            ophyd_devices[name] = device
+        elif isinstance(device, OphydV2Device):
+            ophyd_async_devices[name] = device
+        else:
+            raise ValueError(f"{name}: {device} is not an ophyd or ophyd-async device")
+    return ophyd_devices, ophyd_async_devices
+
+
 def get_beamline_based_on_environment_variable() -> ModuleType:
     """
     Gets the dodal module for the current beamline, as specified by the

dodal/adsim.py

@@ -1,17 +0,0 @@
-import os
-
-from dodal.devices.adsim import SimStage
-from dodal.devices.areadetector import AdSimDetector
-
-from .utils import get_hostname
-
-# Default prefix to hostname unless overriden with export PREFIX=<prefix>
-PREFIX: str = os.environ.get("PREFIX", get_hostname())
-
-
-def stage(name: str = "sim_motors") -> SimStage:
-    return SimStage(name=name, prefix=f"{PREFIX}-MO-SIM-01:")
-
-
-def det(name: str = "adsim") -> AdSimDetector:
-    return AdSimDetector(name=name, prefix=f"{PREFIX}-AD-SIM-01:")

dodal/devices/areadetector/__init__.py

@@ -1,10 +0,0 @@
-from .adaravis import AdAravisDetector
-from .adsim import AdSimDetector
-from .adutils import Hdf5Writer, SynchronisedAdDriverBase
-
-__all__ = [
-    "AdSimDetector",
-    "SynchronisedAdDriverBase",
-    "Hdf5Writer",
-    "AdAravisDetector",
-]

dodal/devices/areadetector/adaravis.py

@@ -1,101 +0,0 @@
-from collections.abc import Mapping
-from typing import Any
-
-from ophyd import EpicsSignal, Signal
-from ophyd.areadetector.base import ADComponent as Cpt
-from ophyd.areadetector.detectors import DetectorBase
-
-from .adutils import Hdf5Writer, SingleTriggerV33, SynchronisedAdDriverBase
-
-_ACQUIRE_BUFFER_PERIOD = 0.2
-
-
-class AdAravisDetector(SingleTriggerV33, DetectorBase):
-    cam = Cpt(SynchronisedAdDriverBase, suffix="DET:")
-    hdf = Cpt(
-        Hdf5Writer,
-        suffix="HDF5:",
-        root="",
-        write_path_template="",
-    )
-    _priming_settings: Mapping[Signal, Any]
-
-    def __init__(self, *args, **kwargs) -> None:
-        super().__init__(*args, **kwargs)
-        self.hdf.kind = "normal"
-
-        # Values for staging
-        self.stage_sigs = {
-            # Get stage to wire up the plugins
-            self.hdf.nd_array_port: self.cam.port_name.get(),
-            # Reset array counter on stage
-            self.cam.array_counter: 0,
-            # Set image mode to multiple on stage so we have the option, can still
-            # set num_images to 1
-            self.cam.image_mode: "Multiple",
-            # For now, this Ophyd device does not support hardware
-            # triggered scanning, disable on stage
-            self.cam.trigger_mode: "Off",
-            **self.stage_sigs,  # type: ignore
-        }
-
-        # Settings to apply when priming plugins during pre-stage
-        self._priming_settings = {
-            self.hdf.enable: 1,
-            self.hdf.nd_array_port: self.cam.port_name.get(),
-            self.cam.array_callbacks: 1,
-            self.cam.image_mode: "Single",
-            self.cam.trigger_mode: "Off",
-            # Take the quickest possible frame
-            self.cam.acquire_time: 6.3e-05,
-            self.cam.acquire_period: 0.003,
-        }
-
-        # Signals that control driver and hdf writer should be put_complete to
-        # avoid race conditions during priming
-        for signal in set(self.stage_sigs.keys()).union(
-            set(self._priming_settings.keys())
-        ):
-            if isinstance(signal, EpicsSignal):
-                signal.put_complete = True
-        self.cam.acquire.put_complete = True
-
-    def stage(self, *args, **kwargs) -> list[object]:
-        # We have to manually set the acquire period bcause the EPICS driver
-        # doesn't do it for us. If acquire time is a staged signal, we use the
-        # stage value to calculate the acquire period, otherwise we perform
-        # a caget and use the current acquire time.
-        if self.cam.acquire_time in self.stage_sigs:
-            acquire_time = self.stage_sigs[self.cam.acquire_time]
-        else:
-            acquire_time = self.cam.acquire_time.get()
-        self.stage_sigs[self.cam.acquire_period] = (
-            float(acquire_time) + _ACQUIRE_BUFFER_PERIOD
-        )
-
-        # Ensure detector warmed up
-        self._prime_hdf()
-
-        # Now calling the super method should set the acquire period
-        return super().stage(*args, **kwargs)
-
-    def _prime_hdf(self) -> None:
-        """
-        Take a single frame and pipe it through the HDF5 writer plugin
-        """
-
-        # Backup state and ensure we are not acquiring
-        reset_to = {signal: signal.get() for signal in self._priming_settings.keys()}
-        self.cam.acquire.set(0).wait(timeout=10)
-
-        # Apply all settings for acquisition
-        for signal, value in self._priming_settings.items():
-            # Ensure that .wait really will wait until the PV is set including its RBV
-            signal.set(value).wait(timeout=10)
-
-        # Acquire a frame
-        self.cam.acquire.set(1).wait(timeout=10)
-
-        # Revert settings to previous values
-        for signal, value in reversed(reset_to.items()):
-            signal.set(value).wait(timeout=10)

dodal/devices/areadetector/adsim.py

@@ -1,47 +0,0 @@
-from ophyd.areadetector.base import ADComponent as Cpt
-from ophyd.areadetector.detectors import DetectorBase
-
-from .adutils import Hdf5Writer, SingleTriggerV33, SynchronisedAdDriverBase
-
-
-class AdSimDetector(SingleTriggerV33, DetectorBase):
-    cam = Cpt(SynchronisedAdDriverBase, suffix="CAM:", lazy=True)
-    hdf = Cpt(
-        Hdf5Writer,
-        suffix="HDF5:",
-        root="",
-        write_path_template="",
-        lazy=True,
-    )
-
-    def __init__(self, *args, **kwargs) -> None:
-        super().__init__(*args, **kwargs)
-        self.hdf.kind = "normal"
-
-        self.stage_sigs = {
-            # Get stage to wire up the plugins
-            self.hdf.nd_array_port: self.cam.port_name.get(),
-            # Reset array counter on stage
-            self.cam.array_counter: 0,
-            # Set image mode to multiple on stage so we have the option, can still
-            # set num_images to 1
-            self.cam.image_mode: "Multiple",
-            # For now, this Ophyd device does not support hardware
-            # triggered scanning, disable on stage
-            self.cam.trigger_mode: "Internal",
-            **self.stage_sigs,  # type: ignore
-        }
-
-    def stage(self, *args, **kwargs) -> list[object]:
-        # We have to manually set the acquire period bcause the EPICS driver
-        # doesn't do it for us. If acquire time is a staged signal, we use the
-        # stage value to calculate the acquire period, otherwise we perform
-        # a caget and use the current acquire time.
-        if self.cam.acquire_time in self.stage_sigs:
-            acquire_time = self.stage_sigs[self.cam.acquire_time]
-        else:
-            acquire_time = self.cam.acquire_time.get()
-        self.stage_sigs[self.cam.acquire_period] = acquire_time
-
-        # Now calling the super method should set the acquire period
-        return super().stage(*args, **kwargs)

dodal/devices/areadetector/adutils.py

@@ -1,81 +0,0 @@
-import time as ttime
-
-from ophyd import Component as Cpt
-from ophyd import DetectorBase, Device, EpicsSignal, EpicsSignalRO, Staged
-from ophyd.areadetector import ADTriggerStatus, TriggerBase
-from ophyd.areadetector.cam import AreaDetectorCam
-from ophyd.areadetector.filestore_mixins import FileStoreHDF5, FileStoreIterativeWrite
-from ophyd.areadetector.plugins import HDF5Plugin
-
-
-class SingleTriggerV33(TriggerBase):
-    _status_type = ADTriggerStatus
-
-    def __init__(self, *args, image_name=None, **kwargs):
-        super().__init__(*args, **kwargs)
-        if image_name is None:
-            # Ensure that this mixin is part of valid device with name
-            assert isinstance(self, Device)
-            image_name = "_".join([self.name, "image"])
-        self._image_name = image_name
-
-    def trigger(self):
-        "Trigger one acquisition."
-        if self._staged != Staged.yes:
-            raise RuntimeError(
-                "This detector is not ready to trigger."
-                "Call the stage() method before triggering."
-            )
-
-        self._status = self._status_type(self)
-
-        def _acq_done(*args, **kwargs):
-            # TODO sort out if anything useful in here
-            self._status._finished()  # noqa: SLF001
-
-        self._acquisition_signal.put(1, use_complete=True, callback=_acq_done)
-        # Ensure that this mixin is part of valid Detector with generate_datum
-        assert isinstance(self, DetectorBase)
-        self.generate_datum(self._image_name, ttime.time())
-        return self._status
-
-
-class SynchronisedAdDriverBase(AreaDetectorCam):
-    """
-    Base Ophyd device to control an AreaDetector driver and
-    syncrhonise it on other AreaDetector plugins, even non-blocking ones.
-    """
-
-    adcore_version = Cpt(EpicsSignalRO, "ADCoreVersion_RBV", string=True, kind="config")
-    driver_version = Cpt(EpicsSignalRO, "DriverVersion_RBV", string=True, kind="config")
-    wait_for_plugins = Cpt(EpicsSignal, "WaitForPlugins", string=True, kind="config")
-
-    def stage(self, *args, **kwargs):
-        # Makes the detector allow non-blocking AD plugins but makes Ophyd use
-        # the AcquireBusy PV to determine when an acquisition is complete
-        self.ensure_nonblocking()
-        return super().stage(*args, **kwargs)
-
-    def ensure_nonblocking(self):
-        self.stage_sigs["wait_for_plugins"] = "Yes"
-        if self.parent is not None:
-            for c in self.parent.component_names:
-                cpt = getattr(self.parent, c)
-                if cpt is self:
-                    continue
-                if hasattr(cpt, "ensure_nonblocking"):
-                    cpt.ensure_nonblocking()
-
-
-# ophyd code to be removed, only used for adim
-# https://github.com/DiamondLightSource/dodal/issues/404
-class Hdf5Writer(HDF5Plugin, FileStoreHDF5, FileStoreIterativeWrite):  # type: ignore
-    """ """
-
-    pool_max_buffers = None
-    file_number_sync = None
-    file_number_write = None
-
-    def get_frames_per_point(self):
-        assert isinstance(self.parent, DetectorBase)
-        return self.parent.cam.num_images.get()