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

pymmcore_plus/experimental/unicore/devices/_device.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+import threading
+from abc import ABC
+from collections import ChainMap
+from typing import TYPE_CHECKING, Any, Callable, ClassVar, Generic, TypeVar, final
+
+from pymmcore_plus.core import DeviceType
+from pymmcore_plus.core._constants import PropertyType
+from pymmcore_plus.experimental.unicore.devices._properties import (
+    PropertyController,
+    PropertyInfo,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import KeysView, Sequence
+
+    from typing_extensions import Any, Self
+
+    from pymmcore_plus.experimental.unicore._proxy import CMMCoreProxy
+
+    from ._properties import PropArg, TDev, TProp
+
+
+class _Lockable:
+    """Mixin to make an object lockable."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._lock = threading.Lock()
+
+    def __enter__(self) -> Self:
+        self._lock.acquire()
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self._lock.release()
+
+    def lock(self, blocking: bool = True, timeout: float = -1) -> bool:
+        return self._lock.acquire(blocking, timeout)  # pragma: no cover
+
+    def unlock(self) -> None:
+        self._lock.release()  # pragma: no cover
+
+    def locked(self) -> bool:
+        return self._lock.locked()  # pragma: no cover
+
+
+class Device(_Lockable, ABC):
+    """ABC for all Devices."""
+
+    _TYPE: ClassVar[DeviceType] = DeviceType.UnknownType
+    _cls_prop_controllers: ClassVar[dict[str, PropertyController]]
+
+    def __init__(self) -> None:
+        super().__init__()
+
+        # NOTE: The following attributes are here for the core to manipulate.
+        # Device Adapter subclasses should not touch these attributes.
+        self._label_: str = ""
+        self._initialized_: bool | BaseException = False
+        self._prop_controllers_ = ChainMap[str, PropertyController](
+            {}, self._cls_prop_controllers
+        )
+        self._core_proxy_: CMMCoreProxy | None = None
+
+    @property
+    def core(self) -> CMMCoreProxy:
+        """The device may use this to access a restricted subset of the Core API."""
+        if self._core_proxy_ is None:
+            raise AttributeError("CoreProxy not set. Has this device been loaded?")
+        return self._core_proxy_
+
+    def __init_subclass__(cls) -> None:
+        """Initialize the property controllers."""
+        cls._cls_prop_controllers = {
+            p.property.name: p
+            for p in cls.__dict__.values()
+            if isinstance(p, PropertyController)
+        }
+        return super().__init_subclass__()
+
+    def register_property(
+        self,
+        name: str,
+        *,
+        default_value: TProp | None = None,
+        getter: Callable[[TDev], TProp] | None = None,
+        setter: Callable[[TDev, TProp], None] | None = None,
+        limits: tuple[int | float, int | float] | None = None,
+        sequence_max_length: int = 0,
+        allowed_values: Sequence[TProp] | None = None,
+        is_read_only: bool = False,
+        is_pre_init: bool = False,
+        property_type: PropArg = None,
+    ) -> None:
+        """Manually register a property.
+
+        This is an alternative to using the `@pymm_property` decorator.  It can be used
+        to register properties that are not defined in the class body.  This is useful
+        for pure "user-side" properties that are not used by the adapter, but which the
+        adapter may want to access (such as a preference or a configuration setting
+        that doesn't affect the device's behavior, but which the adapter may want to
+        read).
+
+        Properties defined this way are not accessible as class attributes.
+        """
+        if property_type is None and default_value is not None:
+            property_type = type(default_value)
+
+        prop_info = PropertyInfo(
+            name=name,
+            default_value=default_value,
+            last_value=default_value,
+            limits=limits,
+            sequence_max_length=sequence_max_length,
+            description="",
+            allowed_values=allowed_values,
+            is_read_only=is_read_only,
+            is_pre_init=is_pre_init,
+            type=PropertyType.create(property_type),
+        )
+        controller = PropertyController(property=prop_info, fget=getter, fset=setter)
+        self._prop_controllers_[name] = controller
+
+    def initialize(self) -> None:
+        """Initialize the device."""
+
+    def shutdown(self) -> None:
+        """Shutdown the device."""
+
+    @final  # may not be overridden
+    def get_label(self) -> str:
+        return self._label_
+
+    @final  # may not be overridden
+    @classmethod
+    def type(cls) -> DeviceType:
+        """Return the type of the device."""
+        return cls._TYPE
+
+    @classmethod
+    def name(cls) -> str:
+        """Return the name of the device."""
+        return f"{cls.__name__}"
+
+    def description(self) -> str:
+        """Return a description of the device."""
+        return self.__doc__ or ""
+
+    def busy(self) -> bool:
+        """Return `True` if the device is busy."""
+        return False
+
+    # PROPERTIES
+
+    def get_property_names(self) -> KeysView[str]:
+        """Return the names of the properties."""
+        return self._prop_controllers_.keys()
+
+    def property(self, prop_name: str) -> PropertyInfo:
+        """Return the property controller for a property."""
+        return self._prop_controllers_[prop_name].property
+
+    def get_property_value(self, prop_name: str) -> Any:
+        """Return the value of a property."""
+        # TODO: catch errors
+        ctrl = self._prop_controllers_[prop_name]
+        if ctrl.fget is None:
+            return ctrl.property.last_value
+        return self._prop_controllers_[prop_name].__get__(self, self.__class__)
+
+    def set_property_value(self, prop_name: str, value: Any) -> None:
+        """Set the value of a property."""
+        # TODO: catch errors
+        ctrl = self._prop_controllers_[prop_name]
+        if ctrl.is_read_only:
+            raise ValueError(f"Property {prop_name!r} is read-only.")
+        if ctrl.fset is not None:
+            ctrl.__set__(self, value)
+        else:
+            ctrl.property.last_value = ctrl.validate(value)
+
+    def load_property_sequence(self, prop_name: str, sequence: Sequence[Any]) -> None:
+        """Load a sequence into a property."""
+        self._prop_controllers_[prop_name].load_sequence(self, sequence)
+
+    def start_property_sequence(self, prop_name: str) -> None:
+        """Start a sequence of a property."""
+        self._prop_controllers_[prop_name].start_sequence(self)
+
+    def stop_property_sequence(self, prop_name: str) -> None:
+        """Stop a sequence of a property."""
+        self._prop_controllers_[prop_name].stop_sequence(self)
+
+    def set_property_allowed_values(
+        self, prop_name: str, allowed_values: Sequence[Any]
+    ) -> None:
+        """Set the allowed values of a property."""
+        self._prop_controllers_[prop_name].property.allowed_values = allowed_values
+
+    def set_property_limits(
+        self, prop_name: str, limits: tuple[float, float] | None
+    ) -> None:
+        """Set the limits of a property."""
+        self._prop_controllers_[prop_name].property.limits = limits
+
+    def set_property_sequence_max_length(self, prop_name: str, max_length: int) -> None:
+        """Set the sequence max length of a property."""
+        self._prop_controllers_[prop_name].property.sequence_max_length = max_length
+
+    def is_property_sequenceable(self, prop_name: str) -> bool:
+        """Return `True` if the property is sequenceable."""
+        return self._prop_controllers_[prop_name].is_sequenceable
+
+    def is_property_read_only(self, prop_name: str) -> bool:
+        """Return `True` if the property is read-only."""
+        return self._prop_controllers_[prop_name].is_read_only
+
+
+SeqT = TypeVar("SeqT")
+
+
+class SequenceableDevice(Device, Generic[SeqT]):
+    """ABC For devices that can handle sequences of values.
+
+    This is used for *most* device classes (XYStage, State, etc...). We
+    convert the core `is<>Sequenceable` methods into a call to the
+    `is_property_sequenceable` method on the "current" device of that type.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+
+    @final
+    def is_sequenceable(self) -> bool:
+        """Return `True` if the device is sequenceable. Default is `False`."""
+        if self.get_sequence_max_length() == 0:
+            return False
+
+        # A device is sequenceable if it returns a max sequence length > 0 AND
+        # has reimplemented the send_sequence and start_sequence methods.
+        # we climb the method resolution chain and make sure that at least one base
+        # class has reimplemented these methods.
+        mro = self.__class__.mro()
+        send_sequence_definer = next(b for b in mro if "send_sequence" in b.__dict__)
+        start_sequence_definer = next(b for b in mro if "start_sequence" in b.__dict__)
+        return (
+            send_sequence_definer is not SequenceableDevice
+            and start_sequence_definer is not SequenceableDevice
+        )
+
+    def get_sequence_max_length(self) -> int:
+        """Return the sequence."""
+        return 0
+
+    def send_sequence(self, sequence: tuple[SeqT, ...]) -> None:
+        """Signal that we are done appending sequence values.
+
+        So that the adapter can send the whole sequence to the device
+        """
+        raise NotImplementedError("This device has not been made sequenceable.")
+
+    def start_sequence(self) -> None:
+        """Start the sequence."""
+        raise NotImplementedError("This device has not been made sequenceable.")
+
+    def stop_sequence(self) -> None:
+        """Stop the sequence."""

pymmcore_plus/experimental/unicore/devices/_properties.py

@@ -0,0 +1,400 @@
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Generic,
+    Literal,
+    TypeVar,
+    Union,
+    cast,
+    overload,
+)
+
+from pymmcore_plus.core._constants import PropertyType
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from typing_extensions import Self, TypeAlias
+
+    from ._device import Device
+
+    PropArg: TypeAlias = (
+        PropertyType | type | Literal["float", "integer", "string", "boolean"] | None
+    )
+
+TDev = TypeVar("TDev", bound="Device")
+TProp = TypeVar("TProp")
+TLim = TypeVar("TLim", bound=Union[int, float])
+
+
+slots_true = {"slots": True} if sys.version_info >= (3, 10) else {}
+kw_only_true = {"kw_only": True} if sys.version_info >= (3, 10) else {}
+
+
+@dataclass(**kw_only_true, **slots_true)
+class PropertyInfo(Generic[TProp]):
+    """State of a property of a device.
+
+    Attributes
+    ----------
+    name : str
+        The name of the property.
+    default_value : TProp, optional
+        The default value of the property, by default None.
+    last_value : TProp, optional
+        The last value seen from the device, by default None.
+    limits : tuple[int | float, int | float], optional
+        The minimum and maximum values of the property, by default None.
+    sequence_max_length : int
+        The maximum length of a sequence of property values.
+    description : str, optional
+        A description of the property, by default None.
+    type : PropertyType
+        The type of the property.
+    allowed_values : Sequence[TProp], optional
+        The allowed values of the property, by default None.
+    is_read_only : bool
+        Whether the property is read-only.
+    is_pre_init : bool
+        Whether the property must be set before initialization.
+    """
+
+    name: str
+    default_value: TProp | None = None  # could be used for a "reset"?
+    last_value: TProp | None = None  # the last value we saw from the device
+    limits: tuple[int | float, int | float] | None = None
+    sequence_max_length: int = 0
+    description: str | None = None
+    type: PropertyType = PropertyType.Undef
+
+    allowed_values: Sequence[TProp] | None = None
+    is_read_only: bool | None = None
+    is_pre_init: bool = False
+
+    @property
+    def is_sequenceable(self) -> bool:
+        """Return True if the property is sequenceable."""
+        return self.sequence_max_length > 0
+
+    def __post_init__(self) -> None:
+        """Ensure sound property configuration."""
+        if self.allowed_values and self.limits:  # pragma: no cover
+            raise ValueError(
+                f"Property {self.name!r} cannot have both allowed values and limits. "
+                "Please choose one or the other."
+            )
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        """Perform additional checks when setting attributes."""
+        object.__setattr__(self, name, value)  # slots dataclass has no super()...
+        # setting allowed values also removes the limits
+        if name == "allowed_values" and value is not None:
+            self.limits = None
+
+
+class PropertyController(Generic[TDev, TProp]):
+    """Controls the state of a property connected to a device.
+
+    PropertyController instances are descriptors (i.e. they behave like @property),
+    that can get and set the value of a property on a Device instance using the
+    getter and setter methods provided at initialization.  They can also load and
+    start sequences of property values, if the property is sequenceable (i.e. it has
+    a non-zero sequence_max_length and has been provided with `sequence_loader` and
+    `sequence_starter` methods).
+
+    Device subclasses maintain PropertyController instances in a ClassVar dictionary,
+    `_prop_controllers`, where the keys are the property names and the values are the
+    PropertyController instances.
+    """
+
+    def __init__(
+        self,
+        property: PropertyInfo[TProp],
+        fget: Callable[[TDev], TProp] | None = None,
+        fset: Callable[[TDev, TProp], None] | None = None,
+        fseq_load: Callable[[TDev, Sequence[TProp]], None] | None = None,
+        fseq_start: Callable[[TDev], None] | None = None,
+        fseq_stop: Callable[[TDev], None] | None = None,
+        doc: str | None = None,
+    ) -> None:
+        self.property = property
+        self.fget = fget
+        self.fset = fset
+        self.fseq_load = fseq_load
+        self.fseq_start = fseq_start
+        self.fseq_stop = fseq_stop
+        self.doc = doc
+
+    # same as "Property::Update" in CMMCore
+    @overload
+    def __get__(
+        self, instance: None, owner: type[TDev]
+    ) -> PropertyController[TDev, TProp]: ...
+    @overload
+    def __get__(self, instance: TDev, owner: type[TDev]) -> TProp: ...
+    def __get__(
+        self, instance: TDev | None, owner: type[TDev]
+    ) -> TProp | PropertyController[TDev, TProp]:
+        """Update the property value by calling the getter on the Device instance."""
+        if instance is None:  # pragma: no cover
+            return self
+        if self.fget is None:  # pragma: no cover
+            raise AttributeError("Unreadable property")
+        val = self.fget(instance)  # cache the value
+        object.__setattr__(self.property, "last_value", val)
+        return val
+
+    # same as "Property::Apply" in CMMCore
+    def __set__(self, instance: TDev, value: TProp) -> None:
+        """Update the property value by calling the setter on the Device instance."""
+        if self.fset is None:  # pragma: no cover
+            raise AttributeError("Unsettable property")
+        value = self.validate(value)
+        self.fset(instance, value)
+
+    def validate(self, value: Any) -> TProp:
+        """Validate a property value."""
+        if self.property.allowed_values and value not in self.property.allowed_values:
+            raise ValueError(
+                f"Value '{value}' is not allowed for property '{self.property.name}'. "
+                f"Allowed values: {list(self.property.allowed_values)}."
+            )
+        if self.property.limits:
+            try:
+                value = float(value)
+            except (ValueError, TypeError) as e:
+                raise ValueError(
+                    f"Non-numeric value {value!r} cannot be compared to the limits "
+                    f"of property {self.property.name!r}: {self.property.limits}."
+                ) from e
+            min_, max_ = self.property.limits
+            if not min_ <= cast(float, value) <= max_:
+                raise ValueError(
+                    f"Value {value!r} is not within the allowed range of property "
+                    f"{self.property.name!r}: {self.property.limits}."
+                )
+        return cast("TProp", value)
+
+    @property
+    def is_sequenceable(self) -> bool:
+        """Return True if the property is sequenceable."""
+        return (
+            self.property.is_sequenceable
+            and self.fseq_load is not None
+            and self.fseq_start is not None
+        )
+
+    @property
+    def is_read_only(self) -> bool:
+        """Return True if the property is read-only.
+
+        We consider a property read-only either if the device has explicitly set it as
+        such, or if the property has a getter but no setter.
+        If it has *neither* a getter nor a setter, and is not explicitly marked as
+        read-only, it is considered writeable: this is assumed to be a "configuration"
+        property that the device adapter cares about, but which is likely never sent
+        to the device itself.
+        """
+        return self.property.is_read_only is True or (
+            self.fset is None and self.fget is not None
+        )
+
+    def load_sequence(self, instance: TDev, sequence: Sequence[TProp]) -> None:
+        """Send a sequence of property values to the device."""
+        if self.fseq_load is None:
+            raise RuntimeError(
+                f"Property {self.property.name!r} is not sequenceable. "
+                "No sequence loader is defined."
+            )
+        if (seq_len := len(sequence)) > (max_len := self.property.sequence_max_length):
+            raise ValueError(
+                f"Sequence length {seq_len} exceeds the maximum allowed length "
+                f"of property {self.property.name!r}: {max_len}."
+            )
+        seq = [self.validate(val) for val in sequence]
+        self.fseq_load(instance, seq)
+
+    def start_sequence(self, instance: TDev) -> None:
+        """Tell the device to start the previously loaded sequence."""
+        if self.fseq_start is None:
+            raise RuntimeError(
+                f"Property {self.property.name!r} is not sequenceable. "
+                "No sequence starter is defined."
+            )
+        self.fseq_start(instance)
+
+    def stop_sequence(self, instance: TDev) -> None:
+        """Stop the sequence."""
+        # it's not an error if there is no stopper
+        if self.fseq_stop is not None:
+            self.fseq_stop(instance)
+
+    # ------------------------- Decorators -------------------------
+
+    def setter(self, fset: Callable[[TDev, TProp], None]) -> Self:
+        """Decorate a method to set the property on the device."""
+        self.fset = fset
+        if self.property.is_read_only is None:
+            self.property.is_read_only = False
+        return self
+
+    def sequence_loader(
+        self, fseq_load: Callable[[TDev, Sequence[TProp]], None]
+    ) -> Self:
+        """Decorate a method that sends a property value sequence to the device."""
+        self.fseq_load = fseq_load
+        return self
+
+    def sequence_starter(self, fseq_start: Callable[[TDev], None]) -> Self:
+        """Decorate a method that starts a (previously loaded) property sequence."""
+        self.fseq_start = fseq_start
+        return self
+
+    def sequence_stopper(self, fseq_stop: Callable[[TDev], None]) -> Self:
+        """Decorate a method that stops the currently running property sequence."""
+        self.fseq_stop = fseq_stop
+        return self
+
+
+@overload  # when used as a decorator
+def pymm_property(fget: Callable[[TDev], TProp]) -> PropertyController[TDev, TProp]: ...
+@overload  # when used with keyword arguments including allowed_values
+def pymm_property(
+    *,
+    allowed_values: Sequence[TProp] | None,  # cannot be combined with limits
+    sequence_max_length: int = ...,
+    is_read_only: bool | None = ...,
+    is_pre_init: bool = ...,
+    name: str | None = ...,
+    property_type: PropArg = ...,
+) -> Callable[[Callable[[TDev], TProp]], PropertyController[TDev, TProp]]: ...
+@overload  # when used with keyword arguments including limits
+def pymm_property(
+    *,
+    limits: tuple[TLim, TLim] | None,  # cannot be combined with allowed_values
+    sequence_max_length: int = ...,
+    is_read_only: bool | None = ...,
+    is_pre_init: bool = ...,
+    name: str | None = ...,
+    property_type: PropArg = ...,
+) -> Callable[[Callable[[TDev], TLim]], PropertyController[TDev, TLim]]: ...
+@overload  # when used with keyword arguments without allowed_values or limits
+def pymm_property(
+    *,
+    sequence_max_length: int = ...,
+    is_read_only: bool | None = ...,
+    is_pre_init: bool = ...,
+    name: str | None = ...,
+    property_type: PropArg = ...,
+) -> Callable[[Callable[[TDev], TLim]], PropertyController[TDev, TLim]]: ...
+def pymm_property(
+    fget: Callable[[TDev], TProp] | None = None,
+    *,
+    limits: tuple[TLim, TLim] | None = None,
+    sequence_max_length: int = 0,
+    allowed_values: Sequence[TProp] | None = None,
+    is_read_only: bool | None = None,
+    is_pre_init: bool = False,
+    name: str | None = None,  # taken from fget if None
+    property_type: PropArg = None,
+) -> (
+    PropertyController[TDev, TProp]
+    | Callable[[Callable[[TDev], TProp]], PropertyController[TDev, TProp]]
+):
+    """Decorates a (getter) method to create a device property.
+
+    The returned PropertyController instance can be additionally used (similar to
+    `@property`) to decorate `setter`, `sequence_loader`, `sequence_starter`, and/or
+    `sequence_stopper` methods.
+
+    Properties can have limits, allowed values, but may not have both.
+
+    Properties will only be considered "sequenceable" (i.e. they support hardware
+    triggering) if they have a non-zero sequence_max_length AND have decorated
+    `sequence_loader` and `sequence_starter` methods.
+
+    Parameters
+    ----------
+    fget : Callable[[TDev], TProp], optional
+        The getter method for the property, by default None.
+    limits : tuple[float, float], optional
+        The minimum and maximum values of the property, by default None. Cannot be
+        combined with `allowed_values`.
+    sequence_max_length : int, optional
+        The maximum length of a sequence of property values, by default 0.
+    allowed_values : Sequence[TProp], optional
+        The allowed values of the property, by default None. Cannot be combined with
+        `limits`.
+    is_read_only : bool, optional
+        Whether the property is read-only, by default False.
+    is_pre_init : bool, optional
+        Whether the property must be set before initialization, by default False.
+    name : str, optional
+        The name of the property, by default, the name of the getter method is used.
+    prop_type : PropArg, optional
+        The type of the property, by default the return annotation of the getter method
+        is used (but must be one of `float`, `int`, or `str`).
+
+
+    Examples
+    --------
+    ```python
+    class MyDevice(Device):
+        @pymm_property(limits=(0, 100), sequence_max_length=10)
+        def position(self) -> float:
+            # get position from device
+            return 42.0
+
+        @position.setter
+        def position(self, value: float) -> None:
+            print(f"Setting position to {value}")
+
+        @position.sequence_loader
+        def load_position_sequence(self, sequence: Sequence[float]) -> None:
+            print(f"Loading position sequence: {sequence}")
+
+        @position.sequence_starter
+        def start_position_sequence(self) -> None:
+            print("Starting position sequence")
+
+        @pymm_property(is_read_only=True)
+        def pressure(self) -> float:
+            return 1.0
+
+        @pymm_property(allowed_values=["low", "medium", "high"])
+        def speed(self) -> str:
+            # get speed from device
+            return "medium"
+
+        @speed.setter
+        def speed(self, value: str) -> None:
+            print(f"Setting speed to {value}")
+    ```
+    """
+
+    def _inner(
+        fget: Callable[[TDev], TProp], _pt: PropArg = property_type
+    ) -> PropertyController[TDev, TProp]:
+        prop = PropertyInfo(
+            name=name or fget.__name__,
+            description=fget.__doc__,
+            limits=limits,
+            sequence_max_length=sequence_max_length,
+            allowed_values=allowed_values,
+            # all @pymm_property properties are read-only by default
+            # until they are decorated with a setter
+            # this does not apply to properties that are manually registered
+            # with Device.register_property.
+            is_read_only=is_read_only,
+            is_pre_init=is_pre_init,
+            type=PropertyType.create(_pt or fget.__annotations__.get("return", None)),
+        )
+
+        return PropertyController(property=prop, fget=fget)
+
+    return _inner if fget is None else _inner(fget)