pymmcore-plus 0.13.7__tar.gz → 0.14.0__tar.gz

{pymmcore_plus-0.13.7 → pymmcore_plus-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymmcore-plus
-Version: 0.13.7
+Version: 0.14.0
 Summary: pymmcore superset providing improved APIs, event handling, and a pure python acquisition engine
 Project-URL: Source, https://github.com/pymmcore-plus/pymmcore-plus
 Project-URL: Tracker, https://github.com/pymmcore-plus/pymmcore-plus/issues
@@ -25,55 +25,32 @@ Classifier: Topic :: System :: Hardware
 Classifier: Topic :: System :: Hardware :: Hardware Drivers
 Classifier: Topic :: Utilities
 Requires-Python: >=3.9
-Requires-Dist: numpy>=1.17.3
+Requires-Dist: numpy>=1.25.2
+Requires-Dist: numpy>=1.26.0; python_version >= '3.12'
+Requires-Dist: numpy>=2.1.0; python_version >= '3.13'
 Requires-Dist: platformdirs>=3.0.0
-Requires-Dist: psygnal>=0.7
-Requires-Dist: pymmcore>=10.7.0.71.0
+Requires-Dist: psygnal>=0.10
+Requires-Dist: pymmcore>=11.2.1.71.0
 Requires-Dist: rich>=10.2.0
-Requires-Dist: tensorstore<=0.1.71
+Requires-Dist: tensorstore!=0.1.72,>=0.1.67
+Requires-Dist: tensorstore!=0.1.72,>=0.1.71; python_version >= '3.13'
 Requires-Dist: typer>=0.4.2
-Requires-Dist: typing-extensions
-Requires-Dist: useq-schema>=0.7.0
+Requires-Dist: typing-extensions>=4
+Requires-Dist: useq-schema>=0.7.2
 Provides-Extra: cli
 Requires-Dist: rich>=10.2.0; extra == 'cli'
 Requires-Dist: typer>=0.4.2; extra == 'cli'
-Provides-Extra: dev
-Requires-Dist: ipython; extra == 'dev'
-Requires-Dist: mypy; extra == 'dev'
-Requires-Dist: pdbpp; (sys_platform != 'win32') and extra == 'dev'
-Requires-Dist: pre-commit; extra == 'dev'
-Requires-Dist: ruff; extra == 'dev'
-Requires-Dist: tensorstore-stubs; extra == 'dev'
-Provides-Extra: docs
-Requires-Dist: mkdocs-autorefs==1.3.1; extra == 'docs'
-Requires-Dist: mkdocs-material; extra == 'docs'
-Requires-Dist: mkdocs-typer==0.0.3; extra == 'docs'
-Requires-Dist: mkdocs>=1.4; extra == 'docs'
-Requires-Dist: mkdocstrings-python==1.1.2; extra == 'docs'
-Requires-Dist: mkdocstrings==0.22.0; extra == 'docs'
 Provides-Extra: io
 Requires-Dist: tifffile>=2021.6.14; extra == 'io'
-Requires-Dist: zarr<3,>=2.2; extra == 'io'
+Requires-Dist: zarr<3,>=2.15; extra == 'io'
 Provides-Extra: pyqt5
 Requires-Dist: pyqt5>=5.15.4; extra == 'pyqt5'
 Provides-Extra: pyqt6
-Requires-Dist: pyqt6<6.8,>=6.4.2; extra == 'pyqt6'
+Requires-Dist: pyqt6>=6.4.2; extra == 'pyqt6'
 Provides-Extra: pyside2
-Requires-Dist: pyside2>=5.15; extra == 'pyside2'
+Requires-Dist: pyside2>=5.15.2.1; extra == 'pyside2'
 Provides-Extra: pyside6
-Requires-Dist: pyside6<6.8,>=6.4.0; extra == 'pyside6'
-Provides-Extra: test
-Requires-Dist: msgpack; extra == 'test'
-Requires-Dist: msgspec; extra == 'test'
-Requires-Dist: pytest-cov>=4; extra == 'test'
-Requires-Dist: pytest-qt>=4; extra == 'test'
-Requires-Dist: pytest>=7.3.2; extra == 'test'
-Requires-Dist: qtpy>=2; extra == 'test'
-Requires-Dist: rich; extra == 'test'
-Requires-Dist: tifffile>=2021.6.14; extra == 'test'
-Requires-Dist: typer>=0.4.2; extra == 'test'
-Requires-Dist: xarray; extra == 'test'
-Requires-Dist: zarr<3,>=2.2; extra == 'test'
+Requires-Dist: pyside6==6.7.3; extra == 'pyside6'
 Description-Content-Type: text/markdown
 
 # pymmcore-plus

{pymmcore_plus-0.13.7 → pymmcore_plus-0.14.0}/pyproject.toml

@@ -36,13 +36,15 @@ classifiers = [
 dynamic = ["version"]
 dependencies = [
     "platformdirs >=3.0.0",
-    "numpy >=1.17.3",
-    "psygnal >=0.7",
-    "pymmcore >=10.7.0.71.0",
-    "typing-extensions",      # not actually required at runtime
-    "useq-schema >=0.7.0",
-    # until https://github.com/google/tensorstore/issues/217 is resolved
-    "tensorstore <= 0.1.71",
+    "numpy >=2.1.0; python_version >= '3.13'",
+    "numpy >=1.26.0; python_version >= '3.12'",
+    "numpy >=1.25.2",
+    "psygnal >=0.10",
+    "pymmcore >=11.2.1.71.0",
+    "typing-extensions >=4",                                   # not actually required at runtime
+    "useq-schema >=0.7.2",
+    "tensorstore >=0.1.71,!=0.1.72; python_version >= '3.13'",
+    "tensorstore >=0.1.67,!=0.1.72",
     # cli requirements included by default for now
     "typer >=0.4.2",
     "rich >=10.2.0",
@@ -52,40 +54,54 @@ dependencies = [
 # https://peps.python.org/pep-0621/#dependencies-optional-dependencies
 [project.optional-dependencies]
 cli = ["typer >=0.4.2", "rich >=10.2.0"]
-io = ["tifffile >=2021.6.14", "zarr >=2.2,<3"]
-PySide2 = ["PySide2 >=5.15"]
-PySide6 = ["PySide6 >=6.4.0,<6.8"]
+io = ["tifffile >=2021.6.14", "zarr >=2.15,<3"]
+PySide2 = ["PySide2 >=5.15.2.1"]
+PySide6 = ["PySide6 ==6.7.3"]
 PyQt5 = ["PyQt5 >=5.15.4"]
-PyQt6 = ["PyQt6 >=6.4.2,<6.8"]
-test = [
-    "msgspec",
-    "msgpack",
-    "pytest-cov >=4",
-    "pytest-qt >=4",
-    "pytest >=7.3.2",
-    "qtpy >=2",
-    "rich",
-    "typer >=0.4.2",
-    "tifffile >=2021.6.14",
-    "zarr >=2.2,<3",
-    "xarray",
-]
-dev = [
-    "ipython",
-    "mypy",
-    "pdbpp; sys_platform != 'win32'",
-    "pre-commit",
-    "ruff",
-    "tensorstore-stubs",
-]
+PyQt6 = ["PyQt6 >=6.4.2"]
+
+[dependency-groups]
 docs = [
     "mkdocs >=1.4",
-    "mkdocs-material",
+    "mkdocs-material>=9.5",
     "mkdocstrings ==0.22.0",
     "mkdocs-autorefs ==1.3.1",
     "mkdocstrings-python ==1.1.2",
     "mkdocs-typer ==0.0.3",
-    # "griffe @ git+https://github.com/tlambert03/griffe@recursion"
+]
+test = [
+    "pymmcore-plus[io]",
+    "msgspec >= 0.19",
+    "msgpack >=1",
+    "pytest-cov >=5",
+    "pytest >=8",
+    "xarray >=2024.1",
+    "pymmcore >=11.5.0.73",
+]
+test-codspeed = [{ include-group = "test" }, "pytest-codspeed >=3.2.0"]
+test-qt = ["pytest-qt >=4.4", "qtpy >=2"]
+PyQt6 = [{ include-group = 'test-qt' }, "pymmcore-plus[PyQt6]"]
+PySide6 = [{ include-group = 'test-qt' }, "pymmcore-plus[PySide6]"]
+PyQt5 = [{ include-group = 'test-qt' }, "pymmcore-plus[PyQt5]"]
+PySide2 = [{ include-group = 'test-qt' }, "pymmcore-plus[PySide2]"]
+dev = [
+    # { include-group = "docs" },
+    { include-group = "test" },
+    "PyQt6 >=6.4.2",
+    "ipython>=8.18.1",
+    "pdbpp>=0.11.6 ; sys_platform != 'win32'",
+    "mypy>=1.14.1",
+    "pre-commit>=4.1.0",
+    "ruff>=0.9.4",
+    "pydantic >2.7.4; python_version >= '3.13'",
+]
+
+[tool.uv.sources]
+pymmcore-plus = { workspace = true }
+
+[tool.uv]
+override-dependencies = [
+    "griffe @ git+https://github.com/tlambert03/griffe@recursion#egg=griffe",
 ]
 
 [project.urls]
@@ -115,6 +131,8 @@ sources = ["src"]
 [tool.ruff]
 line-length = 88
 target-version = "py39"
+fix = true
+unsafe-fixes = true
 
 [tool.ruff.lint]
 pydocstyle = { convention = "numpy" }
@@ -153,7 +171,11 @@ docstring-code-format = true
 [tool.pytest.ini_options]
 minversion = "6.0"
 testpaths = ["tests"]
-filterwarnings = ["error", "ignore:Failed to disconnect::pytestqt"]
+filterwarnings = [
+    "error",
+    "ignore:Failed to disconnect::pytestqt",
+    "ignore:numpy.core.multiarray is deprecated",
+]
 markers = ["run_last: mark a test to run last"]
 
 # https://mypy.readthedocs.io/en/stable/config_file.html

{pymmcore_plus-0.13.7 → pymmcore_plus-0.14.0}/src/pymmcore_plus/__init__.py

@@ -8,6 +8,7 @@ except PackageNotFoundError:  # pragma: no cover
     __version__ = "unknown"
 
 
+from ._accumulator import AbstractChangeAccumulator
 from ._logger import configure_logging
 from ._util import find_micromanager, use_micromanager
 from .core import (
@@ -34,6 +35,7 @@ from .core.events import CMMCoreSignaler, PCoreSignaler
 from .mda._runner import GeneratorMDASequence
 
 __all__ = [
+    "AbstractChangeAccumulator",
     "ActionType",
     "CFGCommand",
     "CFGGroup",

pymmcore_plus-0.14.0/src/pymmcore_plus/_accumulator.py

@@ -0,0 +1,258 @@
+"""Accumulate `setX` calls to a device value or property."""
+
+from __future__ import annotations
+
+import abc
+import sys
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal, TypeVar
+
+import psygnal
+
+from pymmcore_plus.core._constants import DeviceType
+from pymmcore_plus.core._mmcore_plus import CMMCorePlus
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+T = TypeVar("T")
+DT = TypeVar("DT", bound=DeviceType)
+
+
+class AbstractChangeAccumulator(ABC, Generic[T]):
+    """Abstract base class for accumulating a series of `setX` calls to a device.
+
+    A `ChangeAccumulator`` is a class that accumulates a series of `setX` calls to a
+    device, retaining an internal target value, and emitting a signal when the device
+    has reached its target and is idle. It can be shared by multiple players (e.g.
+    widgets, or other classes) that want to control the same device, and allows them all
+    to issue relative/absolute moves, and be notified when the device is idle.
+
+    A common use case is to accumulate setPosition calls made to a stage device, where
+    you might want to accumulate a series of relative moves, and snap an image only when
+    the stage is idle after reaching its target position.
+    """
+
+    finished = psygnal.Signal()
+    """Signal emitted when the device has reached its target and is idle."""
+
+    def __init__(self, zero: T) -> None:
+        self._zero = zero
+        self._reset()
+
+    def _reset(self) -> None:
+        self._base: T | None = None
+        self._delta: T | None = None
+
+    # ------------------------ Public API ------------------------
+
+    def add_relative(self, delta: T) -> None:
+        """Add a relative value to the target."""
+        if self._delta is None:
+            self._base = self._get_value()
+            self._delta = delta
+        else:
+            self._delta = self._add(self._delta, delta)
+        self._issue_move()
+
+    def set_absolute(self, target: T) -> None:
+        """Assign an absolute value to the target.
+
+        This will reset the accumulated state and issue a move to the target position.
+        After the move finishes, new `move_relative()` calls are interpreted
+        relative to *target*.
+        """
+        self._base = target  # anchor for later relatives
+        self._delta = self._zero  # target == base + delta
+        self._issue_move()
+
+    def poll_done(self) -> bool:
+        """Check if the device is done moving.
+
+        This should be called repeatedly by some event loop driver.
+
+        Returns True exactly once when:
+        1. The device is idle (not busy) AND
+        2. The last issued move command has been completed
+
+        After returning True it resets its state and will return False until the next
+        move_relative() call.
+        """
+        # if we have no base or delta, we're not moving
+        if self._delta is None:
+            return False
+
+        # if the device is busy, we're not done
+        if self._is_busy():
+            return False
+
+        # no new work, we're done
+        self._reset()
+        self.finished.emit()
+        return True
+
+    @property
+    def is_moving(self) -> bool:
+        """Returns True if the device is moving."""
+        return self._delta is not None
+
+    @property
+    def target(self) -> T | None:
+        """The target position of the stage. Or None if not moving."""
+        if self._base is None or self._delta is None:
+            return None
+        return self._add(self._base, self._delta)
+
+    # ------------------------ Public API ------------------------
+
+    def _issue_move(self) -> None:
+        # self._base and self._delta are guaranteed to be not None here
+        target = self._add(self._base, self._delta)  # type: ignore[arg-type]
+        # issue the move command
+        try:
+            self._set_value(target)
+        except Exception:  # pragma: no cover
+            from pymmcore_plus._logger import logger
+
+            logger.exception(f"Error setting {type(self)} to {target}")
+
+    # ------------------------ Abstract methods ------------------------
+
+    @abstractmethod
+    def _get_value(self) -> T:
+        """Get the current position of the device."""
+
+    @abstractmethod
+    def _set_value(self, value: T) -> None:
+        """Set the position of the device."""
+
+    @abstractmethod
+    def _add(self, a: T, b: T) -> T:
+        """Add two values together.
+
+        Provided for more complex types like sequences.
+        """
+
+    @abstractmethod
+    def _is_busy(self) -> bool:
+        """Return True if the device is busy."""
+
+
+class FloatChangeAccumulator(AbstractChangeAccumulator[float]):
+    def __init__(self) -> None:
+        super().__init__(zero=0.0)
+
+    def _add(self, a: float, b: float) -> float:
+        return a + b
+
+
+ZIP_STRICT = {"strict": True} if sys.version_info >= (3, 10) else {}
+
+
+class SequenceChangeAccumulator(AbstractChangeAccumulator[Sequence[float]]):
+    def __init__(self, sequence_length: int) -> None:
+        self.sequence_length = sequence_length
+        super().__init__(zero=[0.0] * sequence_length)
+
+    def _add(self, a: Sequence[float], b: Sequence[float]) -> Sequence[float]:
+        return [x + y for x, y in zip(a, b, **ZIP_STRICT)]
+
+
+class DeviceAccumulator(abc.ABC, Generic[DT]):
+    def __init__(
+        self,
+        *,
+        device_label: str,
+        mmcore: CMMCorePlus | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._mmcore = mmcore or CMMCorePlus.instance()
+        dev_type = self._device_type()
+        if not self._mmcore.getDeviceType(device_label) == dev_type:  # pragma: no cover
+            raise ValueError(
+                f"Cannot create {self.__class__.__name__}. "
+                f"Device {device_label!r} is not a {dev_type.name}. "
+            )
+
+        self._device_label = device_label
+        super().__init__(**kwargs)
+
+    def _is_busy(self) -> bool:
+        return self._mmcore.deviceBusy(self._device_label)
+
+    @classmethod
+    @abstractmethod
+    def _device_type(cls) -> DT:
+        """Return the device type for this class."""
+
+    _CACHE: ClassVar[dict[tuple[int, str], DeviceAccumulator]] = {}
+
+    @classmethod
+    def get_cached(cls, device: str, mmcore: CMMCorePlus | None = None) -> Self:
+        """Get a cached instance of the class for the given (device, core) pair.
+
+        This is intended to be called on the subclass for the device type you want to
+        create. For example, if you want to create a `PositionChangeAccumulator` for a
+        `StageDevice`, you would call: `PositionChangeAccumulator.get_cached(device)`.
+
+        But it may also be called on the base class, in which case it will still return
+        the correct subclass instance, but you will not have type safety on the return
+        type.
+        """
+        mmcore = mmcore or CMMCorePlus.instance()
+        cache_key = (id(mmcore), device)
+        device_type = mmcore.getDeviceType(device)
+        if cache_key not in DeviceAccumulator._CACHE:
+            if device_type == cls._device_type():
+                cls._CACHE[cache_key] = cls(device_label=device, mmcore=mmcore)
+            else:
+                for sub in cls.__subclasses__():
+                    if sub._device_type() == device_type:  # noqa: SLF001
+                        cls._CACHE[cache_key] = sub(device_label=device, mmcore=mmcore)
+                        break
+                else:
+                    raise ValueError(
+                        "No matching DeviceTypeMixin subclass found for device type "
+                        f"{device_type.name} (for device {device!r})."
+                    )
+        obj = cls._CACHE[cache_key]
+        if not isinstance(obj, cls):
+            raise TypeError(
+                f"Cannot create {cls.__name__} for {device!r}. "
+                f"Device is a {device_type!r}, not a {cls._device_type().name}. "
+            )
+        return obj
+
+
+class PositionChangeAccumulator(DeviceAccumulator, FloatChangeAccumulator):
+    """Accumulator for single axis stage devices."""
+
+    def __init__(self, device_label: str, mmcore: CMMCorePlus | None = None) -> None:
+        super().__init__(device_label=device_label, mmcore=mmcore)
+
+    @classmethod
+    def _device_type(cls) -> Literal[DeviceType.StageDevice]:
+        return DeviceType.StageDevice
+
+    def _get_value(self) -> float:
+        return self._mmcore.getPosition(self._device_label)
+
+    def _set_value(self, value: float) -> None:
+        self._mmcore.setPosition(self._device_label, value)
+
+
+class XYPositionChangeAccumulator(DeviceAccumulator, SequenceChangeAccumulator):
+    """Accumulator for XY stage devices."""
+
+    def __init__(self, device_label: str, mmcore: CMMCorePlus | None = None) -> None:
+        super().__init__(device_label=device_label, mmcore=mmcore, sequence_length=2)
+
+    @classmethod
+    def _device_type(cls) -> Literal[DeviceType.XYStageDevice]:
+        return DeviceType.XYStageDevice
+
+    def _get_value(self) -> Sequence[float]:
+        return self._mmcore.getXYPosition(self._device_label)
+
+    def _set_value(self, value: Sequence[float]) -> None:
+        self._mmcore.setXYPosition(self._device_label, *value)

{pymmcore_plus-0.13.7 → pymmcore_plus-0.14.0}/src/pymmcore_plus/core/__init__.py

@@ -1,10 +1,14 @@
 __all__ = [
     "ActionType",
+    "AutoFocusDevice",
     "CFGCommand",
     "CFGGroup",
     "CMMCorePlus",
+    "CameraDevice",
     "ConfigGroup",
     "Configuration",
+    "CoreDevice",
+    "Device",
     "Device",
     "DeviceAdapter",
     "DeviceDetectionStatus",
@@ -13,12 +17,24 @@ __all__ = [
     "DeviceProperty",
     "DeviceType",
     "FocusDirection",
+    "GalvoDevice",
+    "GenericDevice",
+    "HubDevice",
+    "ImageProcessorDevice",
     "Keyword",
+    "MagnifierDevice",
     "Metadata",
     "PixelFormat",
     "PortType",
     "PropertyType",
+    "SLMDevice",
     "SequencedEvent",
+    "SerialDevice",
+    "ShutterDevice",
+    "SignalIODevice",
+    "StageDevice",
+    "StateDevice",
+    "XYStageDevice",
     "iter_sequenced_events",
 ]
 
@@ -39,7 +55,24 @@ from ._constants import (
     PortType,
     PropertyType,
 )
-from ._device import Device
+from ._device import (
+    AutoFocusDevice,
+    CameraDevice,
+    CoreDevice,
+    Device,
+    GalvoDevice,
+    GenericDevice,
+    HubDevice,
+    ImageProcessorDevice,
+    MagnifierDevice,
+    SerialDevice,
+    ShutterDevice,
+    SignalIODevice,
+    SLMDevice,
+    StageDevice,
+    StateDevice,
+    XYStageDevice,
+)
 from ._metadata import Metadata
 from ._mmcore_plus import CMMCorePlus
 from ._property import DeviceProperty