datalab-platform 0.0.1.dev0__py3-none-any.whl → 1.0.0__py3-none-any.whl

datalab/plugins.py

@@ -0,0 +1,355 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+DataLab plugin system
+---------------------
+
+DataLab plugin system provides a way to extend the application with new
+functionalities.
+
+Plugins are Python modules that relies on two classes:
+
+    - :class:`PluginInfo`, which stores information about the plugin
+    - :class:`PluginBase`, which is the base class for all plugins
+
+Plugins may also extends DataLab I/O features by providing new image or
+signal formats. To do so, they must provide a subclass of :class:`ImageFormatBase`
+or :class:`SignalFormatBase`, in which format information is defined using the
+:class:`FormatInfo` class.
+"""
+
+from __future__ import annotations
+
+import abc
+import dataclasses
+import importlib
+import os
+import os.path as osp
+import pkgutil
+import sys
+from typing import TYPE_CHECKING
+
+from qtpy import QtWidgets as QW
+
+# pylint: disable=unused-import
+from sigima.io.base import FormatInfo  # noqa: F401
+from sigima.io.image.base import ImageFormatBase  # noqa: F401
+from sigima.io.image.formats import ClassicsImageFormat  # noqa: F401
+from sigima.io.signal.base import SignalFormatBase  # noqa: F401
+
+from datalab.config import MOD_NAME, OTHER_PLUGINS_PATHLIST, Conf, _
+from datalab.control.proxy import LocalProxy
+from datalab.env import execenv
+
+if TYPE_CHECKING:
+    from sigima.objects import NewImageParam, NewSignalParam
+
+    from datalab.gui import main
+    from datalab.gui.panel.image import ImagePanel
+    from datalab.gui.panel.signal import SignalPanel
+
+
+PLUGINS_DEFAULT_PATH = Conf.get_path("plugins")
+
+if not osp.isdir(PLUGINS_DEFAULT_PATH):
+    os.makedirs(PLUGINS_DEFAULT_PATH)
+
+
+#  pylint: disable=bad-mcs-classmethod-argument
+class PluginRegistry(type):
+    """Metaclass for registering plugins"""
+
+    _plugin_classes: list[type[PluginBase]] = []
+    _plugin_instances: list[PluginBase] = []
+
+    def __init__(cls, name, bases, attrs):
+        super().__init__(name, bases, attrs)
+        if name != "PluginBase":
+            cls._plugin_classes.append(cls)
+
+    @classmethod
+    def get_plugin_classes(cls) -> list[type[PluginBase]]:
+        """Return plugin classes"""
+        return cls._plugin_classes
+
+    @classmethod
+    def get_plugins(cls) -> list[PluginBase]:
+        """Return plugin instances"""
+        return cls._plugin_instances
+
+    @classmethod
+    def get_plugin(cls, name_or_class: str | type[PluginBase]) -> PluginBase | None:
+        """Return plugin instance"""
+        for plugin in cls._plugin_instances:
+            if name_or_class in (plugin.info.name, plugin.__class__):
+                return plugin
+        return None
+
+    @classmethod
+    def register_plugin(cls, plugin: PluginBase):
+        """Register plugin"""
+        if plugin.info.name in [plug.info.name for plug in cls._plugin_instances]:
+            raise ValueError(f"Plugin {plugin.info.name} already registered")
+        cls._plugin_instances.append(plugin)
+        execenv.log(cls, f"Plugin {plugin.info.name} registered")
+
+    @classmethod
+    def unregister_plugin(cls, plugin: PluginBase):
+        """Unregister plugin"""
+        cls._plugin_instances.remove(plugin)
+        execenv.log(cls, f"Plugin {plugin.info.name} unregistered")
+        execenv.log(cls, f"{len(cls._plugin_instances)} plugins left")
+
+    @classmethod
+    def unregister_all_plugins(cls):
+        """Unregister all plugins"""
+        for plugin in cls._plugin_instances:
+            execenv.log(cls, f"Unregistering plugin {plugin.info.name}")
+            plugin.unregister()
+        cls._plugin_instances.clear()
+        execenv.log(cls, "All plugins unregistered")
+
+    @classmethod
+    def get_plugin_info(cls, html: bool = True) -> str:
+        """Return plugin information (names, versions, descriptions) in html format
+
+        Args:
+            html: return html formatted text (default: True)
+        """
+        linesep = "<br>" if html else os.linesep
+        bullet = "• " if html else " " * 4
+
+        def italic(text: str) -> str:
+            """Return italic text"""
+            return f"<i>{text}</i>" if html else text
+
+        if Conf.main.plugins_enabled.get():
+            plugins = cls.get_plugins()
+            if plugins:
+                text = italic(_("Registered plugins:"))
+                text += linesep
+                for plugin in plugins:
+                    text += f"{bullet}{plugin.info.name} ({plugin.info.version})"
+                    if plugin.info.description:
+                        text += f": {plugin.info.description}"
+                    text += linesep
+            else:
+                text = italic(_("No plugins available"))
+        else:
+            text = italic(_("Plugins are disabled (see DataLab settings)"))
+        return text
+
+
+@dataclasses.dataclass
+class PluginInfo:
+    """Plugin info"""
+
+    name: str = None
+    version: str = "0.0.0"
+    description: str = ""
+    icon: str = None
+
+
+class PluginBaseMeta(PluginRegistry, abc.ABCMeta):
+    """Mixed metaclass to avoid conflicts"""
+
+
+class PluginBase(abc.ABC, metaclass=PluginBaseMeta):
+    """Plugin base class"""
+
+    PLUGIN_INFO: PluginInfo = None
+
+    def __init__(self):
+        self.main: main.DLMainWindow = None
+        self.proxy: LocalProxy = None
+        self._is_registered = False
+        self.info = self.PLUGIN_INFO
+        if self.info is None:
+            raise ValueError(f"Plugin info not set for {self.__class__.__name__}")
+
+    @property
+    def signalpanel(self) -> SignalPanel:
+        """Return signal panel"""
+        return self.main.signalpanel
+
+    @property
+    def imagepanel(self) -> ImagePanel:
+        """Return image panel"""
+        return self.main.imagepanel
+
+    def show_warning(self, message: str):
+        """Show warning message"""
+        QW.QMessageBox.warning(self.main, _("Warning"), message)
+
+    def show_error(self, message: str):
+        """Show error message"""
+        QW.QMessageBox.critical(self.main, _("Error"), message)
+
+    def show_info(self, message: str):
+        """Show info message"""
+        QW.QMessageBox.information(self.main, _("Information"), message)
+
+    def ask_yesno(
+        self, message: str, title: str | None = None, cancelable: bool = False
+    ) -> bool:
+        """Ask yes/no question"""
+        if title is None:
+            title = _("Question")
+        buttons = QW.QMessageBox.Yes | QW.QMessageBox.No
+        if cancelable:
+            buttons |= QW.QMessageBox.Cancel
+        answer = QW.QMessageBox.question(self.main, title, message, buttons)
+        if answer == QW.QMessageBox.Yes:
+            return True
+        if answer == QW.QMessageBox.No:
+            return False
+        return None
+
+    def edit_new_signal_parameters(
+        self,
+        title: str | None = None,
+        size: int | None = None,
+    ) -> NewSignalParam:
+        """Create and edit new signal parameter dataset
+
+        Args:
+            title: title of the new signal
+            size: size of the new signal (default: None, get from current signal)
+
+        Returns:
+            New signal parameter dataset (or None if canceled)
+        """
+        newparam = self.signalpanel.get_newparam_from_current(title=title)
+        if size is not None:
+            newparam.size = size
+        if newparam.edit(self.main):
+            return newparam
+        return None
+
+    def edit_new_image_parameters(
+        self,
+        title: str | None = None,
+        shape: tuple[int, int] | None = None,
+        hide_height: bool = False,
+        hide_width: bool = False,
+        hide_type: bool = True,
+        hide_dtype: bool = False,
+    ) -> NewImageParam | None:
+        """Create and edit new image parameter dataset
+
+        Args:
+            title: title of the new image
+            shape: shape of the new image (default: None, get from current image)
+            hide_height: hide image heigth parameter (default: False)
+            hide_width: hide image width parameter (default: False)
+            hide_type: hide image type parameter (default: True)
+            hide_dtype: hide image data type parameter (default: False)
+
+        Returns:
+            New image parameter dataset (or None if canceled)
+        """
+        newparam = self.imagepanel.get_newparam_from_current(title=title)
+        if shape is not None:
+            newparam.height, newparam.width = shape
+        newparam.hide_height = hide_height
+        newparam.hide_width = hide_width
+        newparam.hide_type = hide_type
+        newparam.hide_dtype = hide_dtype
+        if newparam.edit(self.main):
+            return newparam
+        return None
+
+    def is_registered(self):
+        """Return True if plugin is registered"""
+        return self._is_registered
+
+    def register(self, main: main.DLMainWindow) -> None:
+        """Register plugin"""
+        if self._is_registered:
+            return
+        PluginRegistry.register_plugin(self)
+        self._is_registered = True
+        self.main = main
+        self.proxy = LocalProxy(main)
+        self.register_hooks()
+
+    def unregister(self):
+        """Unregister plugin"""
+        if not self._is_registered:
+            return
+        PluginRegistry.unregister_plugin(self)
+        self._is_registered = False
+        self.unregister_hooks()
+        self.main = None
+        self.proxy = None
+
+    def register_hooks(self):
+        """Register plugin hooks"""
+
+    def unregister_hooks(self):
+        """Unregister plugin hooks"""
+
+    @abc.abstractmethod
+    def create_actions(self):
+        """Create actions"""
+
+
+def discover_plugins() -> list[type[PluginBase]]:
+    """Discover plugins using naming convention
+
+    Returns:
+        List of discovered plugins (as classes)
+    """
+    if Conf.main.plugins_enabled.get():
+        for path in [
+            Conf.main.plugins_path.get(),
+            PLUGINS_DEFAULT_PATH,
+        ] + OTHER_PLUGINS_PATHLIST:
+            rpath = osp.realpath(path)
+            if rpath not in sys.path:
+                sys.path.append(rpath)
+        return [
+            importlib.import_module(name)
+            for _finder, name, _ispkg in pkgutil.iter_modules()
+            if name.startswith(f"{MOD_NAME}_")
+        ]
+    return []
+
+
+def discover_v020_plugins() -> list[tuple[str, str]]:
+    """Discover v0.20 plugins (with ``cdl_`` prefix) without importing them
+
+    Returns:
+        List of tuples (plugin_name, directory_path) for discovered v0.20 plugins
+    """
+    v020_plugins = []
+    if Conf.main.plugins_enabled.get():
+        for path in [
+            Conf.main.plugins_path.get(),
+            PLUGINS_DEFAULT_PATH,
+        ] + OTHER_PLUGINS_PATHLIST:
+            rpath = osp.realpath(path)
+            if rpath not in sys.path:
+                sys.path.append(rpath)
+        for finder, name, _ispkg in pkgutil.iter_modules():
+            if name.startswith("cdl_"):
+                # Get the directory path from the module finder
+                if hasattr(finder, "path"):
+                    directory_path = finder.path
+                    v020_plugins.append((name, directory_path))
+                else:
+                    # Fallback if path is not available
+                    v020_plugins.append((name, ""))
+    return v020_plugins
+
+
+def get_available_plugins() -> list[PluginBase]:
+    """Instantiate and get available plugins
+
+    Returns:
+        List of available plugins (as instances)
+    """
+    # Note: this function is not used by DataLab itself, but it is used by the
+    #       test suite to get a list of available plugins
+    discover_plugins()
+    return [plugin_class() for plugin_class in PluginRegistry.get_plugin_classes()]

datalab/tests/__init__.py

@@ -0,0 +1,199 @@
+# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
+
+"""
+Tests (:mod:`datalab.tests`)
+------------------------
+
+The DataLab test suite is based on the `pytest <https://pytest.org>`_ framework.
+
+The test suite modules are organized in subpackages according to their purpose.
+The following subpackages are available:
+
+- :mod:`datalab.tests.backbone`: backbone tests
+- :mod:`datalab.tests.features`: feature tests (unit tests and application tests)
+- :mod:`datalab.tests.scenarios`: high-level scenarios tests
+
+.. seealso::
+
+    :ref:`validation` for more information about DataLab's testing strategy.
+"""
+
+from __future__ import annotations
+
+import os
+import os.path as osp
+import sys
+import time
+from contextlib import contextmanager
+from typing import Generator
+
+import psutil
+import pytest
+from guidata.guitest import run_testlauncher
+from sigima.tests import helpers
+
+import datalab.config  # Loading icons
+from datalab.config import MOD_NAME, SHOTPATH
+from datalab.control.proxy import RemoteProxy
+from datalab.env import execenv
+from datalab.gui.main import DLMainWindow
+from datalab.gui.panel.image import ImagePanel
+from datalab.gui.panel.signal import SignalPanel
+from datalab.utils import qthelpers as qth
+
+# Add test data files and folders pointed by `DATALAB_DATA` environment variable:
+helpers.add_test_path_from_env("DATALAB_DATA")
+
+# Add test data files and folders for the DataLab module:
+helpers.add_test_module_path(MOD_NAME, osp.join("data", "tests"))
+
+# Set default screenshot path for tests
+execenv.screenshot_path = SHOTPATH
+
+
+@contextmanager
+def datalab_test_app_context(
+    size: tuple[int, int] = None,
+    maximized: bool = False,
+    save: bool = False,
+    console: bool | None = None,
+    exec_loop: bool = True,
+) -> Generator[DLMainWindow, None, None]:
+    """Context manager handling DataLab mainwindow creation and Qt event loop
+    with optional HDF5 file save and other options for testing purposes
+
+    Args:
+        size: mainwindow size (default: (950, 600))
+        maximized: whether to maximize mainwindow (default: False)
+        save: whether to save HDF5 file (default: False)
+        console: whether to show console (default: None)
+        exec_loop: whether to execute Qt event loop (default: True)
+    """
+    if size is None:
+        size = 1200, 700
+    with qth.datalab_app_context(exec_loop=exec_loop):
+        win: DLMainWindow | None = None
+        try:
+            win = DLMainWindow(console=console)
+            if maximized:
+                win.showMaximized()
+            else:
+                width, height = size
+                win.resize(width, height)
+                win.showNormal()
+            win.show()
+            win.setObjectName(helpers.get_default_test_name())  # screenshot name
+            yield win
+        finally:
+            if save:
+                path = helpers.get_output_data_path("h5")
+                try:
+                    os.remove(path)
+                    win.save_to_h5_file(path)
+                except (FileNotFoundError, PermissionError):
+                    pass
+            has_exception_occurred = sys.exc_info()[0] is not None
+            if not exec_loop or has_exception_occurred and win is not None:
+                # Closing main window properly
+                win.set_modified(False)
+                win.close()
+
+
+def is_pid_alive(pid: int) -> bool:
+    """Check if a process with the given PID is alive
+
+    Args:
+        Process ID to check
+
+    Returns:
+        True if the process is alive, False otherwise
+    """
+    return psutil.pid_exists(pid) and psutil.Process(pid).is_running()
+
+
+def run_datalab_in_background(wait_until_ready: bool = True) -> None:
+    """Run DataLab application as a service.
+
+    This function starts the DataLab application in a separate process, ensuring that
+    it runs independently of the current script. It sets the necessary environment
+    variables to prevent the application from quitting automatically (since the script
+    is executed in a non-interactive mode - the so-called "unattended" mode) and to
+    avoid port conflicts. After starting the application, it waits for a short period
+    to allow the application to initialize and then checks if the process is alive.
+
+    The main use case for this function is in testing scenarios where the DataLab
+    application needs to be running in the background while a client connects to it
+    and performs various operations.
+
+    Args:
+        wait_until_ready: If True, waits until the DataLab application is ready to
+         accept connections (default: True). Uses RemoteProxy's built-in retry logic
+         with extended timeout to handle DataLab startup time.
+
+    Raises:
+        RuntimeError: If the DataLab application fails to start
+    """
+    env = os.environ.copy()
+    env[execenv.DO_NOT_QUIT_ENV] = "1"
+    if execenv.XMLRPCPORT_ENV in env:
+        # May happen when executing other tests before
+        env.pop(execenv.XMLRPCPORT_ENV)
+
+    proc = helpers.exec_script(
+        "-m", args=["datalab.app"], wait=False, env=env, verbose=False
+    )
+    # If the process fails to start, it will raise the `AssertionError` exception
+    # with the message "Unable to start DataLab application".
+    # In that case, it might be useful to set `wait=True` and `verbose=True` in the
+    # `exec_script` call above, so that the script waits for the DataLab application
+    # to start and prints the output to the console. This way, you can see any
+    # error messages or logs that might help you understand why the application failed
+    # to start.
+    # If the script is executed within a pytest session, add the `-s` option to pytest.
+
+    # Give the process a moment to actually start
+    time.sleep(1)
+    if not is_pid_alive(proc.pid):
+        raise RuntimeError("DataLab process terminated immediately after start")
+
+    if wait_until_ready:
+        # Use RemoteProxy's built-in retry mechanism with extended timeout
+        # DataLab startup: Python imports, Qt init, GUI creation, XML-RPC server
+        try:
+            proxy = RemoteProxy(autoconnect=False)
+            proxy.connect(timeout=30.0)  # 30 seconds max for DataLab to be ready
+            proxy.disconnect()
+        except ConnectionRefusedError as exc:
+            if is_pid_alive(proc.pid):
+                proc.kill()
+            raise RuntimeError(
+                "Failed to connect to DataLab application. "
+                "Process may have started but XML-RPC server is not responding."
+            ) from exc
+
+
+@contextmanager
+def skip_if_opencv_missing() -> Generator[None, None, None]:
+    """Skip test if OpenCV is not available"""
+    try:
+        yield
+    except ImportError as exc:
+        if "cv2" in str(exc).lower():
+            pytest.skip("OpenCV not available, skipping test")
+        raise exc
+
+
+def take_plotwidget_screenshot(panel: SignalPanel | ImagePanel, name: str) -> None:
+    """Eventually takes plotwidget screenshot (only in screenshot mode)"""
+    if execenv.screenshot:
+        prefix = panel.PARAMCLASS.PREFIX
+        qth.grab_save_window(panel.plothandler.plotwidget, f"{prefix}_{name}")
+
+
+def run() -> None:
+    """Run DataLab test launcher"""
+    run_testlauncher(datalab)
+
+
+if __name__ == "__main__":
+    run()

datalab/tests/backbone/__init__.py

@@ -0,0 +1 @@
+#