pymmcore-plus 0.13.0__tar.gz → 0.13.2__tar.gz

{pymmcore_plus-0.13.0 → pymmcore_plus-0.13.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pymmcore-plus
-Version: 0.13.0
+Version: 0.13.2
 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

{pymmcore_plus-0.13.0 → pymmcore_plus-0.13.2}/src/pymmcore_plus/core/_constants.py

@@ -209,10 +209,15 @@ class PortType(IntEnum):
     HIDPort = pymmcore.HIDPort
 
 
+# NB:
+# do *not* use `pymmcore.FocusDirection...` enums here.
+# the MMCore API does not use the device enums (which is what pymmcore exposes)
+# but instead translates MM::FocusDirectionTowardSample into a different number:
+# https://github.com/micro-manager/mmCoreAndDevices/tree/MMCore/MMCore.cpp#L2063-L2074
 class FocusDirection(IntEnum):
-    Unknown = pymmcore.FocusDirectionUnknown
-    TowardSample = pymmcore.FocusDirectionTowardSample
-    AwayFromSample = pymmcore.FocusDirectionAwayFromSample
+    Unknown = 0
+    TowardSample = 1
+    AwayFromSample = -1
     # aliases
     FocusDirectionUnknown = Unknown
     FocusDirectionTowardSample = TowardSample

{pymmcore_plus-0.13.0 → pymmcore_plus-0.13.2}/src/pymmcore_plus/mda/__init__.py

@@ -1,6 +1,6 @@
 from ._engine import MDAEngine
 from ._protocol import PMDAEngine
-from ._runner import MDARunner
+from ._runner import MDARunner, SupportsFrameReady
 from ._thread_relay import mda_listeners_connected
 from .events import PMDASignaler
 
@@ -9,5 +9,6 @@ __all__ = [
     "MDARunner",
     "PMDAEngine",
     "PMDASignaler",
+    "SupportsFrameReady",
     "mda_listeners_connected",
 ]

{pymmcore_plus-0.13.0 → pymmcore_plus-0.13.2}/src/pymmcore_plus/mda/_engine.py

@@ -248,7 +248,12 @@ class MDAEngine(PMDAEngine):
                 self._mmc.setExposure(event.exposure)
             except Exception as e:
                 logger.warning("Failed to set exposure. %s", e)
-
+        if event.properties is not None:
+            try:
+                for dev, prop, value in event.properties:
+                    self._mmc.setProperty(dev, prop, value)
+            except Exception as e:
+                logger.warning("Failed to set properties. %s", e)
         if (
             # (if autoshutter wasn't set at the beginning of the sequence
             # then it never matters...)

{pymmcore_plus-0.13.0 → pymmcore_plus-0.13.2}/src/pymmcore_plus/mda/_runner.py

@@ -5,8 +5,9 @@ import warnings
 from collections.abc import Iterable, Iterator, Sequence
 from contextlib import AbstractContextManager, nullcontext
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 from unittest.mock import MagicMock
+from weakref import WeakSet
 
 from useq import MDASequence
 
@@ -17,13 +18,40 @@ from ._thread_relay import mda_listeners_connected
 from .events import PMDASignaler, _get_auto_MDA_callback_class
 
 if TYPE_CHECKING:
-    from typing import TypeAlias
+    from typing import Protocol, TypeAlias
 
+    import numpy as np
     from useq import MDAEvent
 
+    from pymmcore_plus.metadata.schema import FrameMetaV1
+
     from ._engine import MDAEngine
 
-    SingleOutput: TypeAlias = Path | str | object
+    class FrameReady0(Protocol):
+        """Data handler with a no-argument `frameReady` method."""
+
+        def frameReady(self) -> Any: ...
+
+    class FrameReady1(Protocol):
+        """Data handler with a `frameReady` method that takes `(image,)` ."""
+
+        def frameReady(self, img: np.ndarray, /) -> Any: ...
+
+    class FrameReady2(Protocol):
+        """Data handler with a `frameReady` method that takes `(image, event)`."""
+
+        def frameReady(self, img: np.ndarray, event: MDAEvent, /) -> Any: ...
+
+    class FrameReady3(Protocol):
+        """Data handler with a `frameReady` method that takes `(image, event, meta)`."""
+
+        def frameReady(
+            self, img: np.ndarray, event: MDAEvent, meta: FrameMetaV1, /
+        ) -> Any: ...
+
+
+SupportsFrameReady: TypeAlias = "FrameReady0 | FrameReady1 | FrameReady2 | FrameReady3"
+SingleOutput: TypeAlias = "Path | str | SupportsFrameReady"
 
 MSG = (
     "This sequence is a placeholder for a generator of events with unknown "
@@ -67,7 +95,7 @@ class MDARunner:
         self._paused = False
         self._paused_time: float = 0
         self._pause_interval: float = 0.1  # sec to wait between checking pause state
-
+        self._handlers: WeakSet[SupportsFrameReady] = WeakSet()
         self._canceled = False
         self._sequence: MDASequence | None = None
         # timer for the full sequence, reset only once at the beginning of the sequence
@@ -189,6 +217,10 @@ class MDARunner:
             - A handler object that implements the `DataHandler` protocol, currently
                 meaning it has a `frameReady` method.  See `mda_listeners_connected`
                 for more details.
+
+            During the course of the sequence, the `get_output_handlers` method can be
+            used to get the currently connected output handlers (including those that
+            were created automatically based on file paths).
         """
         error = None
         sequence = events if isinstance(events, MDASequence) else GeneratorMDASequence()
@@ -206,6 +238,31 @@ class MDARunner:
         if error is not None:
             raise error
 
+    def get_output_handlers(self) -> tuple[SupportsFrameReady, ...]:
+        """Return the data handlers that are currently connected.
+
+        Output handlers are connected by passing them to the `output` parameter of the
+        `run` method; the run method accepts objects with a `frameReady` method *or*
+        strings representing paths.  If a string is passed, a handler will be created
+        internally.
+
+        This method returns a tuple of currently connected handlers, including those
+        that were explicitly passed to `run()`, as well as those that were created based
+        on file paths.  Internally, handlers are held by weak references, so if you want
+        the handler to persist, you must keep a reference to it.  The only guaranteed
+        API that the handler will have is the `frameReady` method, but it could be any
+        user-defined object that implements that method.
+
+        Handlers are cleared each time `run()` is called, (but not at the end
+        of the sequence).
+
+        Returns
+        -------
+        tuple[SupportsFrameReady, ...]
+            Tuple of objects that (minimally) support the `frameReady` method.
+        """
+        return tuple(self._handlers)
+
     def seconds_elapsed(self) -> float:
         """Return the number of seconds since the start of the acquisition."""
         return time.perf_counter() - self._sequence_t0
@@ -228,48 +285,31 @@ class MDARunner:
         if isinstance(output, (str, Path)) or not isinstance(output, Sequence):
             output = [output]
 
-        # convert all items to handler objects
-        handlers: list[Any] = []
+        # convert all items to handler objects, preserving order
+        _handlers: list[SupportsFrameReady] = []
         for item in output:
             if isinstance(item, (str, Path)):
-                handlers.append(self._handler_for_path(item))
+                _handlers.append(self._handler_for_path(item))
             else:
-                # TODO: better check for valid handler protocol
-                # quick hack for now.
-                if not hasattr(item, "frameReady"):
+                if not callable(getattr(item, "frameReady", None)):
                     raise TypeError(
-                        "Output handlers must have a frameReady method. "
+                        "Output handlers must have a callable frameReady method. "
                         f"Got {item} with type {type(item)}."
                     )
-                handlers.append(item)
+                _handlers.append(item)
 
-        return mda_listeners_connected(*handlers, mda_events=self._signals)
+        self._handlers.clear()
+        self._handlers.update(_handlers)
+        return mda_listeners_connected(*_handlers, mda_events=self._signals)
 
-    def _handler_for_path(self, path: str | Path) -> object:
+    def _handler_for_path(self, path: str | Path) -> SupportsFrameReady:
         """Convert a string or Path into a handler object.
 
         This method picks from the built-in handlers based on the extension of the path.
         """
-        path = str(Path(path).expanduser().resolve())
-        if path.endswith(".zarr"):
-            from pymmcore_plus.mda.handlers import OMEZarrWriter
-
-            return OMEZarrWriter(path)
-
-        if path.endswith((".tiff", ".tif")):
-            from pymmcore_plus.mda.handlers import OMETiffWriter
-
-            return OMETiffWriter(path)
-
-        # FIXME: ugly hack for the moment to represent a non-existent directory
-        # there are many features that ImageSequenceWriter supports, and it's unclear
-        # how to infer them all from a single string.
-        if not (Path(path).suffix or Path(path).exists()):
-            from pymmcore_plus.mda.handlers import ImageSequenceWriter
-
-            return ImageSequenceWriter(path)
+        from pymmcore_plus.mda.handlers import handler_for_path
 
-        raise ValueError(f"Could not infer a writer handler for path: '{path}'")
+        return cast("SupportsFrameReady", handler_for_path(path))
 
     def _run(self, engine: PMDAEngine, events: Iterable[MDAEvent]) -> None:
         """Main execution of events, inside the try/except block of `run`."""

pymmcore_plus-0.13.2/src/pymmcore_plus/mda/handlers/__init__.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from ._img_sequence_writer import ImageSequenceWriter
+from ._ome_tiff_writer import OMETiffWriter
+from ._ome_zarr_writer import OMEZarrWriter
+from ._tensorstore_handler import TensorStoreHandler
+
+__all__ = [
+    "ImageSequenceWriter",
+    "OMETiffWriter",
+    "OMEZarrWriter",
+    "TensorStoreHandler",
+    "handler_for_path",
+]
+
+
+def handler_for_path(path: str | Path) -> object:
+    """Convert a string or Path into a handler object.
+
+    This method picks from the built-in handlers based on the extension of the path.
+    """
+    if str(path).rstrip("/").rstrip(":").lower() == "memory":
+        return TensorStoreHandler(kvstore="memory://")
+
+    path = str(Path(path).expanduser().resolve())
+    if path.endswith(".zarr"):
+        return OMEZarrWriter(path)
+
+    if path.endswith((".tiff", ".tif")):
+        return OMETiffWriter(path)
+
+    # FIXME: ugly hack for the moment to represent a non-existent directory
+    # there are many features that ImageSequenceWriter supports, and it's unclear
+    # how to infer them all from a single string.
+    if not (Path(path).suffix or Path(path).exists()):
+        return ImageSequenceWriter(path)
+
+    raise ValueError(f"Could not infer a writer handler for path: '{path}'")

{pymmcore_plus-0.13.0 → pymmcore_plus-0.13.2}/src/pymmcore_plus/mda/handlers/_img_sequence_writer.py

@@ -22,6 +22,8 @@ if TYPE_CHECKING:
     import useq
     from typing_extensions import TypeAlias  # py310
 
+    from pymmcore_plus.metadata.schema import FrameMetaV1
+
     ImgWriter: TypeAlias = Callable[[str, npt.NDArray], Any]
 
 FRAME_KEY = "frame"
@@ -118,7 +120,7 @@ class ImageSequenceWriter:
             shutil.rmtree(self._directory)
 
         # ongoing dict of frame meta... stored for easy rewrite without reading
-        self._frame_metadata: dict[str, dict] = {}
+        self._frame_metadata: dict[str, FrameMetaV1] = {}
         self._frame_meta_file = self._directory.joinpath(self.FRAME_META_PATH)
         self._seq_meta_file = self._directory.joinpath(self.SEQ_META_PATH)
 
@@ -186,7 +188,9 @@ class ImageSequenceWriter:
         # write final frame metadata to disk
         self._frame_meta_file.write_bytes(json_dumps(self._frame_metadata, indent=2))
 
-    def frameReady(self, frame: np.ndarray, event: useq.MDAEvent, meta: dict) -> None:
+    def frameReady(
+        self, frame: np.ndarray, event: useq.MDAEvent, meta: FrameMetaV1, /
+    ) -> None:
         """Write a frame to disk."""
         frame_idx = next(self._counter)
         if self._name_template:

{pymmcore_plus-0.13.0 → pymmcore_plus-0.13.2}/src/pymmcore_plus/mda/handlers/_tensorstore_handler.py

@@ -111,6 +111,8 @@ class TensorStoreHandler:
         self.delete_existing = delete_existing
         self.spec = spec
 
+        self._current_sequence: useq.MDASequence | None = None
+
         # storage of individual frame metadata
         # maps position key to list of frame metadata
         self.frame_metadatas: list[tuple[useq.MDAEvent, FrameMetaV1]] = []
@@ -176,13 +178,25 @@ class TensorStoreHandler:
 
         return cls(path=path, **kwargs)
 
-    def sequenceStarted(self, seq: useq.MDASequence, meta: SummaryMetaV1) -> None:
-        """On sequence started, simply store the sequence."""
+    def reset(self, sequence: useq.MDASequence) -> None:
+        """Reset state to prepare for new `sequence`."""
         self._frame_index = 0
         self._store = None
         self._futures.clear()
         self.frame_metadatas.clear()
-        self.current_sequence = seq
+        self._current_sequence = sequence
+
+    @property
+    def current_sequence(self) -> useq.MDASequence | None:
+        """Return current sequence, or none.
+
+        Use `.reset()` to initialize the handler for a new sequence.
+        """
+        return self._current_sequence
+
+    def sequenceStarted(self, seq: useq.MDASequence, meta: SummaryMetaV1) -> None:
+        """On sequence started, simply store the sequence."""
+        self.reset(seq)
 
     def sequenceFinished(self, seq: useq.MDASequence) -> None:
         """On sequence finished, clear the current sequence."""
@@ -199,7 +213,7 @@ class TensorStoreHandler:
             self.finalize_metadata()
 
     def frameReady(
-        self, frame: np.ndarray, event: useq.MDAEvent, meta: FrameMetaV1
+        self, frame: np.ndarray, event: useq.MDAEvent, meta: FrameMetaV1, /
     ) -> None:
         """Write frame to the zarr array for the appropriate position."""
         if self._store is None:

{pymmcore_plus-0.13.0 → pymmcore_plus-0.13.2}/src/pymmcore_plus/mocks.py

@@ -28,9 +28,7 @@ class MockSequenceableCore(MagicMock):
             self.loadExposureSequence.return_value = None
             self.loadStageSequence.return_value = None
             self.loadXYStageSequence.return_value = None
-            # TODO: add support in pymmcore-nano
-            if hasattr(CMMCorePlus, "loadSLMSequence"):
-                self.loadSLMSequence.return_value = None
+            self.loadSLMSequence.return_value = None
 
             self.loadPropertySequence.return_value = None
 

{pymmcore_plus-0.13.0 → pymmcore_plus-0.13.2}/src/pymmcore_plus/model/_config_file.py

@@ -209,18 +209,28 @@ def run_command(line: str, scope: Microscope) -> None:
         return
 
     exec_cmd, expected_n_args = COMMAND_EXECUTORS[command]
+    should_raise = command in SHOULD_RAISE
 
     if (nargs := len(args) + 1) not in expected_n_args:
         exp_str = " or ".join(map(str, expected_n_args))
-        raise ValueError(
+        msg = (
             f"Invalid configuration line encountered for command {cmd_name}. "
             f"Expected {exp_str} arguments, got {nargs}: {line!r}"
         )
+        if should_raise:
+            raise ValueError(msg)
+        else:
+            warnings.warn(msg, RuntimeWarning, stacklevel=2)
+            return
 
     try:
         exec_cmd(scope, args)
     except Exception as exc:
-        raise ValueError(f"Error executing command {line!r}: {exc}") from exc
+        if should_raise:
+            raise ValueError(f"Error executing command {line!r}: {exc}") from exc
+        warnings.warn(
+            f"Failed to execute command {line!r}: {exc}", RuntimeWarning, stacklevel=2
+        )
 
 
 def _exec_Device(scope: Microscope, args: Sequence[str]) -> None:
@@ -352,3 +362,6 @@ COMMAND_EXECUTORS: dict[CFGCommand, tuple[Executor, set[int]]] = {
     CFGCommand.ParentID: (_exec_ParentID, {3}),
     CFGCommand.FocusDirection: (_exec_FocusDirection, {3}),
 }
+
+# Commands that should raise when fail
+SHOULD_RAISE = {CFGCommand.Device, CFGCommand.Property}

{pymmcore_plus-0.13.0 → pymmcore_plus-0.13.2}/tests/test_mda.py

@@ -49,19 +49,33 @@ def test_mda_waiting(core: CMMCorePlus) -> None:
 
 def test_setting_position(core: CMMCorePlus) -> None:
     core.mda._running = True
-    event1 = MDAEvent(exposure=123, x_pos=123, y_pos=456, z_pos=1)
+    event1 = MDAEvent(
+        exposure=123,
+        x_pos=123,
+        y_pos=456,
+        z_pos=1,
+        properties=[("Camera", "TestProperty1", 0.05)],
+    )
     core.mda.engine.setup_event(event1)
     assert tuple(core.getXYPosition()) == (123, 456)
     assert core.getPosition() == 1
     assert core.getExposure() == 123
+    assert core.getProperty("Camera", "TestProperty1") == "0.0500"
 
     # check that we aren't check things like: if event.x_pos
     # because then we will not set to zero
-    event2 = MDAEvent(exposure=321, x_pos=0, y_pos=0, z_pos=0)
+    event2 = MDAEvent(
+        exposure=321,
+        x_pos=0,
+        y_pos=0,
+        z_pos=0,
+        properties=[("Camera", "TestProperty2", -0.07)],
+    )
     core.mda.engine.setup_event(event2)
     assert tuple(core.getXYPosition()) == (0, 0)
     assert core.getPosition() == 0
     assert core.getExposure() == 321
+    assert core.getProperty("Camera", "TestProperty2") == "-0.0700"
 
 
 class BrokenEngine:
@@ -450,3 +464,29 @@ def test_queue_mda(core: CMMCorePlus) -> None:
     # make sure that the engine's iterator was NOT used when running an iter(Queue)
     mock_engine.event_iterator.assert_not_called()
     assert mock_engine.setup_event.call_count == 2
+
+
+def test_get_handlers(core: CMMCorePlus) -> None:
+    """Test that we can get the handlers"""
+    runner = core.mda
+
+    assert not runner.get_output_handlers()
+    on_start_names: list[str] = []
+    on_finish_names: list[str] = []
+
+    @runner.events.sequenceStarted.connect
+    def _on_start() -> None:
+        on_start_names.extend([type(h).__name__ for h in runner.get_output_handlers()])
+
+    @runner.events.sequenceFinished.connect
+    def _on_end() -> None:
+        on_finish_names.extend([type(h).__name__ for h in runner.get_output_handlers()])
+
+    runner.run([MDAEvent()], output="memory://")
+
+    # weakref is used to store the handlers,
+    # handlers should be cleared after the sequence is finished
+    assert not runner.get_output_handlers()
+    # but they should have been available during start and finish events
+    assert on_start_names == ["TensorStoreHandler"]
+    assert on_finish_names == ["TensorStoreHandler"]

{pymmcore_plus-0.13.0 → pymmcore_plus-0.13.2}/tests/test_model.py

@@ -4,8 +4,6 @@ from pathlib import Path
 
 import pytest
 
-import pymmcore_plus
-import pymmcore_plus._pymmcore
 from pymmcore_plus import CMMCorePlus, DeviceType, find_micromanager
 from pymmcore_plus.metadata import summary_metadata
 from pymmcore_plus.model import CoreDevice, Device, Microscope
@@ -142,46 +140,47 @@ def test_load_errors() -> None:
         model.load_config("Property,A,B,C,D,E")
     with pytest.raises(ValueError, match="not an integer"):
         model.load_config("Property,Core,Initialize,NotAnInt")
-    with pytest.raises(ValueError, match="not an integer"):
+    model.load_config("Device,Dichroic,DemoCamera,DWheel")  # fine
+    with pytest.warns(RuntimeWarning, match="not an integer"):
         model.load_config(
             """
             Device,Dichroic,DemoCamera,DWheel
             Label,Dichroic,NotAnInt,Q505LP
             """
         )
-    with pytest.raises(ValueError, match="'NotAPreset' not found"):
+    with pytest.warns(RuntimeWarning, match="'NotAPreset' not found"):
         model.load_config("PixelSize_um,NotAPreset,0.5")
-    with pytest.raises(ValueError, match="Expected a float"):
+    with pytest.warns(RuntimeWarning, match="Expected a float"):
         model.load_config(
             """
             ConfigPixelSize,Res40x,Objective,Label,Nikon 40X Plan Flueor ELWD
             PixelSize_um,Res40x,NotAFloat
             """
         )
-    with pytest.raises(ValueError, match="'Res10x' not found"):
+    with pytest.warns(RuntimeWarning, match="'Res10x' not found"):
         model.load_config("PixelSizeAffine,Res10x,1.0,0.0,0.0,0.0,1.1,0.0")
-    with pytest.raises(ValueError, match="Expected 8 arguments, got 5"):
+    with pytest.warns(RuntimeWarning, match="Expected 8 arguments, got 5"):
         model.load_config(
             """
             ConfigPixelSize,Res40x,Objective,Label,Nikon 40X Plan Flueor ELWD
             PixelSizeAffine,Res40x,1.0,0.0,0.0
             """
         )
-    with pytest.raises(ValueError, match="Expected 6 floats"):
+    with pytest.warns(RuntimeWarning, match="Expected 6 floats"):
         model.load_config(
             """
             ConfigPixelSize,Res40x,Objective,Label,Nikon 40X Plan Flueor ELWD
             PixelSizeAffine,Res40x,1.0,0.0,0.0,0.0,1.1,NoFloat
             """
         )
-    with pytest.raises(ValueError, match="Expected a float"):
+    with pytest.warns(RuntimeWarning, match="Expected a float"):
         model.load_config(
             """
             Device,Shutter,DemoCamera,DShutter
             Delay,Shutter,NotAFloat
             """
         )
-    with pytest.raises(ValueError, match="not a valid FocusDirection"):
+    with pytest.warns(RuntimeWarning, match="not a valid FocusDirection"):
         model.load_config(
             """
             Device,Z,DemoCamera,DStage
@@ -201,10 +200,6 @@ def test_scope_errs():
         Microscope(devices=[CoreDevice()])
 
 
-@pytest.mark.skipif(
-    pymmcore_plus._pymmcore.BACKEND == "pymmcore-nano",
-    reason="This is still hanging on pymmcore-nano",
-)
 def test_apply():
     core1 = CMMCorePlus()
     core1.loadSystemConfiguration()

pymmcore_plus-0.13.0/src/pymmcore_plus/mda/handlers/__init__.py

@@ -1,11 +0,0 @@
-from ._img_sequence_writer import ImageSequenceWriter
-from ._ome_tiff_writer import OMETiffWriter
-from ._ome_zarr_writer import OMEZarrWriter
-from ._tensorstore_handler import TensorStoreHandler
-
-__all__ = [
-    "ImageSequenceWriter",
-    "OMETiffWriter",
-    "OMEZarrWriter",
-    "TensorStoreHandler",
-]