pymmcore-plus 0.15.4__py3-none-any.whl → 0.17.0__py3-none-any.whl

pymmcore_plus/_util.py

@@ -2,9 +2,9 @@ from __future__ import annotations
 
 import datetime
 import importlib
+import importlib.metadata
 import os
 import platform
-import re
 import sys
 import warnings
 from collections import defaultdict
@@ -17,9 +17,10 @@ from typing import TYPE_CHECKING, cast, overload
 
 from platformdirs import user_data_dir
 
+from . import _discovery
+
 if TYPE_CHECKING:
     from collections.abc import Iterator
-    from re import Pattern
     from typing import Any, Callable, Literal, TypeVar
 
     QtConnectionType = Literal["AutoConnection", "DirectConnection", "QueuedConnection"]
@@ -39,213 +40,14 @@ except ImportError:
     from contextlib import nullcontext as no_stdout
 
 
-__all__ = ["find_micromanager", "no_stdout", "retry", "signals_backend"]
+__all__ = ["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
-
-
-@overload
-def find_micromanager(return_first: Literal[True] = True) -> str | None: ...
-
-
-@overload
-def find_micromanager(return_first: Literal[False]) -> list[str]: ...
-
-
-def find_micromanager(return_first: bool = True) -> str | None | list[str]:
-    r"""Locate a Micro-Manager folder (for device adapters).
-
-    In order, this will look for:
-
-    1. An environment variable named `MICROMANAGER_PATH`
-    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
-
-    4. A `Micro-Manager*` folder in the `pymmcore_plus` package directory (this is the
-       default install location when running `python -m pymmcore_plus.install`)
-    5. The default micro-manager install location:
-
-        - **Windows**: `C:/Program Files/`
-        - **macOS**: `/Applications`
-        - **Linux**: `/usr/local/lib`
-
-    !!! note
-
-        This function is used by [`pymmcore_plus.CMMCorePlus`][] to locate the
-        micro-manager device adapters.  By default, the output of this function
-        is passed to
-        [`setDeviceAdapterSearchPaths`][pymmcore_plus.CMMCorePlus.setDeviceAdapterSearchPaths]
-        when creating a new `CMMCorePlus` instance.
-
-    Parameters
-    ----------
-    return_first : bool, optional
-        If True (default), return the first found path.  If False, return a list of
-        all found paths.
-    """
-    from ._logger import logger
-
-    # we use a dict here to avoid duplicates, while retaining order
-    full_list: dict[str, None] = {}
-
-    # environment variable takes precedence
-    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[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 for mm-device-adapters
-    with suppress(ImportError):
-        import mm_device_adapters
-
-        from . import _pymmcore
-
-        mm_dev_div = mm_device_adapters.__version__.split(".")[0]
-        pymm_div = str(_pymmcore.version_info.device_interface)
-
-        if pymm_div != mm_dev_div:  # pragma: no cover
-            warnings.warn(
-                "mm-device-adapters installed, but its device interface "
-                f"version ({mm_dev_div}) "
-                f"does not match the device interface version of {_pymmcore.BACKEND}"
-                f"({pymm_div}). You may wish to run"
-                f" `pip install --force-reinstall mm-device-adapters=={pymm_div}`. "
-                "mm-device-adapters will be ignored.",
-                stacklevel=2,
-            )
-        else:
-            path = mm_device_adapters.device_adapter_path()
-            if return_first:
-                logger.debug("using MM path from mm-device-adapters: %s", path)
-                return str(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())
-    if user_install := sorted(_folders, reverse=True):
-        if return_first and (
-            first := next(
-                (x for x in user_install if _mm_path_has_compatible_div(x)), None
-            )
-        ):
-            logger.debug("using MM path from user install: %s", first)
-            return str(first)
-        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"
-    local_install = [
-        p for p in PYMMCORE_PLUS_PATH.glob(f"**/Micro-Manager*{sfx}") if p.is_dir()
-    ]
-    if local_install:
-        if return_first and (
-            first := next(
-                (x for x in local_install if _mm_path_has_compatible_div(x)), None
-            )
-        ):  # pragma: no cover
-            logger.debug("using MM path from local install: %s", first)
-            return str(first)
-        for x in local_install:
-            full_list[str(x)] = None
-
-    applications = {
-        "darwin": Path("/Applications/"),
-        "win32": Path("C:/Program Files/"),
-        "linux": Path("/usr/local/lib"),
-    }
-    if sys.platform not in applications:
-        raise NotImplementedError(
-            f"MM autodiscovery not implemented for platform: {sys.platform}"
-        )
-    app_path = applications[sys.platform]
-    pth = next(app_path.glob("[m,M]icro-[m,M]anager*"), None)
-    if return_first:
-        if pth and _mm_path_has_compatible_div(pth):  # pragma: no cover
-            logger.debug("using MM path found in applications: %s", pth)
-            return str(pth)
-        from . import _pymmcore
-
-        div = _pymmcore.version_info.device_interface
-        logger.error(
-            f"could not find micromanager directory for device interface {div}. "
-            "Please run 'mmcore install'"
-        )
-        return None
-    if pth is not None:
-        full_list[str(pth)] = None
-    return list(full_list)
-
-
-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
+PYMM_SIGNALS_BACKEND = "PYMM_SIGNALS_BACKEND"
 
 
 def _imported_qt_modules() -> Iterator[str]:
@@ -266,9 +68,6 @@ def _qt_app_is_running() -> bool:
     return False  # pragma: no cover
 
 
-PYMM_SIGNALS_BACKEND = "PYMM_SIGNALS_BACKEND"
-
-
 def signals_backend() -> Literal["qt", "psygnal"]:
     """Return the name of the event backend to use."""
     env_var = os.environ.get(PYMM_SIGNALS_BACKEND, "auto").lower()
@@ -302,8 +101,6 @@ def retry(
     delay: float | None = ...,
     logger: Callable[[str], Any] | None = ...,
 ) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
-
-
 @overload
 def retry(
     func: Callable[P, R],
@@ -312,8 +109,6 @@ def retry(
     delay: float | None = ...,
     logger: Callable[[str], Any] | None = ...,
 ) -> Callable[P, R]: ...
-
-
 def retry(
     func: Callable[P, R] | None = None,
     tries: int = 3,
@@ -609,7 +404,7 @@ def system_info() -> dict[str, str]:
         info["core-version-info"] = core.getVersionInfo()
         info["api-version-info"] = core.getAPIVersionInfo()
 
-    if (mm_path := find_micromanager()) is not None:
+    if (mm_path := _discovery.find_micromanager()) is not None:
         path = str(Path(mm_path).resolve())
         path = path.replace(os.path.expanduser("~"), "~")  # privacy
         info["adapter-path"] = path
@@ -628,10 +423,10 @@ def system_info() -> dict[str, str]:
             info[pkg] = importlib.metadata.version(pkg)
 
             if pkg == "pymmcore-widgets":
-                with suppress(ImportError):
-                    from qtpy import API_NAME, QT_VERSION
+                with suppress(ImportError, AttributeError):
+                    import qtpy
 
-                    info["qt"] = f"{API_NAME} {QT_VERSION}"
+                    info["qt"] = f"{qtpy.API_NAME} {qtpy.QT_VERSION}"
 
     return info
 
@@ -655,34 +450,3 @@ def timestamp() -> str:
     with suppress(Exception):
         now = now.astimezone()
     return now.isoformat()
-
-
-def get_device_interface_version(lib_path: str | Path) -> int:
-    """Return the device interface version from the given library path."""
-    import ctypes
-
-    if sys.platform.startswith("win"):
-        lib = ctypes.WinDLL(str(lib_path))
-    else:
-        lib = ctypes.CDLL(str(lib_path))
-
-    try:
-        func = lib.GetDeviceInterfaceVersion
-    except AttributeError:
-        raise RuntimeError(
-            f"Function 'GetDeviceInterfaceVersion' not found in {lib_path}"
-        ) from None
-
-    func.restype = ctypes.c_long
-    func.argtypes = []
-    return func()  # type: ignore[no-any-return]
-
-
-def _mm_path_has_compatible_div(folder: Path | str) -> bool:
-    from . import _pymmcore
-
-    div = _pymmcore.version_info.device_interface
-    for lib_path in Path(folder).glob("*mmgr_dal*"):
-        with suppress(Exception):
-            return get_device_interface_version(lib_path) == div
-    return False  # pragma: no cover

pymmcore_plus/core/_device.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import weakref
 from typing import TYPE_CHECKING, Any, Literal, overload
 
 from ._constants import DeviceType, FocusDirection, Keyword
@@ -34,6 +35,12 @@ class Device:
         Device label assigned to this device.
     mmcore : CMMCorePlus
         CMMCorePlus instance that owns this device.
+    device_type : DeviceType or Device subclass, optional
+        The type of device to create. If not specified, the type will be inferred
+        from the core if the device is already loaded. If the device is not loaded,
+        an error will be raised. This parameter is mainly intended for usage when
+        calling from `CMMCorePlus.getDeviceObject()`.  Otherwise, prefer using
+        `[SpecificDeviceSubclass].create()`.
 
     Examples
     --------
@@ -56,14 +63,39 @@ class Device:
     propertyChanged: PSignalInstance
 
     @classmethod
-    def create(cls, device_label: str, mmcore: CMMCorePlus) -> Self:
-        sub_cls = cls.get_subclass(device_label, mmcore)
+    def create(
+        cls,
+        device_label: str,
+        mmcore: CMMCorePlus,
+        device_type: type[Device] | DeviceType = DeviceType.Any,
+    ) -> Self:
+        if device_type in {DeviceType.Any, DeviceType.Unknown}:
+            try:
+                sub_cls = cls.get_subclass(device_label, mmcore)
+            except RuntimeError as e:
+                raise RuntimeError(
+                    f"Could not determine device type for {device_label}. "
+                    "If you are preloading a device object, "
+                    "please specify `device_type` as a `pymmcore_plus.DeviceType`."
+                ) from e
+        else:
+            if isinstance(device_type, type) and issubclass(device_type, Device):
+                sub_cls = device_type
+            elif isinstance(device_type, DeviceType):
+                sub_cls = _TYPE_MAP[device_type]
+            else:
+                raise TypeError(
+                    f"Invalid device_type: {device_type!r}.  Must be a "
+                    "pymmcore_plus `DeviceType` or `Device` subclass."
+                )
+
         # make sure it's an error to call this class method on a subclass with
         # a non-matching type
-        if issubclass(sub_cls, cls):
-            return sub_cls(device_label, mmcore)
-        dev_type = mmcore.getDeviceType(device_label).name
-        raise TypeError(f"Cannot cast {dev_type} {device_label!r} to {cls}")
+        if not issubclass(sub_cls, cls):
+            dev_type = mmcore.getDeviceType(device_label).name
+            raise TypeError(f"Cannot cast {dev_type} {device_label!r} to {cls}")
+
+        return sub_cls(device_label, mmcore)
 
     @classmethod
     def get_subclass(cls, device_label: str, mmcore: CMMCorePlus) -> type[Device]:
@@ -82,17 +114,18 @@ class Device:
         if mmcore is None:
             from ._mmcore_plus import CMMCorePlus
 
-            self._mmc = CMMCorePlus.instance()
+            mmcore = CMMCorePlus.instance()
         else:
-            self._mmc = mmcore
+            mmcore = mmcore
 
+        self._mmc_ref = weakref.ref(mmcore)
         self._label = device_label
         self._type = None
         if self.isLoaded():
-            adapter_name = self._mmc.getDeviceLibrary(device_label)
-            device_name = self._mmc.getDeviceName(device_label)
-            description = self._mmc.getDeviceDescription(device_label)
-            type = self._mmc.getDeviceType(device_label)  # noqa: A001
+            adapter_name = mmcore.getDeviceLibrary(device_label)
+            device_name = mmcore.getDeviceName(device_label)
+            description = mmcore.getDeviceDescription(device_label)
+            type = mmcore.getDeviceType(device_label)  # noqa: A001
             if self.type() != type:
                 raise TypeError(
                     f"Cannot create loaded device with label {device_label!r} and type "
@@ -103,7 +136,18 @@ class Device:
         self._device_name = device_name
         self._type = type
         self._description = description
-        self.propertyChanged = _DevicePropValueSignal(device_label, None, self._mmc)
+        self.propertyChanged = _DevicePropValueSignal(device_label, None, mmcore)
+
+    @property
+    def _mmc(self) -> CMMCorePlus:
+        """Return the `CMMCorePlus` instance to which this Device is bound."""
+        mmc = self._mmc_ref()
+        if mmc is None:  # pragma: no cover
+            raise RuntimeError(
+                "The CMMCorePlus instance to which this Device "
+                "is bound has been garbage collected."
+            )
+        return mmc
 
     @property
     def label(self) -> str:

pymmcore_plus/core/_mmcore_plus.py

@@ -27,8 +27,9 @@ from psygnal import SignalInstance
 from typing_extensions import deprecated
 
 import pymmcore_plus._pymmcore as pymmcore
+from pymmcore_plus._discovery import find_micromanager
 from pymmcore_plus._logger import current_logfile, logger
-from pymmcore_plus._util import find_micromanager, print_tabular_data
+from pymmcore_plus._util import print_tabular_data
 from pymmcore_plus.mda import MDAEngine, MDARunner, PMDAEngine
 from pymmcore_plus.metadata.functions import summary_metadata
 
@@ -334,8 +335,10 @@ class CMMCorePlus(pymmcore.CMMCore):
     def __del__(self) -> None:
         if hasattr(self, "_weak_clean"):
             atexit.unregister(self._weak_clean)
+
         try:
             super().registerCallback(None)
+
             self.reset()
             # clean up logging
             self.setPrimaryLogFile("")
@@ -517,7 +520,12 @@ class CMMCorePlus(pymmcore.CMMCore):
         **Why Override?** The returned [`pymmcore_plus.FocusDirection`][] enum is more
         interpretable than the raw `int` returned by `pymmcore`
         """
-        return FocusDirection(super().getFocusDirection(stageLabel))
+        try:
+            return FocusDirection(super().getFocusDirection(stageLabel))
+        except (ValueError, TypeError):
+            # On some platforms (notably Windows), device adapters may return
+            # invalid values that cannot be converted to FocusDirection enum.
+            return FocusDirection.Unknown
 
     def getPropertyType(self, label: str, propName: str) -> PropertyType:
         """Return the intrinsic property type for a given device and property.
@@ -1260,18 +1268,7 @@ class CMMCorePlus(pymmcore.CMMCore):
             }
         }
         """
-        dev = _device.Device.create(device_label, mmcore=self)
-        if (isinstance(device_type, type) and not isinstance(dev, device_type)) or (
-            isinstance(device_type, DeviceType)
-            and device_type not in {DeviceType.Any, DeviceType.Unknown}
-            and dev.type() != device_type
-        ):
-            raise TypeError(
-                f"{device_type!r} requested but device with label "
-                f"{device_label!r} is a {dev.type()}."
-            )
-
-        return dev
+        return _device.Device.create(device_label, mmcore=self, device_type=device_type)
 
     def getConfigGroupObject(
         self, group_name: str, allow_missing: bool = False
@@ -1622,16 +1619,16 @@ class CMMCorePlus(pymmcore.CMMCore):
         **Why Override?** to emit the `imageSnapped` event after snapping an image.
         and to emit shutter property changes if `getAutoShutter` is `True`.
         """
-        if autoshutter := self.getAutoShutter():
-            self.events.propertyChanged.emit(self.getShutterDevice(), "State", True)
+        if (autoshutter := self.getAutoShutter()) and (
+            shutter := self.getShutterDevice()
+        ):
+            self.events.propertyChanged.emit(shutter, "State", True)
         try:
             self._do_snap_image()
             self.events.imageSnapped.emit(self.getCameraDevice())
         finally:
-            if autoshutter:
-                self.events.propertyChanged.emit(
-                    self.getShutterDevice(), "State", False
-                )
+            if autoshutter and shutter:
+                self.events.propertyChanged.emit(shutter, "State", False)
 
     @property
     def mda(self) -> MDARunner:
@@ -2083,13 +2080,13 @@ class CMMCorePlus(pymmcore.CMMCore):
         super().deleteConfig(*args)
         self.events.configDeleted.emit(groupName, configName)
 
-    def deleteConfigGroup(self, group: str) -> None:
+    def deleteConfigGroup(self, groupName: str) -> None:
         """Deletes an entire configuration `group`.
 
         **Why Override?** To emit a `configGroupDeleted` event.
         """
-        super().deleteConfigGroup(group)
-        self.events.configGroupDeleted.emit(group)
+        super().deleteConfigGroup(groupName)
+        self.events.configGroupDeleted.emit(groupName)
 
     @overload
     def defineConfig(self, groupName: str, configName: str) -> None: ...