wolfhece._jupyter_kernel
========================

.. py:module:: wolfhece._jupyter_kernel

.. autoapi-nested-parse::

   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:

      .. code-block:: shell

          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
---------------

.. py:data:: _logger

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

   In-process Jupyter kernel bound to a :class:`WolfMapViewer`.

   :param viewer: The live viewer instance to expose inside the kernel.
   :param extra_ns: Additional names to inject into the kernel namespace on top of the
                    defaults (``viewer``, ``v``, ``call_ui``).
   :param Usage:
   :param -----:
   :param ::: kernel = EmbeddedKernel(viewer)
              kernel.start()
              print(kernel.connection_file)   # show to user / copy to VSCode

              # later, if needed:
              kernel.stop()


   .. py:attribute:: _viewer


   .. py:attribute:: _extra_ns
      :type:  dict[str, Any]


   .. py:attribute:: _thread
      :type:  Optional[threading.Thread]
      :value: None



   .. py:attribute:: _connection_file
      :type:  Optional[str]
      :value: None



   .. py:attribute:: _app
      :value: None



   .. py:attribute:: _ready_event


   .. py:property:: is_running
      :type: bool


      ``True`` while the kernel thread is alive.


   .. py:property:: connection_file
      :type: Optional[str]


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

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


   .. py:method:: 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).

      :param 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.



   .. py:method:: 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 :meth:`stop` is not called explicitly.



   .. py:method:: _build_namespace() -> dict[str, Any]

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



   .. py:method:: _run_kernel() -> None

      Kernel entry-point — runs in the daemon thread.



.. py:function:: 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.


.. py:function:: _copy_to_clipboard(text: str) -> None