bec-ipython-client 4.1.6__tar.gz → 4.2.0__tar.gz

{bec_ipython_client-4.1.6 → bec_ipython_client-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bec_ipython_client
-Version: 4.1.6
+Version: 4.2.0
 Summary: BEC IPython client
 Project-URL: Bug Tracker, https://github.com/bec-project/bec/issues
 Project-URL: Homepage, https://github.com/bec-project/bec

{bec_ipython_client-4.1.6 → bec_ipython_client-4.2.0}/bec_ipython_client/bec_startup.py

@@ -13,46 +13,11 @@ from bec_lib.redis_connector import RedisConnector as _RedisConnector
 logger = _bec_logger.logger
 
 
-class _LazyBECGuiClient:
-    """Defer BEC Widgets import while preserving the interactive ``gui`` object."""
-
-    def __init__(self, gui_id: str | None = None):
-        self._gui_id = gui_id
-        self._client = None
-
-    def _materialize(self):
-        if self._client is None:
-            try:
-                from bec_widgets.cli.client_utils import BECGuiClient
-            except ImportError:
-                logger.warning("BEC Widgets is not available; skipping GUI startup.")
-                bec.gui = None
-                globals().pop("gui", None)
-                raise
-
-            self._client = BECGuiClient()
-            if self._gui_id:
-                self._client.connect_to_gui_server(self._gui_id)
-            bec.gui = self._client
-            globals()["gui"] = self._client
-        return self._client
-
-    def __getattr__(self, name):
-        return getattr(self._materialize(), name)
-
-    def __setattr__(self, name, value):
-        if name.startswith("_"):
-            return super().__setattr__(name, value)
-        return setattr(self._materialize(), name, value)
-
-    def __repr__(self) -> str:
-        if self._client is None:
-            return "LazyBECGuiClient(uninitialized)"
-        return repr(self._client)
-
-
 bec = _BECIPythonClient(
-    _main_dict["config"], _RedisConnector, wait_for_server=_main_dict["wait_for_server"]
+    _main_dict["config"],
+    _RedisConnector,
+    wait_for_server=_main_dict["wait_for_server"],
+    gui_id=_main_dict["args"].gui_id,
 )
 _main_dict["bec"] = bec
 
@@ -66,13 +31,15 @@ except Exception:
     sys.excepthook(*sys.exc_info())
 else:
     if bec.started:
-        gui = bec.gui = _LazyBECGuiClient(gui_id=_main_dict["args"].gui_id)
+        gui = bec._gui  # pylint: disable=protected-access
         if not _main_dict["args"].nogui:
             try:
                 gui.show()
             except ImportError:
-                logger.warning("BEC Widgets is not available")
-                pass
+                logger.warning(
+                    "BEC Widgets is unavailable; skipping GUI startup. "
+                    "Install bec-widgets in this Python environment to use the GUI."
+                )
 
     _available_plugins = plugin_helper.get_ipython_client_startup_plugins(state="post")
     if _available_plugins:

bec_ipython_client-4.2.0/bec_ipython_client/gui_client.py

@@ -0,0 +1,66 @@
+"""Deferred GUI access for the interactive BEC client."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from bec_widgets.cli.client_utils import BECGuiClient
+
+
+class LazyBECGuiClient:
+    """Import and create the GUI client on first use, independently of the shell namespace."""
+
+    def __init__(self, gui_id: str | None = None) -> None:
+        self._gui_id = gui_id
+        self._client: BECGuiClient | None = None
+
+    def get_client(self) -> BECGuiClient:
+        """Return the GUI client, importing BEC Widgets when first requested.
+
+        Returns:
+            BECGuiClient: The initialized GUI client.
+
+        Raises:
+            ImportError: If BEC Widgets or one of its dependencies cannot be imported.
+        """
+        if self._client is None:
+            try:
+                # Import only when GUI access is requested.
+                # pylint: disable=import-outside-toplevel
+                from bec_widgets.cli.client_utils import BECGuiClient
+            except ImportError as exc:
+                raise ImportError(
+                    "BEC Widgets is required to use the GUI. Install bec-widgets in the "
+                    f"Python environment running this client. Import failed: {exc}"
+                ) from exc
+
+            client = BECGuiClient()
+            if self._gui_id:
+                client.connect_to_gui_server(self._gui_id)
+            self._client = client
+        return self._client
+
+    def close(self) -> None:
+        """Close an initialized GUI client without creating one during shutdown."""
+        if self._client is not None:
+            self._client.close()
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.get_client(), name)
+
+    def __dir__(self) -> list[str]:
+        if self._client is None:
+            return super().__dir__()
+        return dir(self._client)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name.startswith("_"):
+            super().__setattr__(name, value)
+        else:
+            setattr(self.get_client(), name, value)
+
+    def __repr__(self) -> str:
+        if self._client is None:
+            return "LazyBECGuiClient(uninitialized)"
+        return repr(self._client)

{bec_ipython_client-4.1.6 → bec_ipython_client-4.2.0}/bec_ipython_client/main.py

@@ -6,7 +6,7 @@ import functools
 import os
 import sys
 import traceback
-from typing import Iterable, Literal, Tuple
+from typing import TYPE_CHECKING, Iterable, Literal, Tuple
 
 import IPython
 import redis
@@ -21,6 +21,7 @@ from rich.text import Text
 from bec_ipython_client.beamline_mixin import BeamlineMixin
 from bec_ipython_client.bec_magics import BECMagics
 from bec_ipython_client.callbacks.ipython_live_updates import IPythonLiveUpdates
+from bec_ipython_client.gui_client import LazyBECGuiClient
 from bec_ipython_client.signals import OperationMode, ScanInterruption, SigintHandler
 from bec_lib import messages, plugin_helper
 from bec_lib.alarm_handler import AlarmBase
@@ -34,6 +35,9 @@ from bec_lib.redis_connector import MessageObject, RedisConnector
 from bec_lib.service_config import ServiceConfig
 from bec_lib.utils.pydantic_pretty_print import pretty_print_pydantic_validation_error
 
+if TYPE_CHECKING:
+    from bec_widgets.cli.client_utils import BECGuiClient
+
 logger = bec_logger.logger
 
 
@@ -66,6 +70,7 @@ class BECIPythonClient:
         wait_for_server=True,
         forced=False,
         mode: OperationMode = OperationMode.Normal,
+        gui_id: str | None = None,
     ) -> None:
         self._client = CLIBECClient(
             config,
@@ -85,12 +90,24 @@ class BECIPythonClient:
         self._exit_event = None
         self._exit_handler_thread = None
         self._live_updates = None
-        self.gui = None
+        self._gui = LazyBECGuiClient(gui_id=gui_id)
         self._client.callbacks.register(
             event_type=EventType.NAMESPACE_UPDATE, callback=self._update_namespace_callback
         )
         self._alarm_history = collections.deque(maxlen=100)
 
+    @property
+    def gui(self) -> BECGuiClient:
+        """Access the GUI client, loading BEC Widgets on first access.
+
+        Returns:
+            BECGuiClient: The initialized GUI client.
+
+        Raises:
+            ImportError: If BEC Widgets or one of its dependencies cannot be imported.
+        """
+        return self._gui.get_client()
+
     def __getattr__(self, name):
         return getattr(self._client, name)
 
@@ -218,9 +235,11 @@ class BECIPythonClient:
     def shutdown(self, per_thread_timeout_s: float | None = None):
         """shutdown the client and all its components"""
         try:
-            self.gui.close()
-        except AttributeError:
-            pass
+            # call close on the lazy GUI proxy, which will close the
+            # GUI client if it was initialized, or do nothing if it wasn't
+            self._gui.close()
+        except Exception as exc:  # pylint: disable=broad-except
+            logger.error(f"Error closing GUI client: {exc}")
         self._client.shutdown(per_thread_timeout_s)
         logger.success("done")
 

{bec_ipython_client-4.1.6 → bec_ipython_client-4.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bec_ipython_client"
-version = "4.1.6"
+version = "4.2.0"
 description = "BEC IPython client"
 requires-python = ">=3.11"
 classifiers = [

bec_ipython_client-4.2.0/tests/client_tests/test_gui_client.py

@@ -0,0 +1,180 @@
+"""Regression coverage for deferred GUI imports and shell shutdown."""
+
+from __future__ import annotations
+
+import builtins
+import runpy
+import sys
+from pathlib import Path
+from types import ModuleType, SimpleNamespace
+from unittest import mock
+
+import pytest
+
+from bec_ipython_client import BECIPythonClient, main
+from bec_ipython_client.gui_client import LazyBECGuiClient
+
+
+@pytest.fixture
+def widgets_unavailable(monkeypatch):
+    original_import = builtins.__import__
+    attempts = []
+
+    def import_without_widgets(name, *args, **kwargs):
+        if name.startswith("bec_widgets"):
+            attempts.append(name)
+            raise ModuleNotFoundError("No module named 'bec_widgets'")
+        return original_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", import_without_widgets)
+    return attempts
+
+
+@pytest.fixture
+def gui_factory(monkeypatch):
+    module = ModuleType("bec_widgets.cli.client_utils")
+    factory = mock.Mock()
+    module.BECGuiClient = factory
+    monkeypatch.setitem(sys.modules, module.__name__, module)
+    return factory
+
+
+@pytest.fixture
+def client():
+    # Exercise the real GUI property and shutdown without connecting to Redis.
+    instance = BECIPythonClient.__new__(BECIPythonClient)
+    instance.__dict__.update(
+        _client=mock.Mock(),
+        _gui=LazyBECGuiClient(),
+        started=True,
+        start=mock.Mock(),
+        _ip=mock.Mock(),
+    )
+    return instance
+
+
+@pytest.mark.parametrize("nogui", [True, False])
+def test_shutdown_after_startup_namespace_cleanup(nogui, widgets_unavailable, monkeypatch, client):
+    monkeypatch.setattr(main, "BECIPythonClient", mock.Mock(return_value=client))
+    monkeypatch.setattr(
+        "bec_lib.plugin_helper.get_ipython_client_startup_plugins", mock.Mock(return_value={})
+    )
+    with mock.patch.dict(
+        main.main_dict,
+        {
+            "config": None,
+            "wait_for_server": False,
+            "args": SimpleNamespace(nogui=nogui, gui_id=None),
+            "startup_file": None,
+        },
+        clear=True,
+    ):
+        namespace = runpy.run_path(str(Path(main.__file__).with_name("bec_startup.py")))
+        assert len(widgets_unavailable) == (0 if nogui else 1)
+        assert namespace["gui"] is client._gui
+        namespace.clear()
+        client.shutdown(per_thread_timeout_s=1)
+        client._client.shutdown.assert_called_once_with(1)
+        assert len(widgets_unavailable) == (0 if nogui else 1)
+
+
+@pytest.mark.parametrize("gui_id", [None, "existing-gui"])
+def test_gui_can_be_started_later_and_is_created_once(gui_factory, gui_id):
+    gui = LazyBECGuiClient(gui_id=gui_id)
+    gui_factory.assert_not_called()
+    assert repr(gui) == "LazyBECGuiClient(uninitialized)"
+    gui.close()
+    gui_factory.assert_not_called()
+
+    gui.show()
+    gui.show()
+    gui.set_rpc_timeout(5)
+    gui.some_setting = "value"
+    gui.close()
+
+    gui_factory.assert_called_once_with()
+    real_gui = gui_factory.return_value
+    assert real_gui.show.call_count == 2
+    real_gui.set_rpc_timeout.assert_called_once_with(5)
+    assert real_gui.some_setting == "value"
+    real_gui.close.assert_called_once_with()
+    if gui_id:
+        real_gui.connect_to_gui_server.assert_called_once_with(gui_id)
+    else:
+        real_gui.connect_to_gui_server.assert_not_called()
+
+
+def test_missing_widgets_on_explicit_use_does_not_break_shutdown(widgets_unavailable):
+    gui = LazyBECGuiClient()
+    with pytest.raises(ImportError, match="Install bec-widgets"):
+        gui.show()
+    gui.close()
+    assert len(widgets_unavailable) == 1
+
+
+def test_gui_completion_does_not_import_widgets_before_initialization(widgets_unavailable):
+    gui = LazyBECGuiClient()
+
+    assert "close" in dir(gui)
+    assert widgets_unavailable == []
+
+
+def test_gui_completion_exposes_initialized_client_methods(gui_factory):
+    real_client = gui_factory.return_value
+    real_client.show = mock.Mock()
+    real_client.set_rpc_timeout = mock.Mock()
+    gui = LazyBECGuiClient()
+
+    gui.show()
+
+    assert dir(gui) == dir(real_client)
+    assert "show" in dir(gui)
+    assert "set_rpc_timeout" in dir(gui)
+    gui_factory.assert_called_once_with()
+
+
+def test_failed_gui_connection_can_be_retried(gui_factory):
+    failed_client = mock.Mock()
+    failed_client.connect_to_gui_server.side_effect = RuntimeError("Connection failed")
+    connected_client = mock.Mock()
+    gui_factory.side_effect = [failed_client, connected_client]
+    gui = LazyBECGuiClient(gui_id="existing-gui")
+
+    with pytest.raises(RuntimeError, match="Connection failed"):
+        gui.get_client()
+
+    assert gui.get_client() is connected_client
+    assert gui.get_client() is connected_client
+    assert gui_factory.call_count == 2
+    failed_client.connect_to_gui_server.assert_called_once_with("existing-gui")
+    connected_client.connect_to_gui_server.assert_called_once_with("existing-gui")
+
+
+def test_gui_property_reports_missing_widgets(client, widgets_unavailable):
+    with pytest.raises(ImportError, match="Install bec-widgets") as exc:
+        client.gui
+    assert isinstance(exc.value.__cause__, ModuleNotFoundError)
+    client.shutdown()
+    client._client.shutdown.assert_called_once_with(None)
+    assert len(widgets_unavailable) == 1
+
+
+def test_gui_property_returns_real_client_and_caches_it(client, gui_factory):
+    gui_factory.assert_not_called()
+    assert client.gui is gui_factory.return_value
+    assert client.gui is gui_factory.return_value
+    client.shutdown()
+    gui_factory.assert_called_once_with()
+    gui_factory.return_value.close.assert_called_once_with()
+
+
+def test_gui_cleanup_failure_does_not_prevent_core_shutdown(client, gui_factory):
+    real_gui = client.gui
+    real_gui.close.side_effect = RuntimeError("GUI cleanup failed")
+
+    with mock.patch.object(main, "logger") as logger:
+        client.shutdown(per_thread_timeout_s=1)
+
+    real_gui.close.assert_called_once_with()
+    client._client.shutdown.assert_called_once_with(1)
+    logger.error.assert_called_once_with("Error closing GUI client: GUI cleanup failed")