Launcher GUI API

Flask routes and helpers for the GONet Wizard launcher interface, including the JSON command endpoint and streaming terminal-feedback endpoint.

HTML Form-Based GUI for the GONet Wizard CLI

This subpackage provides the HTML and Flask-based form interface used by the GONet Wizard unified UI runtime. Rather than implementing a separate “GUI application,” it exposes a lightweight, browser-rendered control surface that maps directly onto the existing command-line interface.

The GUI is intentionally CLI-driven:

  • Every GUI action corresponds to a real CLI command

  • Form submissions are converted into argv tokens using argparse metadata

  • Commands are parsed and executed through the same handler functions used by the terminal CLI

  • Any command capable of producing UI output (HTML, preview windows, dashboards) can be invoked identically from CLI or GUI

This design ensures a single source of truth for command behavior, avoids logic duplication, and keeps the GUI extensible as new commands are added.

Architecture

The package consists of two main parts:

  • Flask blueprint and routing logic (GONet_Wizard.gui.web) - Serves the landing page and per-command form pages - Accepts JSON form submissions - Translates GUI payloads into argv lists using argparse introspection - Executes commands via their registered CLI handlers

  • Jinja2 templates

    • Base layout and shared components (e.g. path picker widgets)

    • One form template per command

    • A shared preview shell template reused by the unified UI runtime

The blueprint is registered into the unified Flask server managed by GONet_Wizard.ui.server, making the GUI available at the same local server that hosts preview endpoints (/view/<channel>).

Design Goals

  • No duplicated command logic

  • Full parity between CLI and GUI execution paths

  • Lazy parser construction to avoid circular imports

  • Declarative extensibility: adding a new command requires only:

    1. A CLI command module with a CommandSpec

    2. An optional HTML form template

This package intentionally contains no application state and no business logic beyond payload-to-argv translation. It is a thin presentation layer over the command system.

In short, this subpackage provides a structured, maintainable bridge between human-friendly HTML forms and the fully declarative GONet Wizard CLI.

Flask Routes for the GONet Wizard GUI Forms

This module defines the Flask blueprint powering the HTML form-based GUI used by the GONet Wizard unified UI server. It serves:

  • a landing page listing available commands,

  • per-command form pages rendered from Jinja templates,

  • a JSON endpoint that executes CLI commands from GUI-submitted payloads, and

  • a streaming endpoint that emits live command feedback for GUI terminal panels.

The GUI is intentionally built on top of the existing CLI infrastructure. Form submissions are converted into an argv list using argparse metadata, parsed through the same command tree as the terminal CLI, and dispatched through the registered command handler. This keeps the command logic centralized and avoids duplicating behavior between CLI and GUI entry points.

To prevent circular import issues (commands importing UI helpers, while the UI needs the command registry), the argparse parser is constructed lazily on first use and cached for subsequent requests.

Constants

launcher_bpflask.Blueprint

Flask blueprint registering the GUI routes.

Functions

get_cli_parser()

Lazily build and cache the CLI parser used to interpret GUI payloads.

index()

Render the GUI landing page.

command_page()

Render the form page for a specific command.

run_command()

Execute a command using a GUI JSON payload and return captured feedback.

stream_command()

Execute a command while streaming terminal-style feedback as server-sent events.

payload_to_argv_with_parser()

Convert a GUI payload dictionary into an argv list using argparse metadata.

GONet_Wizard.gui.web.get_cli_parser()[source]

Lazily build and cache the CLI parser.

Building the parser walks the command specification tree and imports command modules. This can trigger circular imports if done at module import time, so the parser is constructed on first use and cached.

Return type:

ArgumentParser

Returns:

argparse.ArgumentParser – CLI parser including all registered subcommands.

GONet_Wizard.gui.web.index()[source]

Render the GUI landing page.

Returns:

str – Rendered HTML for the index page.

GONet_Wizard.gui.web.command_page(cmd)[source]

Render the form page for a specific command.

Parameters:

cmd (str) – Command name token (e.g. "show" or "dashboard").

Returns:

str – Rendered HTML for the command form page.

GONet_Wizard.gui.web.run_command()[source]

Run a CLI command from a GUI JSON payload.

The request payload is converted to an argv list using argparse metadata (positionals vs options), parsed through the shared CLI parser, and executed via args.handler(args).

Returns:

flask.Response – JSON response describing success or error, optionally including an HTML output string when returned by the command handler.

Raises:

RuntimeError – If the parser cannot be constructed or command execution fails.

GONet_Wizard.gui.web.stream_command()[source]

Run a GUI command and stream live feedback as server-sent events.

The regular /run route remains useful for simple JSON request/response workflows. This endpoint is optimized for the extraction form terminal panel: it validates the same GUI payload, runs the same command handler, and emits live terminal chunks as stdout, stderr, and package log messages are produced.

Returns:

flask.Response – text/event-stream response containing status, terminal, and final done events.

GONet_Wizard.gui.web.close_show_session(session_id)[source]

Finalize a deferred interactive show session.

The interactive show window explicitly calls this route when the user clicks Save figure or Exit. The route immediately acknowledges the request and, when a save path is provided, performs the expensive figure rebuild and export in a background thread so the show window can close right away.

Parameters:

session_id (str) – Identifier of the active show session.

Returns:

flask.Response – JSON status describing whether the session was accepted.

GONet_Wizard.gui.web.close_show_meta_session(session_id)[source]

Finalize an interactive show_meta session.

The metadata preview calls this route when the user clicks Save PDF or Exit. When a save path is provided, the PDF is written in a background worker while progress remains visible in the CLI or GUI terminal panel.

Parameters:

session_id (str) – Identifier of the active metadata preview session.

Returns:

flask.Response – JSON status describing whether the close/save request was accepted.

GONet_Wizard.gui.web.payload_to_argv_with_parser(root, payload)[source]

Convert a GUI payload into an argv list using argparse metadata.

The conversion uses the destination names and action ordering from the final command parser to place positional arguments first and options afterward.

Parameters:

  • root (argparse.ArgumentParser) – Root parser containing the full command tree.

  • payload (dict) –

    GUI payload containing:

    • command: command token string (e.g. "show" or "extract")

    • additional form fields keyed by argparse dest name

Return type:

list[str]

Returns:

list of str – Token list suitable for argparse.ArgumentParser.parse_args().

Notes

  • Positionals with multi-value nargs are commonly provided as a single comma-separated string by the GUI; these values are split into tokens.

  • Boolean checkbox fields are treated as store_true flags and only emit the option flag when truthy.