pymmcore-plus 0.9.3__py3-none-any.whl → 0.13.0__py3-none-any.whl

pymmcore_plus/core/events/__init__.py

@@ -1,4 +1,4 @@
-from typing import TYPE_CHECKING, Any, List, Type
+from typing import TYPE_CHECKING, Any
 
 from pymmcore_plus._util import signals_backend
 
@@ -6,19 +6,19 @@ from ._protocol import PCoreSignaler
 from ._psygnal import CMMCoreSignaler
 
 if TYPE_CHECKING:
-    from ._qsignals import QCoreSignaler  # noqa: TCH004
+    from ._qsignals import QCoreSignaler  # noqa: TC004
 
 
 __all__ = [
     "CMMCoreSignaler",
-    "QCoreSignaler",
     "PCoreSignaler",
-    "_get_auto_core_callback_class",
+    "QCoreSignaler",
     "_denormalize_slot",
+    "_get_auto_core_callback_class",
 ]
 
 
-def _get_auto_core_callback_class() -> Type[PCoreSignaler]:
+def _get_auto_core_callback_class() -> type[PCoreSignaler]:
     if signals_backend() == "qt":
         from ._qsignals import QCoreSignaler
 
@@ -26,7 +26,7 @@ def _get_auto_core_callback_class() -> Type[PCoreSignaler]:
     return CMMCoreSignaler
 
 
-def __dir__() -> List[str]:  # pragma: no cover
+def __dir__() -> list[str]:  # pragma: no cover
     return [*list(globals()), "QCoreSignaler"]
 
 

pymmcore_plus/core/events/_device_signal_view.py

@@ -1,14 +1,16 @@
-from typing import TYPE_CHECKING, Any, Optional
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     from pymmcore_plus.core import CMMCorePlus
 
-from ._prop_event_mixin import _C
+    from ._prop_event_mixin import _C
 
 
 class _DevicePropValueSignal:
     def __init__(
-        self, device_label: str, property_name: Optional[str], mmcore: "CMMCorePlus"
+        self, device_label: str, property_name: str | None, mmcore: CMMCorePlus
     ) -> None:
         self._dev = device_label
         self._prop = property_name
@@ -18,13 +20,13 @@ class _DevicePropValueSignal:
         sig = self._mmc.events.devicePropertyChanged(self._dev, self._prop)
         return sig.connect(callback)  # type: ignore
 
-    def disconnect(self, callback: _C) -> None:
+    def disconnect(self, callback: _C | None = None) -> None:
         sig = self._mmc.events.devicePropertyChanged(self._dev, self._prop)
-        return sig.disconnect(callback)  # type: ignore
+        sig.disconnect(callback)
 
     def emit(self, *args: Any) -> Any:
         """Emits the signal with the given arguments."""
         self._mmc.events.devicePropertyChanged(self._dev, self._prop).emit(*args)
 
-    def __call__(self, property: str) -> "_DevicePropValueSignal":
+    def __call__(self, property: str) -> _DevicePropValueSignal:
         return _DevicePropValueSignal(self._dev, property, self._mmc)

pymmcore_plus/core/events/_norm_slot.py

@@ -8,13 +8,11 @@ from types import MethodType
 from typing import TYPE_CHECKING, Any, Callable, Union
 
 if TYPE_CHECKING:
-    from typing import Tuple
-
     from typing_extensions import TypeGuard  # py310
 
-    MethodRef = Tuple[weakref.ReferenceType[object], str, Callable | None]
+    MethodRef = tuple[weakref.ReferenceType[object], str, Callable | None]
     NormedCallback = Union[MethodRef, Callable]
-    StoredSlot = Tuple[NormedCallback, int | None]
+    StoredSlot = tuple[NormedCallback, int | None]
     ReducerFunc = Callable[[tuple, tuple], tuple]
 
 

pymmcore_plus/core/events/_prop_event_mixin.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Callable, ClassVar, Dict, Tuple, TypeVar
+from typing import TYPE_CHECKING, Any, Callable, ClassVar, TypeVar
 
 from ._norm_slot import denormalize_slot, normalize_slot
 from ._protocol import PCoreSignaler
@@ -8,8 +8,8 @@ from ._protocol import PCoreSignaler
 if TYPE_CHECKING:
     from ._norm_slot import NormedCallback
 
-    PropKey = Tuple[str, str | None, NormedCallback]
-    PropKeyDict = Dict[PropKey, Callable]
+    PropKey = tuple[str, str | None, NormedCallback]
+    PropKeyDict = dict[PropKey, Callable]
 
 
 _C = TypeVar("_C", bound=Callable[..., Any])
@@ -64,8 +64,11 @@ class _PropertySignal:
         self._events.propertyChanged.connect(_wrapper)
         return callback
 
-    def disconnect(self, callback: Callable) -> None:
+    def disconnect(self, callback: Callable | None = None) -> None:
         """Disconnect `callback` from this device and/or property."""
+        if callback is None:
+            self._events.propertyChanged.disconnect()
+            return
         key = (self._device, self._property, normalize_slot(callback))
         cb = self._events.property_callbacks.pop(key, None)
         if cb is None:

pymmcore_plus/core/events/_protocol.py

@@ -12,8 +12,11 @@ class PSignalInstance(Protocol):
     def connect(self, slot: Callable) -> Any:
         """Connect slot to this signal."""
 
-    def disconnect(self, slot: Callable) -> Any:
-        """Disconnect slot from this signal."""
+    def disconnect(self, slot: Optional[Callable] = None) -> Any:
+        """Disconnect slot from this signal.
+
+        If `None`, all slots should be disconnected.
+        """
 
     def emit(self, *args: Any) -> Any:
         """Emits the signal with the given arguments."""

pymmcore_plus/core/events/_psygnal.py

@@ -1,11 +1,11 @@
-from psygnal import Signal, SignalInstance
+from psygnal import Signal, SignalGroup, SignalInstance
 
 from pymmcore_plus.mda import MDAEngine
 
 from ._prop_event_mixin import _DevicePropertyEventMixin
 
 
-class CMMCoreSignaler(_DevicePropertyEventMixin):
+class CMMCoreSignaler(SignalGroup, _DevicePropertyEventMixin):
     """Signals that will be emitted from CMMCorePlus objects."""
 
     # native MMCore callback events

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)