Core Package

Top-level package objects, CLI entry points, settings, logging helpers, and branding utilities.

Package

GONet_Wizard: A toolkit for analyzing and visualizing GONet sky monitoring data.

This package provides tools for:

• Parsing and decoding raw GONet camera files

• Visualizing the image data

• Monitoring the data from multi-epoch campaigns

• Deploying dashboards and documentation

• Centralized configuration management via environment-aware settings

The package also initializes its environment-dependent configuration via the GONet_Wizard.settings module. This module defines and validates the environment variables required to run the GONet tools and dashboard components. Settings are accessed dynamically to ensure runtime flexibility and testability.

CLI Entrypoint

Entry Point for the GONet Wizard Command-Line Interface

This module provides the top-level driver for the GONet Wizard CLI. It defines main(), which is used both by python -m GONet_Wizard and by the installed console script (as configured in pyproject.toml).

Rather than manually constructing a static argparse command tree, this module delegates parser construction to the declarative command registry in GONet_Wizard.commands and the centralized parser builder in GONet_Wizard.commands.parser_builder (re-exported via GONet_Wizard.commands.cli_core). The full CLI hierarchy—including top-level commands, their arguments, and any nested subcommands—is declared via ParserSpec and CommandSpec objects.

The CLI supports both terminal-only execution and UI-backed workflows:

• Terminal mode: the parsed command handler is executed directly.

• UI-backed mode: some handlers may return structured UI results (published previews and/or window-open requests), which are interpreted by the UI bridge and rendered through the unified local UI server and pywebview.

In addition, the CLI includes a parse-time routing behavior for command forms: when a user invokes a valid command token sequence but omits required arguments, the CLI can open the corresponding GUI form page (served by the unified UI server) directly, bypassing the launcher hub page. This routing is triggered only when the invocation contains only the command token sequence (after removing global flags), so other parsing failures (unknown flags, malformed options, etc.) continue to behave like a standard terminal CLI.

Global flags such as --ui-port and --debug-webview configure the unified UI runtime used to render HTML output and manage desktop windows. These flags are pre-parsed independently of the command tree so they can be applied even when full argument parsing fails.

Workflow

1. Determine the effective argv (from sys.argv[1:] or from the provided argv argument in tests).

2. Store the current argv for parse-time error reporting and subparser error classification (used by SmartArgumentParser).

3. Pre-parse global UI flags (--ui-port, --debug-webview) without triggering subparser validation.

4. Construct the root parser using SmartArgumentParser, attach global CLI flags, and build the full command hierarchy via build_subparser().

5. Parse arguments into an argparse.Namespace.

   • On successful parse, dispatch to the registered handler (args.handler).

   • On parse failure, classify the error and:

     • open a command form page for command-only invocations missing required arguments, or

     • print standard usage/error text for all other parse errors.

6. If no command was provided (no handler attached), show help.

Branding

At import time, GONet_Wizard._branding.patch_webview_start() is invoked to ensure consistent desktop window branding (icons, titles, startup behavior) across all pywebview-backed UI entry points.

Available Commands

• show (GONet_Wizard.commands.show) — Visualize GONet files by channel using Plotly.

• show_meta (GONet_Wizard.commands.show_meta) — Display file metadata as text or HTML.

• extract (GONet_Wizard.commands.extract) — Extract counts from GONet image files.

• dashboard (GONet_Wizard.commands.run_dashboard) — Launch the interactive dashboard.

• gui (GONet_Wizard.commands.gui) — Open the unified GUI launcher window.

• build_full_array (GONet_Wizard.commands.build_full_array) — Build/process full-array products.

• split_raw (GONet_Wizard.commands.split_raw) — Convert RAW GONet JPEG files to standard TIFF/JPEG products.

Experimental remote-camera commands live under GONet_Wizard.commands.connect_commands, but they are intentionally not registered in the public command tree yet.

GONet_Wizard.cli.main(argv=None)

Execute the GONet Wizard command-line interface.

This function serves as the primary entry point for all CLI execution, whether invoked via the installed GONet_Wizard console script or through python -m GONet_Wizard. It constructs the root argument parser, attaches global options (such as --version), and delegates all command and subcommand registration to the centralized parser builder in GONet_Wizard.commands.cli_core.

Parameters:

argv (list of str, optional) – A list of command-line arguments to parse instead of sys.argv. This is primarily intended for testing. When None (default), the function processes sys.argv[1:] automatically.

Return type:

None

Returns:

None – This function does not return a value. It invokes command handlers for side effects, such as displaying images, launching dashboards, or performing remote SSH operations.

Module Entrypoint

Module entry point for python -m GONet_Wizard and the console script.

This file simply re-exports GONet_Wizard.cli.main() as main and invokes it when run as a script.

GONet_Wizard.__main__.main(argv=None)

Delegate to GONet_Wizard.cli.main().

Parameters:

argv (list of str, optional) – Optional argument vector to pass to the CLI. When None, sys.argv[1:] is used, matching standard command-line behavior.

Return type:

None

Settings

Environment Configuration and Variable Management

This module centralizes environment-driven configuration used across GONet Wizard. It defines small helpers and data containers for reading values from os.environ (optionally via a .env file) and for collecting related settings into structured objects.

The primary abstraction is EnvVar, which represents a named environment variable with an optional default value. require_env_var() builds on that to ensure required values are available, prompting the user when needed.

Constants

ROOTpathlib.Path

Absolute path to the GONet_Wizard package root directory.

STATICpathlib.Path

Absolute path to the shared static assets folder.

GONET_USEREnvVar

Environment variable for the remote GONet username (default: "pi").

GONET_PASSWORDEnvVar

Environment variable for the remote GONet password (no default).

GONET4_PATHEnvVar

Environment variable for the remote gonet4.py path (default: "/home/pi/Tools/Camera/gonet4.py").

GONET_CONFIG_FOLDEREnvVar

Environment variable for the remote configuration folder path (default: "/home/pi/Tools/Camera/").

GONET_IMAGES_FOLDEREnvVar

Environment variable for the remote image folder path (default: "/home/pi/images/").

LOCAL_OUTPUT_FOLDEREnvVar

Environment variable for the local download destination (default: "./downloaded_files/").

DASHBOARD_DEBUGEnvVar

Environment variable controlling dashboard debug behavior (default: False).

Functions

require_env_var()

Retrieve a required environment variable, prompting the user if missing.

Classes

EnvVar

Representation of a named environment variable with an optional default.

GONetConfig

Environment-based configuration for interacting with a remote GONet device.

class GONet_Wizard.settings.EnvVar(name, default=None)

Bases: object

Representation of an environment variable with an optional default value.

Instances of this class centralize variable names and defaults, and provide a consistent accessor via get().

name

Name of the environment variable.

Type:

str

default

Default value used when the environment variable is not present. Defaults to None.

Type:

object, optional

get()

Retrieve the environment variable value or its default.

If the variable exists in the environment and is a string, leading and trailing whitespace are stripped. If the resulting string is empty, the value is treated as missing and None is returned.

Return type:

Optional[Any]

Returns:

object, optional – The value of the environment variable, the configured default, or None if the variable is unset (or set to an empty string).

GONet_Wizard.settings.require_env_var(envvar, prompt=None)

Retrieve a required environment variable, or prompt the user to input it.

This function ensures a required value is available. If the variable is not set (or is set to an empty string), the user is prompted for a value.

Parameters:

• envvar (EnvVar) – Environment variable descriptor for the required value.

• prompt (str, optional) – Custom prompt shown to the user if the variable is missing.

Return type:

str

Returns:

str – The retrieved or user-provided value.

Raises:

EOFError – If user input is required but cannot be read (e.g., stdin closed).

class GONet_Wizard.settings.GONetConfig(gonet_user=None, gonet4_path=None, gonet_config_folder=None, gonet_images_folder=None, local_output_folder=None, gonet_password=None)

Bases: object

Environment-based configuration for interacting with a remote GONet device.

Values are loaded from environment variables at instantiation time (in __post_init__()) to support test overrides (e.g., monkeypatch.setenv) and runtime reconfiguration.

gonet_user

Username for SSH connection to the GONet device (from GONET_USER).

Type:

str, optional

gonet4_path

Remote path to gonet4.py (from GONET4_PATH).

Type:

str, optional

gonet_config_folder

Remote folder containing camera config files (from GONET_CONFIG_FOLDER).

Type:

str, optional

gonet_images_folder

Remote folder where images are stored (from GONET_IMAGES_FOLDER).

Type:

str, optional

local_output_folder

Local folder where downloaded files should be saved (from LOCAL_OUTPUT_FOLDER).

Type:

str, optional

gonet_password

SSH password for the GONet device. Loaded from GONET_PASSWORD or prompted for interactively if missing.

Type:

str, optional

get_gonet_password()

Retrieve the SSH password for the GONet device.

The password is read from GONET_PASSWORD when available; otherwise the user is prompted interactively.

Return type:

str

Returns:

str – The SSH password.

Raises:

EOFError – If user input is required but cannot be read (e.g., stdin closed).

Logging

Logging Utilities

Small helpers for package-wide logging.

The package emits logs under the GONet_Wizard logger namespace. Library modules should create module loggers with get_logger() and should not configure handlers directly. CLI entry points may call configure_logging() to make package logs visible to terminal users.

GONet_Wizard.logging_utils.get_logger(name=None)

Return a logger in the package namespace.

Parameters:

name (str, optional) – Module or component name. If the name already starts with "GONet_Wizard", it is used as-is. Otherwise it is appended to the package logger namespace.

Return type:

Logger

Returns:

logging.Logger – The requested package logger.

GONet_Wizard.logging_utils.configure_logging(level=30, *, force=False, fmt='%(levelname)s:%(name)s:%(message)s')

Configure terminal logging for GONet Wizard entry points.

This function is intended for CLI/UI launchers, not low-level library code. It attaches a stream handler to the package logger if one is not already present and sets the package logger level.

Parameters:

• level (int or str, optional) – Logging threshold. String values such as "INFO" and "DEBUG" are accepted. Defaults to logging.WARNING.

• force (bool, optional) – If True, remove existing package logger handlers before installing a fresh stream handler. Defaults to False.

• fmt (str, optional) – Logging format string.

Return type:

None

Returns:

None

GONet_Wizard.logging_utils.silence_noisy_loggers(level=40)

Raise the threshold for noisy third-party web-server loggers.

Parameters:

level (int, optional) – Logging level to apply to known noisy loggers. Defaults to logging.ERROR.

Return type:

None

Returns:

None

Branding

Branding module for GONet Wizard pywebview windows.

Purpose

Provides centralized, process-wide branding for all pywebview windows launched by the GONet Wizard package. On macOS, this module sets the Dock icon to a custom .icns file so that every window shares the same branded appearance. It achieves this by patching pywebview’s start() function to ensure the Dock icon is applied automatically after Cocoa initialization.

When to use

Call patch_webview_start() once, early in your application entry point (e.g., in __main__.py). After that, every call to webview.start() across the entire package will:

• Use the Cocoa backend on macOS by default (if none specified).

• Invoke set_dock_icon_once() after the Cocoa app is initialized, ensuring the Dock icon displays correctly.

Notes

• This mechanism is primarily useful during development or when running the app unbundled. When the project is packaged as a proper macOS .app bundle (via PyInstaller or py2app) and the bundle Info.plist specifies an embedded .icns icon, macOS will use that automatically, rendering this module unnecessary.

• Icon paths are hardcoded by design. If the icons are moved or renamed, this module will fail immediately, prompting you to update it.

GONet_Wizard._branding.set_dock_icon_once(path=None)

Set the macOS Dock icon for this process exactly once.

This function is a no-op on non-macOS platforms. On macOS it calls the native Cocoa API via PyObjC to set the application icon.

Parameters:

path (str, optional) – Absolute path to a .icns file. If omitted, uses _default_icon_path().

Return type:

None

Returns:

None

Raises:

• ImportError – If PyObjC is not installed on macOS.

• Exception – Any error raised by Cocoa if the icon cannot be loaded or applied.

GONet_Wizard._branding.patch_webview_start()

Patch webview.start() to apply GONet Wizard branding automatically.

Scope

This function replaces the original webview.start with a wrapper that:

1. Forces the Cocoa backend on macOS if no backend is explicitly provided.

2. Injects a startup callback that sets the Dock icon once Cocoa is initialized.

3. Preserves any user-supplied startup callback, calling it after the icon is applied.

4. Has no effect (no-op) if the patch has already been applied.

param None:

rtype:

None

returns:

None

raises ImportError:

If pywebview is not installed or cannot be imported.

Version

Retrieve the version of the GONet_Wizard package.

This module provides the __version__ variable, which automatically reflects the current version of the installed package using importlib.metadata.

Fallback support for Python <3.8 is provided via importlib_metadata.

GONet_Wizard._version.__version__

The version string of the installed GONet_Wizard package.

Type:

str

Notes

• The version is determined at runtime, so it will reflect the actual installed version of the package. If the package is not installed, it defaults to “dev”.

Desktop Entrypoint

Desktop GUI Entrypoint

This module provides a GUI-first entry point for packaged desktop builds. It is intended for [project.gui-scripts] and frozen application launchers where the user starts GONet Wizard by double-clicking an icon rather than typing a command in a terminal.

The desktop entry point deliberately reuses the existing CLI command system by invoking the gui command programmatically. This keeps the graphical launcher as a thin distribution layer and preserves all terminal functionality for power users.

GONet_Wizard.desktop.main(argv=None)

Launch the GONet Wizard GUI launcher.

Parameters:

argv (sequence of str, optional) – Optional arguments to pass after the implicit gui command. When None, command-line arguments supplied to the GUI script are used. For example, gonet-wizard-gui --port 5051 becomes equivalent to gonet-wizard gui --port 5051.

Return type:

None

Returns:

None – The function starts the normal GONet Wizard GUI workflow for its side effects.

Path Helpers

User-Writable Path Helpers

Installed desktop applications should treat their installation directory as read-only. This module provides small platform-aware helpers for paths that the application may write to at runtime: cache files, logs, configuration files, and user data.

The helpers avoid third-party dependencies so they can be used very early during application startup and inside frozen bundles. Tests and advanced users can set GONET_WIZARD_HOME to force all writable paths under a single directory.

GONet_Wizard.paths.user_dir(kind, *parts, create=True)

Return a user-writable application directory.

Parameters:

• kind ({"data", "config", "cache", "logs", "temp"}) – Writable path category.

• *parts (str or pathlib.Path) – Optional child path segments below the category directory.

• create (bool, optional) – If True create the directory and parents. Defaults to True.

Return type:

Path

Returns:

pathlib.Path – Platform-aware user-writable directory.

GONet_Wizard.paths.data_dir(*parts, create=True)

Return a directory for persistent user data.

Return type:

Path

GONet_Wizard.paths.config_dir(*parts, create=True)

Return a directory for user configuration files.

Return type:

Path

GONet_Wizard.paths.cache_dir(*parts, create=True)

Return a directory for disposable application cache files.

Return type:

Path

GONet_Wizard.paths.log_dir(*parts, create=True)

Return a directory for application logs.

Return type:

Path

GONet_Wizard.paths.temp_dir(*parts, create=True)

Return a directory for temporary application files.

Return type:

Path

GONet_Wizard.paths.config_file(*parts, create_parent=True)

Return a path to a user configuration file.

Parameters:

• *parts (str or pathlib.Path) – File path segments below the user configuration directory.

• create_parent (bool, optional) – If True create the parent directory. Defaults to True.

Return type:

Path

Returns:

pathlib.Path – User-writable configuration file path.

Resource Helpers

Package Resource Location Helpers

This module centralizes filesystem access to resources shipped inside the GONet_Wizard Python package, such as static assets, HTML templates, icons, and small data files. The helpers are intentionally small wrappers around pathlib.Path because Flask, Dash, pywebview, and some scientific libraries still expect real filesystem paths rather than abstract package resources.

The same helpers are safe to use in three common execution modes:

• editable/source checkouts during development,

• normal wheel/sdist installations, and

• frozen desktop bundles created by tools such as PyInstaller.

For frozen applications, the code understands common PyInstaller data-file layouts including _MEIPASS bundles, simple one-directory builds, and macOS .app bundles that store data under Contents/Resources. This keeps the application code stable while the packaging specification is still evolving.

GONet_Wizard.resources.package_root()

Return the best filesystem root for package-shipped resources.

Return type:

Path

Returns:

pathlib.Path – Directory that should contain package resources such as static and gui/templates.

GONet_Wizard.resources.resource_path(*parts, must_exist=False)

Build an absolute path to a package-shipped resource.

Parameters:

• *parts (str or pathlib.Path) – Path segments relative to the package resource root. With no parts, the package resource root itself is returned.

• must_exist (bool, optional) – If True, raise FileNotFoundError when the resolved path does not exist. Defaults to False.

Return type:

Path

Returns:

pathlib.Path – Absolute filesystem path to the requested resource.

Raises:

FileNotFoundError – If must_exist is True and the resource cannot be found.

GONet_Wizard.resources.static_dir(*parts, must_exist=False)

Return a path inside the shared static resource directory.

Parameters:

• *parts (str or pathlib.Path) – Optional path segments below static.

• must_exist (bool, optional) – If True, require the path to exist.

Return type:

Path

Returns:

pathlib.Path – Absolute path to the static directory or one of its children.

GONet_Wizard.resources.template_dir(*parts, must_exist=False)

Return a path inside the Flask/Jinja template directory.

Parameters:

• *parts (str or pathlib.Path) – Optional path segments below gui/templates.

• must_exist (bool, optional) – If True, require the path to exist.

Return type:

Path

Returns:

pathlib.Path – Absolute path to the template directory or one of its children.

GONet_Wizard.resources.data_file(*parts, must_exist=False)

Return a path inside the package-shipped GONet utility data directory.

Parameters:

• *parts (str or pathlib.Path) – Optional path segments below GONet_utils/src.

• must_exist (bool, optional) – If True, require the path to exist.

Return type:

Path

Returns:

pathlib.Path – Absolute path to a package data file or directory.

GONet_Wizard.resources.logo_path(filename, *, must_exist=False)

Return a path to a logo/icon file shipped with the package.

Parameters:

• filename (str) – Logo filename under static/img/logo.

• must_exist (bool, optional) – If True, require the icon file to exist.

Return type:

Path

Returns:

pathlib.Path – Absolute path to the requested logo file.