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

pymmcore_plus/_util.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
+import datetime
 import importlib
 import os
 import platform
+import re
 import sys
 import warnings
 from collections import defaultdict
@@ -16,7 +18,9 @@ from typing import TYPE_CHECKING, cast, overload
 from platformdirs import user_data_dir
 
 if TYPE_CHECKING:
-    from typing import Any, Callable, Iterator, Literal, TypeVar
+    from collections.abc import Iterator
+    from re import Pattern
+    from typing import Any, Callable, Literal, TypeVar
 
     QtConnectionType = Literal["AutoConnection", "DirectConnection", "QueuedConnection"]
 
@@ -35,11 +39,12 @@ except ImportError:
     from contextlib import nullcontext as no_stdout
 
 
-__all__ = ["find_micromanager", "retry", "no_stdout", "signals_backend"]
+__all__ = ["find_micromanager", "no_stdout", "retry", "signals_backend"]
 
 APP_NAME = "pymmcore-plus"
 USER_DATA_DIR = Path(user_data_dir(appname=APP_NAME))
 USER_DATA_MM_PATH = USER_DATA_DIR / "mm"
+CURRENT_MM_PATH = USER_DATA_MM_PATH / ".current_mm"
 PYMMCORE_PLUS_PATH = Path(__file__).parent.parent
 
 
@@ -57,16 +62,17 @@ def find_micromanager(return_first: bool = True) -> str | None | list[str]:
     In order, this will look for:
 
     1. An environment variable named `MICROMANAGER_PATH`
-    2. A `Micro-Manager*` folder in the `pymmcore-plus` user data directory
+    2. A path stored in the `CURRENT_MM_PATH` file (set by `use_micromanager`).
+    3. A `Micro-Manager*` folder in the `pymmcore-plus` user data directory
        (this is the default install location when running `mmcore install`)
 
         - **Windows**: C:\Users\\[user]\AppData\Local\pymmcore-plus\pymmcore-plus
         - **macOS**: ~/Library/Application Support/pymmcore-plus
         - **Linux**: ~/.local/share/pymmcore-plus
 
-    3. A `Micro-Manager*` folder in the `pymmcore_plus` package directory (this is the
+    4. A `Micro-Manager*` folder in the `pymmcore_plus` package directory (this is the
        default install location when running `python -m pymmcore_plus.install`)
-    4. The default micro-manager install location:
+    5. The default micro-manager install location:
 
         - **Windows**: `C:/Program Files/`
         - **macOS**: `/Applications`
@@ -88,14 +94,25 @@ def find_micromanager(return_first: bool = True) -> str | None | list[str]:
     """
     from ._logger import logger
 
+    # we use a dict here to avoid duplicates
+    full_list: dict[str, None] = {}
+
     # environment variable takes precedence
-    full_list: list[str] = []
     env_path = os.getenv("MICROMANAGER_PATH")
     if env_path and os.path.isdir(env_path):
         if return_first:
             logger.debug("using MM path from env var: %s", env_path)
             return env_path
-        full_list.append(env_path)
+        full_list[env_path] = None
+
+    # then check for a path in CURRENT_MM_PATH
+    if CURRENT_MM_PATH.exists():
+        path = CURRENT_MM_PATH.read_text().strip()
+        if os.path.isdir(path):
+            if return_first:
+                logger.debug("using MM path from current_mm: %s", path)
+                return path
+            full_list[path] = None
 
     # then look in user_data_dir
     _folders = (p for p in USER_DATA_MM_PATH.glob("Micro-Manager*") if p.is_dir())
@@ -104,7 +121,8 @@ def find_micromanager(return_first: bool = True) -> str | None | list[str]:
         if return_first:
             logger.debug("using MM path from user install: %s", user_install[0])
             return str(user_install[0])
-        full_list.extend([str(x) for x in user_install])
+        for x in user_install:
+            full_list[str(x)] = None
 
     # then look for an installation in this folder (from `pymmcore_plus.install`)
     sfx = "_win" if os.name == "nt" else "_mac"
@@ -115,7 +133,8 @@ def find_micromanager(return_first: bool = True) -> str | None | list[str]:
         if return_first:
             logger.debug("using MM path from local install: %s", local_install[0])
             return str(local_install[0])
-        full_list.extend([str(x) for x in local_install])
+        for x in local_install:
+            full_list[str(x)] = None
 
     applications = {
         "darwin": Path("/Applications/"),
@@ -137,20 +156,76 @@ def find_micromanager(return_first: bool = True) -> str | None | list[str]:
         logger.debug("using MM path found in applications: %s", pth)
         return str(pth)
     if pth is not None:
-        full_list.append(str(pth))
-    return full_list
+        full_list[str(pth)] = None
+    return list(full_list)
 
 
-def _qt_app_is_running() -> bool:
+def _match_mm_pattern(pattern: str | Pattern[str]) -> Path | None:
+    """Locate an existing Micro-Manager folder using a regex pattern."""
+    for _path in find_micromanager(return_first=False):
+        if not isinstance(pattern, re.Pattern):
+            pattern = str(pattern)
+        if re.search(pattern, _path) is not None:
+            return Path(_path)
+    return None
+
+
+def use_micromanager(
+    path: str | Path | None = None, pattern: str | Pattern[str] | None = None
+) -> Path | None:
+    """Set the preferred Micro-Manager path.
+
+    This sets the preferred micromanager path, and persists across sessions.
+    This path takes precedence over everything *except* the `MICROMANAGER_PATH`
+    environment variable.
+
+    Parameters
+    ----------
+    path : str | Path | None
+        Path to an existing directory. This directory should contain micro-manager
+        device adapters. If `None`, the path will be determined using `pattern`.
+    pattern : str Pattern | | None
+        A regex pattern to match against the micromanager paths found by
+        `find_micromanager`. If no match is found, a `FileNotFoundError` will be raised.
+    """
+    if path is None:
+        if pattern is None:  # pragma: no cover
+            raise ValueError("One of 'path' or 'pattern' must be provided")
+        if (path := _match_mm_pattern(pattern)) is None:
+            options = "\n".join(find_micromanager(return_first=False))
+            raise FileNotFoundError(
+                f"No micromanager path found matching: {pattern!r}. Options:\n{options}"
+            )
+
+    if not isinstance(path, Path):  # pragma: no cover
+        path = Path(path)
+
+    path = path.expanduser().resolve()
+    if not path.is_dir():  # pragma: no cover
+        if not path.exists():
+            raise FileNotFoundError(f"Path not found: {path!r}")
+        raise NotADirectoryError(f"Not a directory: {path!r}")
+
+    USER_DATA_MM_PATH.mkdir(parents=True, exist_ok=True)
+    CURRENT_MM_PATH.write_text(str(path))
+    return path
+
+
+def _imported_qt_modules() -> Iterator[str]:
     for modname in {"PyQt5", "PySide2", "PyQt6", "PySide6"}:
         if modname in sys.modules:
-            try:
-                # in broken environments modname can be a namespace package...
-                # and QtWidgets will still be unavailable
-                QtWidgets = importlib.import_module(".QtWidgets", modname)
-            except ImportError:  # pragma: no cover
-                continue
-            return QtWidgets.QApplication.instance() is not None
+            yield modname
+
+
+def _qt_app_is_running() -> bool:
+    for modname in _imported_qt_modules():
+        try:
+            # in broken environments modname can be a namespace package...
+            # and QtWidgets will still be unavailable
+            QtWidgets = importlib.import_module(".QtWidgets", modname)
+        except ImportError:  # pragma: no cover
+            continue
+        return QtWidgets.QApplication.instance() is not None
     return False  # pragma: no cover
 
 
@@ -168,10 +243,11 @@ def signals_backend() -> Literal["qt", "psygnal"]:
         )
         env_var = "auto"
 
+    qt_app_running = _qt_app_is_running()
     if env_var == "auto":
-        return "qt" if _qt_app_is_running() else "psygnal"
+        return "qt" if qt_app_running else "psygnal"
     if env_var == "qt":
-        if _qt_app_is_running():
+        if qt_app_running or list(_imported_qt_modules()):
             return "qt"
         warnings.warn(
             f"{MMCORE_PLUS_SIGNALS_BACKEND} set to 'qt', but no Qt app is running. "
@@ -342,13 +418,10 @@ def _sorted_rows(data: dict, sort: str | None) -> list[tuple]:
     """Return a list of rows, sorted by the given column name."""
     rows = list(zip(*data.values()))
     if sort is not None:
-        try:
+        with suppress(ValueError):
+            # silently ignore if the sort column is not found
             sort_idx = [x.lower() for x in data].index(sort.lower())
-        except ValueError:  # pragma: no cover
-            raise ValueError(
-                f"invalid sort column: {sort!r}. Must be one of {list(data)}"
-            ) from None
-        rows.sort(key=lambda x: x[sort_idx])
+            rows.sort(key=lambda x: x[sort_idx])
     return rows
 
 
@@ -474,16 +547,25 @@ def system_info() -> dict[str, str]:
 
     This backs the `mmcore info` command in the CLI.
     """
-    import pymmcore
-
     import pymmcore_plus
 
     info = {
         "python": sys.version,
         "platform": platform.platform(),
         "pymmcore-plus": getattr(pymmcore_plus, "__version__", "err"),
-        "pymmcore": getattr(pymmcore, "__version__", "err"),
     }
+    try:
+        import pymmcore
+
+        info["pymmcore"] = getattr(pymmcore, "__version__", "err")
+    except ImportError:
+        info["pymmcore"] = ""
+    try:
+        import pymmcore_nano
+
+        info["pymmcore-nano"] = getattr(pymmcore_nano, "__version__", "err")
+    except ImportError:
+        info["pymmcore-nano"] = ""
 
     with suppress(Exception):
         core = pymmcore_plus.CMMCorePlus.instance()
@@ -515,3 +597,24 @@ def system_info() -> dict[str, str]:
                     info["qt"] = f"{API_NAME} {QT_VERSION}"
 
     return info
+
+
+if sys.version_info < (3, 11):
+
+    def _utcnow() -> datetime.datetime:
+        return datetime.datetime.utcnow()
+else:
+
+    def _utcnow() -> datetime.datetime:
+        return datetime.datetime.now(datetime.UTC)
+
+
+def timestamp() -> str:
+    """Return the current timestamp, try using local timezone, in ISO format.
+
+    YYYY-MM-DD HH:MM:SS.mmmmmm+HH:MM
+    """
+    now = _utcnow()
+    with suppress(Exception):
+        now = now.astimezone()
+    return now.isoformat()

pymmcore_plus/core/__init__.py

@@ -15,8 +15,11 @@ __all__ = [
     "FocusDirection",
     "Keyword",
     "Metadata",
+    "PixelFormat",
     "PortType",
     "PropertyType",
+    "SequencedEvent",
+    "iter_sequenced_events",
 ]
 
 from ._adapter import DeviceAdapter
@@ -32,6 +35,7 @@ from ._constants import (
     DeviceType,
     FocusDirection,
     Keyword,
+    PixelFormat,
     PortType,
     PropertyType,
 )
@@ -39,3 +43,4 @@ from ._device import Device
 from ._metadata import Metadata
 from ._mmcore_plus import CMMCorePlus
 from ._property import DeviceProperty
+from ._sequencing import SequencedEvent, iter_sequenced_events

pymmcore_plus/core/_config.py

@@ -3,15 +3,17 @@
 from __future__ import annotations
 
 from collections import defaultdict
-from typing import TYPE_CHECKING, Any, Iterable, Iterator, Tuple, overload
+from typing import TYPE_CHECKING, Any, overload
 
-import pymmcore
+import pymmcore_plus._pymmcore as pymmcore
 
 if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
     from typing_extensions import TypeAlias  # py310
 
-DevPropValueTuple: TypeAlias = Tuple[str, str, str]
-DevPropTuple: TypeAlias = Tuple[str, str]
+DevPropValueTuple: TypeAlias = tuple[str, str, str]
+DevPropTuple: TypeAlias = tuple[str, str]
 
 
 class Configuration(pymmcore.Configuration):

pymmcore_plus/core/_config_group.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Iterator, Literal, MutableMapping, overload
+from collections.abc import Iterator, MutableMapping
+from typing import TYPE_CHECKING, Any, Literal, overload
 
-import pymmcore
+import pymmcore_plus._pymmcore as pymmcore
 
 from ._config import Configuration
 from ._property import DeviceProperty
@@ -72,7 +73,7 @@ class ConfigGroup(MutableMapping[str, Configuration]):
     def __getitem__(self, configName: str) -> Configuration:
         try:
             return self._mmc.getConfigData(self._name, configName)
-        except ValueError as e:
+        except (ValueError, RuntimeError) as e:
             if configName not in self:
                 raise KeyError(
                     f"Group {self._name!r} does not have a config {configName!r}"

pymmcore_plus/core/_constants.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
-from enum import Enum, IntEnum
+from enum import Enum, IntEnum, auto
+from typing import Any, Literal
 
-import pymmcore
+import pymmcore_plus._pymmcore as pymmcore
 
 # NOTE: by using pymmcore.attributes, we guarantee that the values are the same
 # however, we also risk AttributeErrors in the future.
@@ -156,6 +157,7 @@ class PropertyType(IntEnum):
     String = pymmcore.String
     Float = pymmcore.Float
     Integer = pymmcore.Integer
+    Boolean = auto()  # not supported in pymmcore
 
     def to_python(self) -> type | None:
         return {0: None, 1: str, 2: float, 3: int}[self]
@@ -163,8 +165,31 @@ class PropertyType(IntEnum):
     def to_json(self) -> str:
         return {0: "null", 1: "string", 2: "number", 3: "integer"}[self]
 
-    def __repr__(self) -> str:
-        return getattr(self.to_python(), "__name__", "None")
+    def __repr__(self) -> Literal["undefined", "float", "int", "str"]:
+        return getattr(self.to_python(), "__name__", "undefined")
+
+    @classmethod
+    def create(cls, value: Any) -> PropertyType:
+        if isinstance(value, PropertyType):
+            return value
+        if value is None:
+            return PropertyType.Undef
+        if isinstance(value, str):
+            return PropertyType[value.lower().capitalize()]
+        if isinstance(value, type):
+            if value is float:
+                return PropertyType.Float
+            elif value is int:
+                return PropertyType.Integer
+            elif value is str:
+                return PropertyType.String
+            elif value is bool:
+                return PropertyType.Boolean
+
+        raise TypeError(
+            f"Property type must be a PropertyType enum member, "
+            f"a string, or a type. Got: {type(value)}"
+        )
 
 
 class ActionType(IntEnum):
@@ -185,13 +210,13 @@ class PortType(IntEnum):
 
 
 class FocusDirection(IntEnum):
-    FocusDirectionUnknown = pymmcore.FocusDirectionUnknown
-    FocusDirectionTowardSample = pymmcore.FocusDirectionTowardSample
-    FocusDirectionAwayFromSample = pymmcore.FocusDirectionAwayFromSample
+    Unknown = pymmcore.FocusDirectionUnknown
+    TowardSample = pymmcore.FocusDirectionTowardSample
+    AwayFromSample = pymmcore.FocusDirectionAwayFromSample
     # aliases
-    Unknown = FocusDirectionUnknown
-    TowardSample = FocusDirectionTowardSample
-    AwayFromSample = FocusDirectionAwayFromSample
+    FocusDirectionUnknown = Unknown
+    FocusDirectionTowardSample = TowardSample
+    FocusDirectionAwayFromSample = AwayFromSample
 
 
 class DeviceNotification(IntEnum):
@@ -222,6 +247,12 @@ class DeviceInitializationState(IntEnum):
 
 
 class PixelType(str, Enum):
+    """These are pixel types, as used in MMStudio and MMCoreJ wrapper.
+
+    They are only here for supporting the legacy (and probably to-be-deprecated)
+    taggedImages.
+    """
+
     UNKNOWN = ""
     GRAY8 = "GRAY8"
     GRAY16 = "GRAY16"
@@ -239,3 +270,97 @@ class PixelType(str, Enum):
                 depth, cls.UNKNOWN
             )
         return cls.GRAY32 if n_comp == 1 else cls.RGB32
+
+    def to_pixel_format(self) -> PixelFormat:
+        return {
+            self.GRAY8: PixelFormat.MONO8,
+            self.GRAY16: PixelFormat.MONO16,
+            self.GRAY32: PixelFormat.MONO32,
+            self.RGB32: PixelFormat.RGB8,
+            self.RGB64: PixelFormat.RGB16,
+        }[self]
+
+
+class PixelFormat(str, Enum):
+    """Subset of GeniCam Pixel Format names used by pymmcore-plus.
+
+    (This is similar to PixelType, but follows GeniCam standards.)
+
+    See <https://docs.baslerweb.com/pixel-format#unpacked-and-packed-pixel-formats>
+    for helpful clarifications.  Note that **unpacked** pixel formats (like
+    Mono8, Mono12, Mono16) are always 8-bit aligned. Meaning Mono12 is actually
+    a 16-bit buffer.
+
+    Attributes
+    ----------
+    MONO8 : str
+        8-bit (unpacked) monochrome pixel format.
+    MONO10 : str
+        10-bit (unpacked) monochrome pixel format. (16-bit buffer)
+    MONO12 : str
+        12-bit (unpacked) monochrome pixel format. (16-bit buffer)
+    MONO14 : str
+        14-bit (unpacked) monochrome pixel format. (16-bit buffer)
+    MONO16 : str
+        16-bit (unpacked) monochrome pixel format
+    MONO32 : str
+        32-bit (unpacked) monochrome pixel format
+    RGB8 : str
+        8-bit RGB pixel format. (24-bit buffer)
+    RGB10 : str
+        10-bit RGB pixel format. (48-bit buffer)
+    RGB12 : str
+        12-bit RGB pixel format. (48-bit buffer)
+    RGB14 : str
+        14-bit RGB pixel format. (48-bit buffer)
+    RGB16 : str
+        16-bit RGB pixel format. (48-bit buffer)
+    """
+
+    MONO8 = "Mono8"
+    MONO10 = "Mono10"
+    MONO12 = "Mono12"
+    MONO14 = "Mono14"
+    MONO16 = "Mono16"
+    MONO32 = "Mono32"
+    RGB8 = "RGB8"
+    RGB10 = "RGB10"
+    RGB12 = "RGB12"
+    RGB14 = "RGB14"
+    RGB16 = "RGB16"
+
+    @classmethod
+    def pick(cls, bit_depth: int, n_comp: int = 1) -> PixelFormat:
+        try:
+            return PIXEL_FORMATS[n_comp][bit_depth]
+        except KeyError as e:
+            raise NotImplementedError(
+                f"Unsupported Pixel Format {bit_depth=} {n_comp=}"
+            ) from e
+
+    @classmethod
+    def for_current_camera(cls, core: pymmcore.CMMCore) -> PixelFormat:
+        n_comp = core.getNumberOfComponents()
+        if n_comp == 4:
+            n_comp = 3
+        return cls.pick(core.getImageBitDepth(), n_comp)
+
+
+# map of {number of components: {bit depth: PixelFormat}}
+PIXEL_FORMATS: dict[int, dict[int, PixelFormat]] = {
+    1: {
+        8: PixelFormat.MONO8,
+        10: PixelFormat.MONO10,
+        12: PixelFormat.MONO12,
+        14: PixelFormat.MONO14,
+        16: PixelFormat.MONO16,
+        32: PixelFormat.MONO32,
+    },
+    3: {
+        8: PixelFormat.RGB8,
+        10: PixelFormat.RGB10,
+        12: PixelFormat.RGB12,
+        14: PixelFormat.RGB14,
+        16: PixelFormat.RGB16,
+    },
+}

pymmcore_plus/core/_device.py

@@ -43,12 +43,12 @@ class Device:
     >>> device.schema()  # JSON schema of device properties
     """
 
-    UNASIGNED = "__UNASIGNED__"
+    UNASSIGNED = "__UNASSIGNED__"
     propertyChanged: PSignalInstance
 
     def __init__(
         self,
-        device_label: str = UNASIGNED,
+        device_label: str = UNASSIGNED,
         mmcore: CMMCorePlus | None = None,
         adapter_name: str = "",
         device_name: str = "",
@@ -162,7 +162,7 @@ class Device:
             raise TypeError("Must specify device_name")
         if device_label:
             self.label = device_label
-        elif self.label == self.UNASIGNED:
+        elif self.label == self.UNASSIGNED:
             self.label = f"{adapter_name}-{device_name}"
 
         self._mmc.loadDevice(self.label, adapter_name, device_name)
@@ -208,7 +208,7 @@ class Device:
     def __repr__(self) -> str:
         if self.isLoaded():
             n = len(self.propertyNames())
-            props = f'{n} {"properties" if n>1 else "property"}'
+            props = f"{n} {'properties' if n > 1 else 'property'}"
             lib = f"({self.library()}::{self.name()}) "
         else:
             props = "NOT LOADED"

pymmcore_plus/core/_metadata.py

@@ -1,10 +1,10 @@
 """pythonic wrapper on pymmcore.Metadata object."""
 
-from collections.abc import Mapping
+from collections.abc import ItemsView, Iterator, KeysView, Mapping, ValuesView
 from types import new_class
-from typing import Any, ItemsView, Iterator, KeysView, ValuesView, cast
+from typing import Any, cast
 
-import pymmcore
+import pymmcore_plus._pymmcore as pymmcore
 
 _NULL = object()