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-<scope> 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 <noreply@anthropic.com>
This commit is contained in:
gac berninaandClaude Sonnet 5 committed 2026-08-21 22:51:38 +02:00
1 parent d5352a9403
commit 91be28b04b
6 files changed
+249 -37

No files matched your search

+74
View File
@@ -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
}
+73
View File
@@ -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
+18 -6
View File
@@ -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")],
+57 -17
View File
@@ -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-<scope> 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.<scope>
"""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-<scope> 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.<scope>
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-<scope> Jupyter kernel and makes it the
default, so a fresh Console/Notebook you open from
JupyterLab's own launcher starts with eco.<scope> 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-<scope> Jupyter kernel and makes it the default, so a
fresh Console/Notebook you open from JupyterLab's own
launcher starts with eco.<scope> 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.<scope>
+1 -1
View File
@@ -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"]
+26 -13
View File
@@ -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 = {}