pymmcore-plus 0.12.0__py3-none-any.whl → 0.13.1__py3-none-any.whl

pymmcore_plus/experimental/unicore/__init__.py

@@ -0,0 +1,14 @@
+from ._unicore import UniMMCore
+from .devices._device import Device
+from .devices._properties import PropertyInfo, pymm_property
+from .devices._stage import StageDevice, XYStageDevice, XYStepperStageDevice
+
+__all__ = [
+    "Device",
+    "PropertyInfo",
+    "StageDevice",
+    "UniMMCore",
+    "XYStageDevice",
+    "XYStepperStageDevice",
+    "pymm_property",
+]

pymmcore_plus/experimental/unicore/_device_manager.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import logging
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import TYPE_CHECKING, TypeVar, cast
+
+from pymmcore_plus.core._constants import DeviceInitializationState, DeviceType
+
+from .devices._device import Device
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from pymmcore import DeviceLabel
+
+    from ._proxy import CMMCoreProxy
+
+DevT = TypeVar("DevT", bound=Device)
+logger = logging.getLogger(__name__)
+
+
+class PyDeviceManager:
+    """Manages loaded Python devices."""
+
+    __slots__ = ("_devices",)
+
+    def __init__(self) -> None:
+        self._devices: dict[str, Device] = {}
+
+    def load(self, label: str, device: Device, proxy: CMMCoreProxy) -> None:
+        """Load a device and assign it a label."""
+        if label in self._devices:  # pragma: no cover
+            # we probably won't ever get here because the core checks this too
+            raise ValueError(f"The specified device label {label!r} is already in use")
+        self._devices[label] = device
+        device._label_ = label
+        device._core_proxy_ = proxy
+
+    def initialize(self, label: str) -> None:
+        """Initialize the device with the given label."""
+        device = self[label]
+        try:
+            device.initialize()
+            device._initialized_ = True
+        except Exception as e:
+            device._initialized_ = e
+            logger.exception(f"Failed to initialize device {label!r}")
+
+    def initialize_all(self) -> None:
+        if not (labels := self.get_labels_of_type(DeviceType.Any)):
+            return  # pragma: no cover
+
+        # Initialize all devices in parallel
+        with ThreadPoolExecutor() as executor:
+            for future in as_completed(
+                executor.submit(self.initialize, label) for label in labels
+            ):
+                future.result()
+
+    def wait_for(
+        self, label: str, timeout_ms: float = 5000, polling_interval: float = 0.01
+    ) -> None:
+        """Wait for the device to not be busy."""
+        device = self[label]
+        deadline = time.perf_counter() + timeout_ms / 1000
+
+        while True:
+            with device:
+                if not device.busy():
+                    return
+            if time.perf_counter() > deadline:
+                raise TimeoutError(
+                    f"Wait for device {label!r} timed out after {timeout_ms} ms"
+                )
+            time.sleep(polling_interval)
+
+    def wait_for_device_type(self, dev_type: int, timeout_ms: float = 5000) -> None:
+        if not (labels := self.get_labels_of_type(dev_type)):
+            return  # pragma: no cover
+
+        # Wait for all python devices of the given type in parallel
+        with ThreadPoolExecutor() as executor:
+            futures = (
+                executor.submit(self.wait_for, lbl, timeout_ms) for lbl in labels
+            )
+            for future in as_completed(futures):
+                future.result()  # Raises any exceptions from wait_for_device
+
+    def get_initialization_state(self, label: str) -> DeviceInitializationState:
+        """Return the initialization state of the device with the given label."""
+        state = self[label]._initialized_
+        if state is True:
+            return DeviceInitializationState.InitializedSuccessfully
+        if state is False:
+            return DeviceInitializationState.Uninitialized
+        return DeviceInitializationState.InitializationFailed
+
+    def unload(self, label_or_device: str | Device) -> None:
+        """Unload a loaded device by label or instance."""
+        if isinstance(label_or_device, Device):
+            if label_or_device not in self._devices.values():
+                raise ValueError("Device instance is not loaded")  # pragma: no cover
+            _device, label = label_or_device, label_or_device._label_
+        else:
+            _device, label = self[label_or_device], label_or_device
+
+        with _device as dev:
+            dev.shutdown()
+            dev._initialized_ = False
+            dev._label_ = ""
+            dev._core_proxy_ = None
+        self._devices.pop(label)
+
+    def unload_all(self) -> None:
+        """Unload all loaded devices."""
+        for label in list(self._devices):
+            self.unload(label)
+
+    def __len__(self) -> int:
+        """Return the number of loaded device labels."""
+        return len(self._devices)
+
+    def __iter__(self) -> Iterator[DeviceLabel]:
+        """Return an iterator over the loaded device labels."""
+        return iter(self._devices)  # type: ignore
+
+    def __contains__(self, label: str) -> bool:
+        """Return True if the device with the given label is loaded."""
+        return label in self._devices
+
+    def __getitem__(self, label: str) -> Device:
+        """Get device by label, raising KeyError if it does not exist."""
+        if label not in self._devices:
+            raise KeyError(f"No device with label '{label!r}'")
+        return self._devices[label]
+
+    def get_initialized(
+        self, label: str, *, require_initialized: bool = True
+    ) -> Device:
+        """Get device by label, returning None if it does not exist.
+
+        This method is a convenience wrapper around __getitem__ that ensures the device
+        is both loaded and initialized.
+        """
+        if (device := self[label])._initialized_ is not True and require_initialized:
+            raise ValueError(f"Device {label!r} is not initialized")
+        return device
+
+    def get_device_of_type(self, label: str, *types: type[DevT]) -> DevT:
+        """Get device by label, ensuring it is of the correct type.
+
+        Parameters
+        ----------
+        label : str
+            The label of the device to retrieve.
+        types : type[DevT]
+            The type(s) the device must be an instance of.
+        """
+        device = self[label]
+        if isinstance(device, types):
+            return device
+        raise ValueError(
+            f"Device {label!r} is the wrong device type for the requested operation"
+        )
+
+    def get_labels_of_type(self, dev_type: int) -> tuple[DeviceLabel, ...]:
+        """Get the labels of all devices that are instances of the given type(s)."""
+        return tuple(
+            cast("DeviceLabel", label)
+            for label, device in self._devices.items()
+            if dev_type == DeviceType.Any or device.type() == dev_type
+        )

pymmcore_plus/experimental/unicore/_proxy.py

@@ -0,0 +1,127 @@
+"""Proxy objects expose a subset of an object's API.
+
+Useful, e.g., for passing a core-like object to python-side device adapters without
+exposing the entirety of the core.
+"""
+
+from __future__ import annotations
+
+import types
+from itertools import chain
+from typing import TYPE_CHECKING, Any, Protocol, TypeVar, cast, get_type_hints
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from pymmcore_plus.core._mmcore_plus import CMMCorePlus
+
+T = TypeVar("T")
+
+
+class PSignalInstance(Protocol):
+    """A signal instance that can only emit."""
+
+    def emit(self, *args: Any) -> Any:
+        """Emits the signal with the given arguments."""
+
+
+class CoreEventsProxy(Protocol):
+    """Signals that Device Adapters can emit directly."""
+
+    propertyChanged: PSignalInstance  # (str, str, str)
+    stagePositionChanged: PSignalInstance  # (str, float)
+    XYStagePositionChanged: PSignalInstance  # (str, float, float)
+    exposureChanged: PSignalInstance  # (str, float)
+    SLMExposureChanged: PSignalInstance  # (str, float)
+    # channelGroupChanged: PSignalInstance  # (str)
+    # configGroupChanged: PSignalInstance  # (str, str)
+    # configSet: PSignalInstance  # (str, str)
+
+
+class CMMCoreProxy(Protocol):
+    """Exposed CMMCcorePlus attributes that devices may access."""
+
+    @property
+    def events(self) -> CoreEventsProxy:
+        """Events that devices may emit."""
+
+
+def create_core_proxy(core: CMMCorePlus) -> CMMCoreProxy:
+    """Create a proxy object for CMMCorePlus that only exposes CMMCoreProxy."""
+    return create_proxy(core, CMMCoreProxy, {"events": CoreEventsProxy})
+
+
+# ---------------------------------------------------------
+
+
+class _ImmutableModule(types.ModuleType):
+    __frozen__ = False
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if self.__frozen__:
+            raise AttributeError(  # pragma: no cover
+                f"Attributes on proxy {self.__name__!r} cannot be modified."
+            )
+        super().__setattr__(name, value)
+
+    def __delattr__(self, name: str) -> None:
+        raise AttributeError(  # pragma: no cover
+            f"Attributes on proxy {self.__name__!r} cannot be modified."
+        )
+
+
+def create_proxy(
+    obj: Any, protocol: type[T], sub_proxies: Mapping[str, type] | None = None
+) -> T:
+    """Create a proxy object that implements the given protocol.
+
+    Parameters
+    ----------
+    obj : Any
+        The object to proxy.
+    protocol : type[T]
+        The protocol template to implement.  The names and annotations of the protocol
+        define the attributes that will be exposed on the proxy.
+    sub_proxies : Mapping[str, type], optional
+        A mapping of attribute names to sub-protocols.  If an attribute is in this
+        mapping, it will be proxied with the corresponding sub-protocol. For example,
+        if `sub_proxies={"foo": FooProtocol}`, then `proxy.foo` will be a proxy object
+        that implements `FooProtocol`.
+
+    Examples
+    --------
+    ```python
+    class MyProtocol(Protocol):
+        def foo(self) -> None: ...
+
+
+    class MyClass:
+        def foo(self) -> None: ...
+        def bar(self) -> None: ...
+
+
+    proxy = create_proxy(MyClass(), MyProtocol)
+    proxy.foo()  # OK
+    proxy.bar()  # AttributeError
+    ```
+    """
+    sub_proxies = sub_proxies or {}
+    allowed_names = {
+        x
+        for x in chain(dir(protocol), get_type_hints(protocol))
+        if not x.startswith("_")
+    }
+    proxy = _ImmutableModule(protocol.__name__)
+    for attr_name in allowed_names:
+        attr = getattr(obj, attr_name)
+        if subprotocol := sub_proxies.get(attr_name):
+            # look for nested sub-proxies on attr_name, e.g. `attr_name.sub_attr`
+            sub = {
+                k.split(".", 1)[1]: v
+                for k, v in sub_proxies.items()
+                if k.startswith(f"{attr_name}.")
+            }
+            attr = create_proxy(attr, subprotocol, sub)
+        setattr(proxy, attr_name, attr)
+    proxy.__frozen__ = True
+    return cast("T", proxy)