wxGUI: Initial support for Jupyter-based workflows

[lindakarlovska]

This pull request introduces the support for running Jupyter notebooks directly within the GUI.

How it works

There is a new Launch Jupyter Notebook Environment button added to the top menu, right next to the Launch Python Editor button (In this PR, these workflow-related buttons are now grouped together, since all of them serve a similar purpose — working with scripts or automation workflows.)

When you click the Launch Jupyter Notebook button, a new dialog appears — Start Jupyter.
In this dialog, you can:

• Choose whether to use the default working directory (created automatically in your current MAPSET as /notebooks), or
• Select a custom directory where you have write access.

The working directory is very important because in this directory the Jupyter server will be launched which means that each running Jupyter server is tied to a single directory — meaning that your entire Jupyter session is associated with that directory. If you want to work in a different directory, you simply start another Jupyter session from the GUI.

Besides the selection of a working directory, there’s also an option to create a preconfigured “welcome” notebook (a template). This lets you start working immediately with GRASS and Jupyter already initialized — including automatic imports of GRASS scripting and Jupyter modules, and initialization of the session to match your current GRASS environment.

Once you confirm the dialog:
• A local Jupyter server is started.
• The status bar (bottom left corner) shows information such as the running port and the server PID.
• If you selected the template option, a welcome.ipynb file is created in the chosen working directory, already set up with an initialized GRASS Jupyter session.

Why the Working Directory Matters

A Jupyter server always requires a working directory.
By default, GRASS uses <MAPSET_PATH>/notebooks, since it’s always available and writable. In the first version of this PR, the directory was created automatically inside the mapset.
During the PSC meeting in August 2025 ( https://grasswiki.osgeo.org/wiki/PSC_Meeting_2025-08-08), we decided it would be better to:

• Let users choose the working directory, and
• Offer a simple way to start with a good default template notebook.

That’s why the new Start Jupyter dialog exists — it provides both of these options.

What if Jupyter Isn’t Available?
Two cases are handled:

• Jupyter isn’t installed at all, or
• The user is on Windows, where Jupyter isn’t yet integrated in the GRASS build.

In both cases, the Launch Jupyter Notebook button will be disabled.

If the user clicks it anyway, an explanatory message will be shown describing the issue.

Windows Support

In version 8.5, the “Launch Jupyter” button will be active only on UNIX systems.
To make it work on Windows (both OSGeo4W and the standalone installer), Jupyter needs to be included in the build process.
That’s not too difficult — Jupyter itself is already included in the standalone installer — but its dependencies (folium and ipyleaflet) are missing from OSGeo4W packages.
I’ve submitted a PR to add them (jef-n/OSGeo4W#36 ) but it’s still awaiting feedback.
Until this is resolved, Jupyter integration won’t be available on Windows in version 8.5.

Implementation Overview

• python/grass/workflows/
  - directory.py
  Contains the JupyterDirectoryManager class, which manages Jupyter notebooks linked to the given working directory.
  Responsibilities include mainly: Import/export of .ipynb files and managing notebook templates (welcome.ipynb, new.ipynb).
  - server.py
  Provides two key classes: JupyterServerInstance which handles the lifecycle of an individual Jupyter server instance—installation check, port management, startup, shutdown, URL generation, etc. Also handles cleanup using atexit and signal handling to ensure servers are terminated when GRASS exits via GUI, exit, CTRL+C, or kill PID. Further, JupyterServerRegistry—a singleton that registers all active Jupyter server instances. It allows the global shutdown of all running servers when GRASS is closed from the GUI.
  - enviroment.py
  High-level orchestrator JupyterEnvironment integrates a working directory manager (template creation and file discovery), a Jupyter server instance and a registration of running servers in a global server registry
  - template_notebooks/
  - welcome.ipynb: A welcome notebook created on demand if checked in the Start Jupyter dialog (created only if the working directory is empty – no .ipynb files present)
  - new.ipynb: A template used when the user creates a new notebook via GUI

• gui/wxpython/jupyter_notebook/
  - panel.py - defines the JupyterPanel class, which creates the interactive panel inside the GUI. It includes: A toolbar and an AuiNotebook widget that lists and displays .ipynb files from the working directory
  - notebook.py
  Class JupyterAuiNotebook—Handles logic for adding AUI notebook tabs with JavaScript injection for hiding the Jupyter File menu and header.
  - dialogs.py
  Class StartJupyterDialog with Jupyter startup settings.
  - toolbars.py
  Class JupyterToolbar—Implements the toolbar controls for notebook actions: Create new notebook, Import notebook, Export notebook, Dock/Undock, Quit

Additional Notes

• Multiple Jupyter servers can run in a single GRASS session (one per panel)
• All servers are automatically stopped when the GUI is closed or the session ends, even forcefully
• Newly created notebooks (welcome.ipynb or new.ipynb) are pre-initialized with the GRASS Jupyter environment and required imports for immediate use. Welcome.ipynb has some extra info about a working directory.

Following steps

• Enable Jupyter support on Windows once dependencies are available in OSGeo4W.
• At some point, we should revisit the discussion about implementing a GRASS-specific Jupyter kernel — I still believe it makes sense (for example, ArcGIS Pro also provides its own). With such a kernel, users could run notebooks without need for manual initialization code. They could simply select the GRASS kernel and start working in the same way, no matter whether launching Jupyter from within the GUI or in a standalone browser session. Just noting this here for context — we’ve already talked about it briefly, but during the summit in May 2025, it felt too early to make a decision. Perhaps it still is (@petrasovaa, @landa, @wenzeslaus).
• Having in mind that we aim to make Jupyter more accessible to users by enabling GUI integration, in the future, we could also consider introducing GRASS magic commands (IPython extensions) to make command-line operations easier in Jupyter.
  For example:

    %region save=myregion – Save region
    %mapinfo elevation  - Print info about a raster or vector map
    %info – Print info about current session
    %run r.slope.aspect elevation=elevation slope=slope aspect=aspect

These could become part of a grass.jupyter library.

[lindakarlovska]

Just set up the discussion page for the notebook working directory topic and workflows topic in general: #5909.