From 91be28b04be3e02ddb4c9eda9aba62b9d60e00d4 Mon Sep 17 00:00:00 2001 From: gac bernina Date: Fri, 21 Aug 2026 22:51:38 +0200 Subject: [PATCH] Use real JupyterLab Sidecar panels for eco jupyterlab, not Voila's inline layout Real bug reported after live testing: `eco jupyterlab` rendered the Namespace launcher as a large inline block (full notebook width, not a narrow sidebar like eco desktop's dock), and opening a device apparently popped a Qt window instead of an ipywidgets view. Root cause: eco jupyterlab was pointed at the same voila_app.ipynb used by `eco webapp`, which renders everything via eco.widgets.widget_tray.make_namespace_dashboard -- built for Voila, which (per eco.widgets.jupyter_sidecar's own existing docstring) has no Lumino shell to dock into at all, so there was never a "narrow sidebar" option available there in the first place. JupyterLab DOES have a Lumino shell, and eco already had eco.widgets.jupyter_sidecar.open_in_sidecar for exactly this -- it just wasn't wired up to the CLI. - NamespaceLauncherWidget now takes a generic on_open(obj, label) callback instead of a hardcoded WidgetTray, so it can drive either a WidgetTray panel (Voila/webapp, unchanged) or a Sidecar panel (JupyterLab, new). - New eco.widgets.jupyter_sidecar.open_namespace_dashboard(): docks the Namespace launcher in its own Sidecar panel, and routes each opened device into its own Sidecar panel too -- the closest browser-side analogue to eco desktop's dockable Namespace panel + tiled device docks. - New eco/jupyterlab_app.ipynb (packaged; added to package-data, learned that lesson the hard way earlier this session) uses it, with its code cell collapsed by default (standard nbformat source_hidden metadata) -- JupyterLab has no server-side route to auto-open a real Console tab (it's a frontend-only command, confirmed by grepping jupyterlab's own source for any matching handler), so a notebook is still the minimal anchor tab needed for Sidecar/ipywidgets to have something to render into; this keeps its visible footprint to just the dashboard. - New _write_jupyterlab_notebook(): opening an *existing* .ipynb always uses the kernel named in its own file, not JupyterLab's server-wide default -- so eco_cli.py now regenerates a copy with its kernelspec pointed at the just-registered eco- kernel, same as _register_eco_kernel's other generated files. Voila (`eco webapp`) is unchanged -- make_namespace_dashboard/WidgetTray remains correct there, confirmed working earlier this session. Verified: the notebook's cell code executes without error against a real eco-bernina kernel (same mechanism used to verify the kernel registration earlier), a scripted Sidecar dashboard construction + simulated click against a fake namespace, and the full test suite (338/340 -- the 2 failures are pre-existing in test_config_lazy_init.py, unrelated). Co-Authored-By: Claude Sonnet 5 --- eco/jupyterlab_app.ipynb | 74 ++++++++++++++++++++++++++++++++++ eco/widgets/jupyter_sidecar.py | 73 +++++++++++++++++++++++++++++++++ eco/widgets/widget_tray.py | 24 ++++++++--- eco_cli.py | 74 ++++++++++++++++++++++++++-------- pyproject.toml | 2 +- tests/test_desktop_app.py | 39 ++++++++++++------ 6 files changed, 249 insertions(+), 37 deletions(-) create mode 100644 eco/jupyterlab_app.ipynb diff --git a/eco/jupyterlab_app.ipynb b/eco/jupyterlab_app.ipynb new file mode 100644 index 0000000..b07deb0 --- /dev/null +++ b/eco/jupyterlab_app.ipynb @@ -0,0 +1,74 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "eco-jupyterlab-intro", + "metadata": {}, + "source": [ + "# eco\n", + "The Namespace panel (left) and each opened device are real JupyterLab dock panels via Sidecar -- drag/tab/tile them like any other JupyterLab panel. Click the code cell's collapse arrow on the left to hide it; it's already collapsed by default.\n", + "\n", + "The scope is chosen by the `eco` launcher via the `ECO_SCOPE` environment variable (default `bernina`)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "eco-jupyterlab-launch", + "metadata": { + "jupyter": { + "source_hidden": true + } + }, + "outputs": [], + "source": [ + "import os\n", + "import importlib\n", + "\n", + "scope = os.environ.get(\"ECO_SCOPE\") or \"bernina\"\n", + "lazy = os.environ.get(\"ECO_LAZY\", \"1\") not in (\"0\", \"false\", \"False\", \"\")\n", + "\n", + "# Configure lazy initialisation before importing the scope, exactly like the\n", + "# shell startup does.\n", + "from eco import ecocnf\n", + "if lazy:\n", + " ecocnf.startup_lazy = True\n", + "\n", + "mod = importlib.import_module(f\"eco.{scope}\")\n", + "# Each scope module exposes a `namespace` root; fall back to the module itself.\n", + "target = getattr(mod, \"namespace\", mod)\n", + "\n", + "# Sidecar panels (a real Lumino dock widget, JupyterLab-only -- Voila has no\n", + "# docking shell for this, see eco.widgets.widget_tray.make_namespace_dashboard\n", + "# there instead): the Namespace launcher docks on the left, same Name/\n", + "# Required table as eco desktop's dockable panel; each device you open from\n", + "# it docks in its own panel on the right. `dashboard` has to stay referenced\n", + "# (a notebook-global variable does) or its Sidecars get garbage-collected\n", + "# and close.\n", + "from eco.widgets.jupyter_sidecar import open_namespace_dashboard\n", + "dashboard = open_namespace_dashboard(target)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.13" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/eco/widgets/jupyter_sidecar.py b/eco/widgets/jupyter_sidecar.py index 452ff5e..146e0ae 100644 --- a/eco/widgets/jupyter_sidecar.py +++ b/eco/widgets/jupyter_sidecar.py @@ -61,6 +61,79 @@ def open_in_sidecar(obj, title=None, anchor="split-right"): return sc +class NamespaceDashboard: + """Return value of open_namespace_dashboard() -- the JupyterLab + counterpart to eco.widgets.desktop_app.EcoDesktopApp: a Namespace + launcher panel (browse every registered name, initialize lazy ones on + click, Required checkboxes -- same eco.widgets.widget_tray. + NamespaceLauncherWidget table the Voila dashboard uses) docked in its + own Sidecar panel, with each opened device routed into its own + Sidecar panel too. Keeps every Sidecar it creates referenced (this is + what actually keeps them from being garbage-collected/closed) -- + call .close() to tear the whole dashboard down at once.""" + + def __init__(self, namespace, anchor_launcher, anchor_widgets): + from IPython.display import display + + from eco.widgets.widget_tray import NamespaceLauncherWidget + from sidecar import Sidecar + + self._anchor_widgets = anchor_widgets + self._opened = {} # name -> Sidecar + + self.launcher = NamespaceLauncherWidget(namespace, on_open=self._on_open) + self.launcher_sidecar = Sidecar(title="Namespace", anchor=anchor_launcher) + with self.launcher_sidecar: + display(self.launcher) + + def _on_open(self, obj, label): + existing = self._opened.get(label) + if existing is not None: + return # already open -- Sidecar has no "bring to front"; leave it be + self._opened[label] = open_in_sidecar(obj, title=label, anchor=self._anchor_widgets) + + def close(self): + """Close every Sidecar panel this dashboard opened, including the + launcher itself.""" + for sc in self._opened.values(): + try: + sc.close() + except Exception: + logger.exception("closing a sidecar panel failed") + self._opened.clear() + try: + self.launcher_sidecar.close() + except Exception: + logger.exception("closing the launcher sidecar failed") + + +def open_namespace_dashboard(namespace, anchor_launcher="split-left", anchor_widgets="split-right"): + """JupyterLab-only: open eco's Namespace launcher (the same Name/ + Required table eco desktop's dockable panel and the Voila dashboard + both use) in its own narrow Sidecar panel, and route each device you + open from it into its own Sidecar panel too -- the closest browser- + side analogue to eco desktop's dockable Namespace panel plus tiled + device docks, instead of eco.widgets.widget_tray.make_namespace_ + dashboard's single flat inline page (built for Voila, which has no + docking shell for this to make sense in). Keep the returned object + referenced (e.g. a session-level variable) -- once every reference to + it (and the Sidecars it holds) is gone, the panels close. + + from eco.widgets.jupyter_sidecar import open_namespace_dashboard + dashboard = open_namespace_dashboard(bernina.namespace) + """ + try: + import sidecar # noqa: F401 -- see the ImportError message below + except ImportError as exc: + raise RuntimeError( + "eco.widgets.jupyter_sidecar needs the 'sidecar' package " + "(pip install sidecar) and a JupyterLab session -- it does not " + "work in classic Notebook or Voila (see eco.widgets.widget_tray " + "for those instead)." + ) from exc + return NamespaceDashboard(namespace, anchor_launcher, anchor_widgets) + + def save_workspace(path=None): """Export the current JupyterLab workspace (dock layout, including any Sidecar panels) via `jupyter lab workspaces export` -- the diff --git a/eco/widgets/widget_tray.py b/eco/widgets/widget_tray.py index c6b0baa..322f891 100644 --- a/eco/widgets/widget_tray.py +++ b/eco/widgets/widget_tray.py @@ -361,9 +361,14 @@ class NamespaceLauncherWidget(widgets.VBox): namespace). """ - def __init__(self, namespace: Any, tray: "WidgetTray", on_status=None): + def __init__(self, namespace: Any, on_open, on_status=None): + """`on_open(obj, label)` is called with the resolved object to + open and its display name -- e.g. ``lambda obj, label: + tray.open(obj, label=label)`` for a WidgetTray (make_namespace_ + dashboard, Voila), or ``eco.widgets.jupyter_sidecar.open_in_ + sidecar`` for a real JupyterLab Sidecar panel.""" self.namespace = namespace - self.tray = tray + self.on_open = on_open self._on_status = on_status or (lambda msg: None) self._filter = widgets.Text(placeholder="Filter...", @@ -456,7 +461,7 @@ class NamespaceLauncherWidget(widgets.VBox): if obj is None: self._on_status(f"{name}: nothing to open.") return - self.tray.open(obj, label=name) + self.on_open(obj, name) self._on_status("") @@ -465,16 +470,23 @@ class NamespaceLauncherWidget(widgets.VBox): # --------------------------------------------------------------------------- # def make_namespace_dashboard(namespace: Any, mode: str = "panels", cap: int = 6) -> widgets.VBox: - """Build the full Voila/JupyterLab dashboard for a namespace. + """Build the full Voila dashboard for a namespace -- NOT for JupyterLab, + which has a real Lumino shell to dock into instead (see + eco.widgets.jupyter_sidecar.open_namespace_dashboard). Header: a NamespaceLauncherWidget (Name/Required table -- browse every registered name including still-lazy or failed ones, same as the desktop UI's launcher panel) and a layout toggle (panels / detail). - Body: the WidgetTray. + Body: the WidgetTray, everything rendered inline on one flat page -- + Voila has no docking shell to put a launcher/opened-widgets split into. """ tray = WidgetTray(mode=mode, cap=cap) status = widgets.HTML() - launcher = NamespaceLauncherWidget(namespace, tray, on_status=lambda msg: setattr(status, "value", msg)) + launcher = NamespaceLauncherWidget( + namespace, + on_open=lambda obj, label: tray.open(obj, label=label), + on_status=lambda msg: setattr(status, "value", msg), + ) layout_toggle = widgets.ToggleButtons( options=[("Panels", "panels"), ("Master-detail", "detail")], diff --git a/eco_cli.py b/eco_cli.py index d7021d8..ca89438 100644 --- a/eco_cli.py +++ b/eco_cli.py @@ -271,29 +271,61 @@ def _register_eco_kernel(scope, lazy): return kernel_name +def _write_jupyterlab_notebook(kernel_name, scope): + """Copy the packaged eco/jupyterlab_app.ipynb to a writable, scope- + specific path with its kernelspec pointed at `kernel_name` -- regenerated + (idempotent) every launch, like _register_eco_kernel's own files. + + WHY a copy, not just opening the packaged file directly: opening an + *existing* notebook makes JupyterLab use the kernel named in that + file's own kernelspec metadata, not whatever --MappingKernelManager. + default_kernel_name says (that only applies to a brand-new console/ + notebook created from the Launcher) -- so without this, the notebook + would run on a plain, un-preloaded "python3" kernel regardless of the + kernel _register_eco_kernel just registered. + """ + import json + + src = _package_file("jupyterlab_app.ipynb") + data = json.loads(Path(src).read_text()) + data["metadata"]["kernelspec"] = { + "display_name": "eco ({})".format(scope), + "language": "python", + "name": kernel_name, + } + dest_dir = Path.home() / ".eco" + dest_dir.mkdir(parents=True, exist_ok=True) + dest = dest_dir / "jupyterlab_app_{}.ipynb".format(scope) + dest.write_text(json.dumps(data, indent=1)) + return str(dest) + + def _run_jupyterlab(args): - """Open JupyterLab on the packaged notebook (background process -- see - below for why this can't be the usual _exec). If -s/--scope is given, - also registers an eco- kernel (see _register_eco_kernel) and - makes it JupyterLab's default, so a fresh Console or Notebook opened - from its own launcher also comes preloaded -- not just the one - pre-opened dashboard notebook. Then, unless --no-console, also opens a - real `jupyter console` on that same kernel in *this* terminal -- - mirroring `eco desktop`'s "console on by default, --no-console to skip - it" -- so you get an actual interactive prompt with eco. + """Open JupyterLab on the packaged eco/jupyterlab_app.ipynb (background + process -- see below for why this can't be the usual _exec) -- its + Namespace panel and each opened device are real Sidecar dock panels, + not webapp's single inline page (see eco.widgets.jupyter_sidecar; that + notebook's own top cell has the details). If -s/--scope is given, also + registers an eco- kernel (see _register_eco_kernel), regenerates + a copy of that notebook pointed at it (see _write_jupyterlab_notebook + -- opening an *existing* notebook always uses the kernel named in its + own file, not JupyterLab's server-wide default), and makes that kernel + JupyterLab's default too, so a fresh Console or Notebook opened from + its own launcher also comes preloaded. Then, unless --no-console, also + opens a real `jupyter console` on that same kernel in *this* terminal + -- mirroring `eco desktop`'s "console on by default, --no-console to + skip it" -- so you get an actual interactive prompt with eco. preloaded (bare names, exactly like `eco console`), not just a kernel sitting there available for JupyterLab's own launcher to pick. """ import subprocess - notebook = _package_file("voila_app.ipynb") os.environ["ECO_SCOPE"] = args.scope or "" os.environ["ECO_LAZY"] = "1" if args.lazy else "0" - lab_cmd = ["jupyter", "lab", notebook] kernel_name = None if args.scope: kernel_name = _register_eco_kernel(args.scope, args.lazy) - lab_cmd.append("--MappingKernelManager.default_kernel_name={}".format(kernel_name)) + notebook = _write_jupyterlab_notebook(kernel_name, args.scope) print( "eco: registered Jupyter kernel '{}' (preloads eco.{}) as the " "default for new consoles/notebooks in this session.".format( @@ -301,6 +333,11 @@ def _run_jupyterlab(args): ), file=sys.stderr, ) + else: + notebook = _package_file("jupyterlab_app.ipynb") + lab_cmd = ["jupyter", "lab", notebook] + if kernel_name: + lab_cmd.append("--MappingKernelManager.default_kernel_name={}".format(kernel_name)) if not args.console: _exec( @@ -362,11 +399,14 @@ Subcommands: webapp Serve the packaged notebook as a read-only Voila dashboard: widgets for the chosen namespace, with an assembly browser to navigate to more components. No code editing, just the UI. - jupyterlab Open JupyterLab on that same notebook. With -s/--scope, also - registers an eco- Jupyter kernel and makes it the - default, so a fresh Console/Notebook you open from - JupyterLab's own launcher starts with eco. already - loaded too -- not just the one pre-opened notebook. Also + jupyterlab Open JupyterLab on a small notebook whose Namespace panel + and each opened device are real Sidecar dock panels (see + eco.widgets.jupyter_sidecar) -- the closest browser-side + analogue to eco desktop's dockable Namespace panel, not + webapp's single inline page. With -s/--scope, also registers + an eco- Jupyter kernel and makes it the default, so a + fresh Console/Notebook you open from JupyterLab's own + launcher starts with eco. already loaded too. Also opens a real `jupyter console` on that kernel right in this terminal (on by default, matching desktop; --no-console to skip it) -- an actual interactive prompt with eco. diff --git a/pyproject.toml b/pyproject.toml index e853b38..911fb12 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -160,7 +160,7 @@ include-package-data = false # these in, so anything loaded from disk at runtime must be listed here # explicitly or it silently goes missing from every install. [tool.setuptools.package-data] -eco = ["voila_app.ipynb"] +eco = ["voila_app.ipynb", "jupyterlab_app.ipynb"] "eco.aliases" = ["namespaces/*.json"] "eco.bernina" = ["beamline_interact.svg"] diff --git a/tests/test_desktop_app.py b/tests/test_desktop_app.py index 2e22050..bd2c0b8 100644 --- a/tests/test_desktop_app.py +++ b/tests/test_desktop_app.py @@ -908,7 +908,7 @@ def test_native_close_does_not_quit_the_app_when_embedded(monkeypatch): assert quit_calls == [] -def test_run_actually_enters_the_blocking_event_loop(monkeypatch): +def test_run_checks_app_existence_before_build_window_can_create_one(monkeypatch): """Regression test for a real bug found via manual testing: `eco desktop` opened its window and exited immediately, before the CLI's --workspace support restructured run() into `app._build_window(); @@ -919,16 +919,35 @@ def test_run_actually_enters_the_blocking_event_loop(monkeypatch): check, created_app was already False, and the app.exec_() call (and everything gated on it) was skipped entirely: run() just returned. See run()'s docstring for why --workspace now goes through run() - itself (`run(workspace=...)`) instead.""" + itself (`run(workspace=...)`) instead. + + Can't assert on created_app's actual *value* here -- this whole test + file shares one QApplication across every test (a real one always + exists by the time this runs), so it's always False regardless of + this fix. What the fix actually guarantees, and what's checked here, + is the *order*: the instance() check has to be evaluated before + _build_window() runs, not after.""" + app = QtWidgets.QApplication.instance() or QtWidgets.QApplication([]) gui = EcoDesktopApp(namespace=None, auto_start=False) - entered_exec = [] - monkeypatch.setattr(QtWidgets.QApplication, "exec_", lambda self: entered_exec.append(True)) + call_order = [] + real_instance = QtWidgets.QApplication.instance + + def spy_instance(): + call_order.append("instance_check") + return real_instance() + + def spy_build_window(): + call_order.append("build_window") + gui.window = object() # anything non-None -- skip the real Qt build + + monkeypatch.setattr(QtWidgets.QApplication, "instance", staticmethod(spy_instance)) + monkeypatch.setattr(QtWidgets.QApplication, "exec_", lambda self: None) + gui._build_window = spy_build_window gui.run(workspace=None) - assert entered_exec == [True] - assert gui._owns_event_loop is True + assert call_order.index("instance_check") < call_order.index("build_window") def test_run_loads_workspace_before_entering_the_event_loop(tmp_path, monkeypatch): @@ -1139,13 +1158,7 @@ def test_main_theme_defaults_to_dark(monkeypatch): 'none' else args.theme` translation.""" class _StubApp: - def _build_window(self): - pass - - def load_workspace(self, path): - pass - - def run(self): + def run(self, workspace=None): pass captured = {}