How chriskiehl/gooey works
Project Type and Purpose
• Gooey is a Python library/tool that wraps a console (argparse)‑based Python program in a graphical user interface using wxPython. It is not a web app or microservice; it’s a desktop GUI wrapper for CLI scripts.
High‑Level Architectural Components
a. Developer Script
• Your existing Python script, with an @Gooey decorator or GooeyParser.
b. Python Bindings Layer (gooey/python_bindings)
• Intercepts argparse declarations, converts them into a JSON “build config.”
• Exposes decorator, custom parser, control objects and schema definitions.
c. Gooey Core (“Build” Phase)
• Entry point (gooey/__main__.py or @Gooey).
• Processor (gooey/gui/processor.py) reads the JSON config.
• PubSub (gooey/gui/pubsub.py) dispatches build events.
d. GUI Bootstrap & Host
• Bootstrapper (gooey/gui/bootstrap.py) initializes wxPython app.
• Host (gooey/gui/host.py) manages window life‑cycle and subprocess execution.
e. GUI Application & Components
• Application controller (gooey/gui/application/application.py) orchestrates UI.
• Component library (gooey/gui/components, /containers, /widgets) provides panels, layouts, input widgets.
• Formatters, validators, state store, event handlers.
f. Runtime Subprocess
• Gooey spawns your original script as a subprocess (via target argument).
• Captures STDOUT/STDERR to display in console panel, parse progress.
g. Packaging & Distribution
• setup.py, PyPI distribution, PyInstaller specs in docs/packaging.
Relationships & Data Flow
1. User runs python my_script.py
→ the @Gooey decorator activates.
2. Bindings layer inspects argparse actions and builds a JSON representation.
→ passed to the GUI processor.
3. Bootstrap initializes wxPython, loads JSON, and builds the GUI component tree.
4. User interacts with the GUI (fills forms, clicks “Start”).
→ pubsub events update internal state.
5. GUI Host spawns a subprocess running the original script, injecting user inputs as CLI args.
→ captures output streams.
6. Processor parses output against progress_regex/progress_expr
→ updates progress bar.
7. On subprocess exit:
• GUI shows success or failure screen.
• Fires lifecycle events (on_success, on_error).
• Allows custom handlers to modify UI state for the next run.
Key Architectural Patterns & Principles
• Decorator Pattern: @Gooey wraps your main() function.
• Publisher–Subscriber: pubsub.py mediates UI events and state updates.
• Model–View–Controller (MVC):
• Model = JSON configuration + state object
• View = wxPython widgets
• Controller = Application logic in application.py and host.py
• Separation of Concerns:
• Bindings layer purely generates config;
• GUI layer purely renders and controls runtime;
• Subprocess layer purely runs user code.
• Extensibility Points:
• Custom widgets via components/widgets;
• Internationalization via languages/*.json;
• Packaging hooks via docs/packaging.