make device factory decorator

docs/explanations/decisions/0003-make-devices-factory.md

@@ -0,0 +1,28 @@
+# 3. Add device factory decorator with lazy connect support
+
+Date: 2024-04-26
+
+## Status
+
+Accepted
+
+## Context
+
+We should add a decorator to support verified device connection.
+
+## Decision
+
+DAQ members led us to this proposal:
+
+- ophyd-async: make Device.connect(mock, timeout, force=False) be idempotent
+- ophyd-async: make ensure_connected(\*devices) plan stub
+- dodal: make device_factory(eager=False) decorator that makes, names, caches and optionally connects a device
+- dodal: make get_device_factories() that returns all device factories and whether they should be connected at startup
+- blueapi: call get_device_factories(), make all the Devices, connect the ones that should be connected at startup in parallel and log those that fail
+- blueapi: when plan is called, run ensure_connected on all plan args and defaults that are Devices
+
+We can then iterate on this if the parallel connect causes a broadcast storm. We could also in future add a monitor to a heartbeat PV per device in Device.connect so that it would reconnect next time it was called.
+
+## Consequences
+
+The changes above.

src/dodal/aliases.py

@@ -0,0 +1,13 @@
+from collections.abc import Callable
+
+try:
+    from typing import TypeAlias
+except ImportError:
+    from typing import TypeAlias
+from ophyd.device import Device as OphydV1Device
+from ophyd_async.core import Device as OphydV2Device
+
+AnyDevice: TypeAlias = OphydV1Device | OphydV2Device
+V1DeviceFactory: TypeAlias = Callable[..., OphydV1Device]
+V2DeviceFactory: TypeAlias = Callable[..., OphydV2Device]
+AnyDeviceFactory: TypeAlias = V1DeviceFactory | V2DeviceFactory

src/dodal/beamlines/__init__.py

@@ -20,30 +20,49 @@
 }
 
 
-def all_beamline_modules() -> Iterable[str]:
-    """
-    Get the names of all importable modules in beamlines
+class ModuleDiscoveryError(Exception):
+    """Custom exception for module discovery errors."""
+
+    pass
+
 
+def get_all_beamline_modules() -> Iterable[str]:
+    """
+    Get the names of all importable modules in the beamlines package by inspecting file paths.
     Returns:
-        Iterable[str]: Generator of beamline module names
+        Iterable[str]: Generator of beamline module names (excluding __init__.py and __pycache__).
+    Raises:
+        ModuleDiscoveryError: If the beamlines module could not be found.
     """
 
-    # This is done by inspecting file names rather than modules to avoid
-    # premature importing
-    spec = importlib.util.find_spec(__name__)
-    if spec is not None:
-        assert spec.submodule_search_locations
-        search_paths = [Path(path) for path in spec.submodule_search_locations]
-        for path in search_paths:
-            for subpath in path.glob("**/*"):
-                if (
-                    subpath.name.endswith(".py")
-                    and subpath.name != "__init__.py"
-                    and ("__pycache__" not in str(subpath))
-                ):
-                    yield subpath.with_suffix("").name
-    else:
-        raise KeyError(f"Unable to find {__name__} module")
+    try:
+        # Find the package spec for the current module
+        spec = importlib.util.find_spec(__name__)
+    except Exception as e:
+        raise ModuleDiscoveryError(
+            f"Error while finding module spec for {__name__}: {e}"
+        ) from e
+
+    if not spec or not spec.submodule_search_locations:
+        raise ModuleDiscoveryError(
+            f"Unable to find module search locations for {__name__}"
+        )
+
+    search_paths = [Path(path) for path in spec.submodule_search_locations]
+
+    # Yield valid module names by filtering Python files
+    for path in search_paths:
+        for subpath in path.glob("**/*.py"):
+            if _is_valid_module(subpath):
+                yield subpath.stem  # `.stem` gives the filename without the suffix
+
+
+def _is_valid_module(subpath):
+    return (
+        subpath.name.endswith(".py")
+        and subpath.name != "__init__.py"
+        and ("__pycache__" not in str(subpath))
+    )
 
 
 def all_beamline_names() -> Iterable[str]:
@@ -54,7 +73,7 @@
         Iterable[str]: Generator of beamline names that dodal supports
     """
     inverse_mapping = _module_name_overrides()
-    for module_name in all_beamline_modules():
+    for module_name in get_all_beamline_modules():
         yield from inverse_mapping.get(module_name, set()).union({module_name})
 
 

src/dodal/beamlines/i03.py

@@ -2,9 +2,11 @@
 
 from dodal.common.beamlines.beamline_parameters import get_beamline_parameters
 from dodal.common.beamlines.beamline_utils import (
+    BeamlinePrefix,
     device_instantiation,
     get_path_provider,
     set_path_provider,
+    skip_device,
 )
 from dodal.common.beamlines.beamline_utils import set_beamline as set_utils_beamline
 from dodal.common.udc_directory_provider import PandASubpathProvider
@@ -40,7 +42,7 @@
 from dodal.devices.zebra_controlled_shutter import ZebraShutter
 from dodal.devices.zocalo import ZocaloResults
 from dodal.log import set_beamline as set_log_beamline
-from dodal.utils import BeamlinePrefix, get_beamline_name, skip_device
+from dodal.utils import get_beamline_name
 
 ZOOM_PARAMS_FILE = (
     "/dls_sw/i03/software/gda/configurations/i03-config/xml/jCameraManZoomLevels.xml"

src/dodal/beamlines/i04.py

@@ -1,5 +1,9 @@
 from dodal.common.beamlines.beamline_parameters import get_beamline_parameters
-from dodal.common.beamlines.beamline_utils import device_instantiation
+from dodal.common.beamlines.beamline_utils import (
+    BeamlinePrefix,
+    device_instantiation,
+    skip_device,
+)
 from dodal.common.beamlines.beamline_utils import set_beamline as set_utils_beamline
 from dodal.devices.aperturescatterguard import (
     AperturePosition,
@@ -29,7 +33,7 @@
 from dodal.devices.zebra import Zebra
 from dodal.devices.zebra_controlled_shutter import ZebraShutter
 from dodal.log import set_beamline as set_log_beamline
-from dodal.utils import BeamlinePrefix, get_beamline_name, skip_device
+from dodal.utils import get_beamline_name
 
 ZOOM_PARAMS_FILE = (
     "/dls_sw/i04/software/gda/configurations/i04-config/xml/jCameraManZoomLevels.xml"

src/dodal/beamlines/i04_1.py

@@ -1,4 +1,8 @@
-from dodal.common.beamlines.beamline_utils import device_instantiation
+from dodal.common.beamlines.beamline_utils import (
+    BeamlinePrefix,
+    device_instantiation,
+    skip_device,
+)
 from dodal.common.beamlines.beamline_utils import set_beamline as set_utils_beamline
 from dodal.devices.backlight import Backlight
 from dodal.devices.detector import DetectorParams
@@ -9,7 +13,7 @@
 from dodal.devices.undulator import Undulator
 from dodal.devices.zebra import Zebra
 from dodal.log import set_beamline as set_log_beamline
-from dodal.utils import BeamlinePrefix, get_beamline_name, skip_device
+from dodal.utils import get_beamline_name
 
 ZOOM_PARAMS_FILE = "/dls_sw/i04-1/software/gda/config/xml/jCameraManZoomLevels.xml"
 DISPLAY_CONFIG = "/dls_sw/i04-1/software/gda_versions/var/display.configuration"