Packages

Framework-agnostic dispatcher for generating runnable GUI source code from a
declarative JSON GUI specification.

This module provides a unified entry point (:class:`CodeGenerator`) that consumes
a validated GUI JSON file (see `gui_json_schema`) and routes generation to the
appropriate backend code emitter. It is part of the SBL UI generation pipeline,
sitting after the `.ui → JSON specification` phase and before project folder
materialization.

Supported output targets:

- **PyQt6 / PyMOL desktop plugin**
- **Tkinter / VMD desktop plugin**
- **Panel web app** (NGL.js or Three.js visualization)

Core responsibilities:

- Parse the JSON specification into an in-memory `GUI` object
- Select the correct backend generator based on the requested framework
- Invoke the backend generator to produce a complete Python GUI source file
- Remain stateless — file generation and project scaffolding occur upstream

Key design notes:

- Parsing uses :func:`gui_json_schema.ParseGUI.parse_gui`
- Backends are imported lazily to avoid unnecessary dependencies
- No filesystem writes are performed here; caller decides where to persist output
- Supported aliases provide ergonomic symmetry with CLI usage
    - "qt" → PyQt, "tk" → Tkinter, "pymol"/"vmd" for plugin conventions
    - "panel-ngljs" and "panel-threejs" for web visualization backends

Example:

    from gui_codegen import CodeGenerator

    src = CodeGenerator.generate_codes(
        spec_file="spec.json",
        framework="panel-ngljs",
        exe_name="my_tool",
        post_script="post_analysis.py",
    )
    # User persists source if desired:
    # Path("gui.py").write_text(src, encoding="utf-8")

Raises:
    ValueError:
        If an unsupported framework is requested.

This module is intentionally minimal — the heavy lifting (layout rendering,
widget binding, Panel object graph construction, etc.) is delegated to
backend-specific generators in `gui_codegen_*.py`.