wolfhece._jupyter_kernel

In-process Jupyter kernel for WolfMapViewer scripting.

Starts an ipykernel (ZMQ) inside the running wolfhece process so that any terminal-based Jupyter frontend can connect to the live viewer and manipulate it interactively.

Note

VSCode notebooks use HTTP/WebSocket (Jupyter Server API), not ZMQ connection files. The connection file produced here works only with command-line tools:

jupyter console  --existing /path/to/kernel-xxxx.json
jupyter qtconsole --existing /path/to/kernel-xxxx.json

For VSCode, the recommended approach is to open the integrated terminal (Ctrl+\`) and run the jupyter console command there.

Tip

Recommended alternative for VSCode users

Rather than connecting to a running wolfhece application from VSCode, it is simpler and more practical to launch the application directly from a VSCode notebook using %gui wx (see docs/source/development_guide/scripting_from_notebook.ipynb). That approach keeps everything in a single process with no ZMQ bridge, no connection file, and full IDE integration (autocomplete, variable explorer, inline plots).

Quick-start

From a menu item or a Python script:

from wolfhece._jupyter_kernel import EmbeddedKernel
kernel = EmbeddedKernel(viewer)
kernel.start()                         # non-blocking
print(kernel.connection_file)

Then in a terminal (including the VSCode integrated terminal):

jupyter console --existing "<connection_file>"

Thread safety

Code executed from the console runs inside the kernel’s tornado IOLoop thread, not the wx main thread. Any call that touches the wx UI must be wrapped:

import wx
wx.CallAfter(viewer.Paint)

The namespace injected into the kernel already contains a helper call_ui(fn, *args, **kwargs) that does this for you:

call_ui(viewer.Refresh)
call_ui(viewer.set_statusbar_text, 'Done!')

Requirements

ipykernel must be installed in the active environment:

pip install ipykernel

For the optional GUI console:

pip install qtconsole PyQt5   # or PyQt6 / PySide6

Module Contents

wolfhece._jupyter_kernel._logger

class wolfhece._jupyter_kernel.EmbeddedKernel(viewer: wolfhece.PyDraw.WolfMapViewer, extra_ns: dict[str, Any] | None = None)

In-process Jupyter kernel bound to a WolfMapViewer.

Parameters:

• viewer – The live viewer instance to expose inside the kernel.

• extra_ns – Additional names to inject into the kernel namespace on top of the defaults (viewer, v, call_ui).

• Usage

• -----

• :: –

  kernel = EmbeddedKernel(viewer) kernel.start() print(kernel.connection_file) # show to user / copy to VSCode

  # later, if needed: kernel.stop()

_viewer

_extra_ns: dict[str, Any]

_thread: threading.Thread | None = None

_connection_file: str | None = None

_app = None

_ready_event

property is_running: bool

True while the kernel thread is alive.

property connection_file: str | None

Path to the kernel connection JSON file, or None if not started.

The file is available as soon as start() returns (the method blocks until the kernel is initialised).

start(timeout: float = 10.0) → bool

Start the kernel in a background thread.

Blocks until the kernel has written its connection file (or until timeout seconds elapse).

Parameters:

timeout – Maximum seconds to wait for the kernel to be ready.

Returns:

True if the kernel started successfully within the timeout, False otherwise.

Raises:

RuntimeError – If ipykernel is not installed.

stop() → None

Request the kernel to shut down.

The background thread is a daemon so it will also be killed when the main process exits even if stop() is not called explicitly.

_build_namespace() → dict[str, Any]

Build the dict injected into the kernel’s global namespace.

_run_kernel() → None

Kernel entry-point — runs in the daemon thread.

wolfhece._jupyter_kernel.show_connection_dialog(viewer: wolfhece.PyDraw.WolfMapViewer, kernel: EmbeddedKernel) → None

Display a modal dialog with the kernel connection file path.

Includes a Copy button and instructions for terminal-based access. Must be called from the wx main thread.

wolfhece._jupyter_kernel._copy_to_clipboard(text: str) → None