Gooey Documentation

Technical Documentation: chriskiehl/Gooey

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Gooey

Turn (almost) any Python 3 Console Program into a GUI application with one line

Table of Contents Copy Chapter

• Gooey
• Table of contents
• Latest Update
• Quick Start
  • Installation Instructions
  • Usage
  • Examples
• What It Is
• Why Is It
• Who is this for
• How does it work
• Internationalization
• Global Configuration
• Layout Customization
• Run Modes
  • Full/Advanced
  • Basic
  • No Config
• Menus
• Dynamic Validation
• Lifecycle Events and UI control
• Showing Progress
  • Elapsed / Remaining Time
• Customizing Icons
• Packaging
• Screenshots
• Contributing
• Image Credits

Quick Start Copy Chapter

Installation instructions Copy Section

The easiest way to install Gooey is via pip

pip install Gooey

Alternatively, you can install Gooey by cloning the project to your local directory

git clone https://github.com/chriskiehl/Gooey.git

run setup.py

python setup.py install

Usage Copy Section

Gooey is attached to your code via a simple decorator on whichever method has your argparse declarations (usually main).

from gooey import Gooey

@Gooey      <--- all it takes! :)
def main():
  parser = ArgumentParser(...)
  # rest of code

Different styling and functionality can be configured by passing arguments into the decorator.

# options
@Gooey(advanced=Boolean,          # toggle whether to show advanced config or not 
       language=language_string,  # Translations configurable via json
       auto_start=True,           # skip config screens all together
       target=executable_cmd,     # Explicitly set the subprocess executable arguments
       program_name='name',       # Defaults to script name
       program_description,       # Defaults to ArgParse Description
       default_size=(610, 530),   # starting size of the GUI
       required_cols=1,           # number of columns in the "Required" section
       optional_cols=2,           # number of columns in the "Optional" section
       dump_build_config=False,   # Dump the JSON Gooey uses to configure itself
       load_build_config=None,    # Loads a JSON Gooey-generated configuration
       monospace_display=False)   # Uses a mono-spaced font in the output screen
)
def main():
  parser = ArgumentParser(...)
  # rest of code

See: How does it Work section for details on each option.

Gooey will do its best to choose sensible widget defaults to display in the GUI. However, if more fine tuning is desired, you can use the drop-in replacement GooeyParser in place of ArgumentParser. This lets you control which widget displays in the GUI. See: GooeyParser

from gooey import Gooey, GooeyParser

@Gooey
def main():
  parser = GooeyParser(description="My Cool GUI Program!") 
  parser.add_argument('Filename', widget="FileChooser")
  parser.add_argument('Date', widget="DateChooser")
  ...

Examples Copy Section

Gooey downloaded and installed? Great! Wanna see it in action? Head over the the Examples Repository to download a few ready-to-go example scripts. They'll give you a quick tour of all Gooey's various layouts, widgets, and features.

Direct Download

What is it? Copy Chapter

Gooey converts your Console Applications into end-user-friendly GUI applications. It lets you focus on building robust, configurable programs in a familiar way, all without having to worry about how it will be presented to and interacted with by your average user.

Why? Copy Chapter

Because as much as we love the command prompt, the rest of the world looks at it like an ugly relic from the early '80s. On top of that, more often than not programs need to do more than just one thing, and that means giving options, which previously meant either building a GUI, or trying to explain how to supply arguments to a Console Application. Gooey was made to (hopefully) solve those problems. It makes programs easy to use, and pretty to look at!

Who is this for? Copy Chapter

If you're building utilities for yourself, other programmers, or something which produces a result that you want to capture and pipe over to another console application (e.g. *nix philosophy utils), Gooey probably isn't the tool for you. However, if you're building 'run and done,' around-the-office-style scripts, things that shovel bits from point A to point B, or simply something that's targeted at a non-programmer, Gooey is the perfect tool for the job. It lets you build as complex of an application as your heart desires all while getting the GUI side for free.

How does it work? Copy Chapter

Gooey is attached to your code via a simple decorator on whichever method has your argparse declarations.

@Gooey
def my_run_func():
  parser = ArgumentParser(...)
  # rest of code

At run-time, it parses your Python script for all references to ArgumentParser. (The older optparse is currently not supported.) These references are then extracted, assigned a component type based on the 'action' they provide, and finally used to assemble the GUI.

Mappings:

Gooey does its best to choose sensible defaults based on the options it finds. Currently, ArgumentParser._actions are mapped to the following WX components.

GooeyParser Copy Section

If the above defaults aren't cutting it, you can control the exact widget type by using the drop-in ArgumentParser replacement GooeyParser. This gives you the additional keyword argument widget, to which you can supply the name of the component you want to display. Best part? You don't have to change any of your argparse code to use it. Drop it in, and you're good to go.

Example:

from argparse import ArgumentParser
....

def main(): 
    parser = ArgumentParser(description="My Cool Gooey App!")
    parser.add_argument('filename', help="name of the file to process")

Given then above, Gooey would select a normal TextField as the widget type like this:

However, by dropping in GooeyParser and supplying a widget name, you can display a much more user friendly FileChooser

from gooey import GooeyParser
....

def main(): 
    parser = GooeyParser(description="My Cool Gooey App!")
    parser.add_argument('filename', help="name of the file to process", widget='FileChooser')

Custom Widgets:

Internationalization Copy Chapter

Gooey is international ready and easily ported to your host language. Languages are controlled via an argument to the Gooey decorator.

@Gooey(language='russian')
def main(): 
    ...

All program text is stored externally in json files. So adding new language support is as easy as pasting a few key/value pairs in the gooey/languages/ directory.

Thanks to some awesome contributors, Gooey currently comes pre-stocked with over 18 different translations!

Want to add another one? Submit a pull request!

Global Configuration Copy Chapter

Just about everything in Gooey's overall look and feel can be customized by passing arguments to the decorator.

|
| sidebar_title | Controls the heading title above the SideBar's navigation pane. Defaults to: "Actions" |
| show_sidebar | Show/Hide the sidebar in when navigation mode == SIDEBAR |
| body_bg_color | HEX value of the main Gooey window |
| header_bg_color | HEX value of the header background |
| header_height | height in pixels of the header |
| header_show_title | Show/Hide the header title |
| header_show_subtitle | Show/Hide the header subtitle |
| footer_bg_color | HEX value of the Footer background |
| sidebar_bg_color | HEX value of the Sidebar's background |
| terminal_panel_color | HEX value of the terminal's panel |
| terminal_font_color | HEX value of the font displayed in Gooey's terminal |
| terminal_font_family | Name of the Font Family to use in the terminal |
| terminal_font_weight | Weight of the font (constants.FONTWEIGHT_NORMAL, constants.FONTWEIGHT_XXX) |
| terminal_font_size | Point size of the font displayed in the terminal |
| error_color | HEX value of the text displayed when a validation error occurs |
| richtext_controls | Switch on/off the console support for terminal control sequences (limited support for font weight and color). Defaults to : False. See docs for additional details |
| menus | Show custom menu groups and items (see: Menus |
| clear_before_run | When true, previous output will be cleared from the terminal when running program again |

Layout Customization Copy Chapter

You can achieve fairly flexible layouts with Gooey by using a few simple customizations.

At the highest level, you have several overall layout options controllable via various arguments to the Gooey decorator.

Grouping Inputs

By default, if you're using Argparse with Gooey, your inputs will be split into two buckets: positional and optional. However, these aren't always the most descriptive groups to present to your user. You can arbitrarily bucket inputs into logic groups and customize the layout of each.

With argparse this is done via add_argument_group()

parser = ArgumentParser()
search_group = parser.add_argument_group(
    "Search Options", 
    "Customize the search options"
)

You can add arguments to the group as normal

search_group.add_argument(
    '--query', 
    help='Base search string'
)

Which will display them as part of the group within the UI.

Run Modes Copy Chapter

Gooey has a handful of presentation modes so you can tailor its layout to your content type and user's level or experience.

Advanced Copy Section

The default view is the "full" or "advanced" configuration screen. It has two different layouts depending on the type of command line interface it's wrapping. For most applications, the flat layout will be the one to go with, as its layout matches best to the familiar CLI schema of a primary command followed by many options (e.g. Curl, FFMPEG).

On the other side is the Column Layout. This one is best suited for CLIs that have multiple paths or are made up of multiple little tools each with their own arguments and options (think: git). It displays the primary paths along the left column, and their corresponding arguments in the right. This is a great way to package a lot of varied functionality into a single app.

Both views present each action in the Argument Parser as a unique GUI component. It makes it ideal for presenting the program to users which are unfamiliar with command line options and/or Console Programs in general. Help messages are displayed along side each component to make it as clear as possible which each widget does.

Setting the layout style:

Currently, the layouts can't be explicitly specified via a parameter (on the TODO!). The layouts are built depending on whether or not there are subparsers used in your code base. So, if you want to trigger the Column Layout, you'll need to add a subparser to your argparse code.

It can be toggled via the advanced parameter in the Gooey decorator.

@gooey(advanced=True)
def main():
    # rest of code

Basic Copy Section

The basic view is best for times when the user is familiar with Console Applications, but you still want to present something a little more polished than a simple terminal. The basic display is accessed by setting the advanced parameter in the gooey decorator to False.

@gooey(advanced=False)
def main():
    # rest of code

No Config Copy Section

No Config pretty much does what you'd expect: it doesn't show a configuration screen. It hops right to the display section and begins execution of the host program. This is the one for improving the appearance of little one-off scripts.

To use this mode, set auto_start=True in the Gooey decorator.

@Gooey(auto_start=True) 
def main (): 
    ...

Menus Copy Section

Added 1.0.2

You can add a Menu Bar to the top of Gooey with customized menu groups and items.

Menus are specified on the main @Gooey decorator as a list of maps.

@Gooey(menu=[{}, {}, ...])

Each map is made up of two key/value pairs

1. name - the name for this menu group
2. items - the individual menu items within this group

You can have as many menu groups as you want. They're passed as a list to the menu argument on the @Gooey decorator.

@Gooey(menu=[{'name': 'File', 'items: []},
             {'name': 'Tools', 'items': []},
             {'name': 'Help', 'items': []}])

Individual menu items in a group are also just maps of key / value pairs. Their exact key set varies based on their type, but two keys will always be present:

• type - this controls the behavior that will be attached to the menu item as well as the keys it needs specified
• menuTitle - the name for this MenuItem

Currently, three types of menu options are supported:

• AboutDialog
• MessageDialog
• Link
• HtmlDialog

About Dialog is your run-of-the-mill About Dialog. It displays program information such as name, version, and license info in a standard native AboutBox.

Schema

• name - (optional)
• description - (optional)
• version - (optional)
• copyright - (optional)
• license - (optional)
• website - (optional)
• developer - (optional)

Example:

{
    'type': 'AboutDialog',
    'menuTitle': 'About',
    'name': 'Gooey Layout Demo',
    'description': 'An example of Gooey\'s layout flexibility',
    'version': '1.2.1',
    'copyright': '2018',
    'website': 'https://github.com/chriskiehl/Gooey',
    'developer': 'http://chriskiehl.com/',
    'license': 'MIT'
}

MessageDialog is a generic informational dialog box. You can display anything from small alerts, to long-form informational text to the user.

Schema:

• message - (required) the text to display in the body of the modal
• caption - (optional) the caption in the title bar of the modal

Example:

{
    'type': 'MessageDialog',
    'menuTitle': 'Information',
    'message': 'Hey, here is some cool info for ya!',
    'caption': 'Stuff you should know'
}

Link is for sending the user to an external website. This will spawn their default browser at the URL you specify.

Schema:

• url - (required) - the fully qualified URL to visit

Example:

{
    'type': 'Link',
    'menuTitle': 'Visit Out Site',
    'url': 'http://www.example.com'
}

HtmlDialog gives you full control over what's displayed in the message dialog (bonus: people can copy/paste text from this one!).

Schema:

• caption - (optional) the caption in the title bar of the modal
• html - (required) the html you want displayed in the dialog. Note: only a small subset of HTML is supported. See the WX docs for more info.

Example:

{
    'type': 'HtmlDialog',
    'menuTitle': 'Fancy Dialog!',
    'caption': 'Demo of the HtmlDialog',
    'html': '''
    <body bgcolor="white">
        <img src=/path/to/your/image.png" /> 
        <h1>Hello world!</h1> 
        <p><font color="red">Lorem ipsum dolor sit amet, consectetur</font></p>
    </body>
    '''
}

A full example:

Two menu groups ("File" and "Help") with four menu items between them.

@Gooey(
    program_name='Advanced Layout Groups',
    menu=[{
        'name': 'File',
        'items': [{
                'type': 'AboutDialog',
                'menuTitle': 'About',
                'name': 'Gooey Layout Demo',
                'description': 'An example of Gooey\'s layout flexibility',
                'version': '1.2.1',
                'copyright': '2018',
                'website': 'https://github.com/chriskiehl/Gooey',
                'developer': 'http://chriskiehl.com/',
                'license': 'MIT'
            }, {
                'type': 'MessageDialog',
                'menuTitle': 'Information',
                'caption': 'My Message',
                'message': 'I am demoing an informational dialog!'
            }, {
                'type': 'Link',
                'menuTitle': 'Visit Our Site',
                'url': 'https://github.com/chriskiehl/Gooey'
            }]
        },{
        'name': 'Help',
        'items': [{
            'type': 'Link',
            'menuTitle': 'Documentation',
            'url': 'https://www.readthedocs.com/foo'
        }]
    }]
)

Dynamic Validation Copy Section

:warning:
Note! This functionality is experimental and likely to be unstable. Its API may be changed or removed altogether. Feedback/thoughts on this feature is welcome and encouraged!

:warning:
See Release Notes for guidance on upgrading from 1.0.8 to 1.2.0

Before passing the user's inputs to your program, Gooey can optionally run a special pre-flight validation to check that all arguments pass your specified validations.

How does it work?

Gooey piggy backs on the type parameter available to most Argparse Argument types.

parser.add_argument('--some-number', type=int)
parser.add_argument('--some-number', type=float)

In addition to simple builtins like int and float, you can supply your own function to the type parameter to vet the incoming values.

def must_be_exactly_ten(value): 
    number = int(value) 
    if number == 10:
        return number
    else: 
        raise TypeError("Hey! you need to provide exactly the number 10!")
        
        
def main(): 
    parser = ArgumentParser()
    parser.add_argument('--ten', type=must_be_exactly_ten)

How to enable the pre-flight validation

By default, Gooey won't run the validation. Why? This feature is fairly experimental and does a lot of intense Monkey Patching behind the scenes. As such, it's currently opt-in.

You enable to validation by telling Gooey you'd like to subscribe to the VALIDATE_FORM event.

from gooey import Gooey, Events 

@Gooey(use_events=[Events.VALIDATE_FORM])
def main(): 
    ...

Now, when you run Gooey, before it invokes your main program, it'll send a separate pre-validation check and record any issues raised from your type functions.

Full Code Example

from gooey import Gooey, Events
from argparse import ArgumentParser

def must_be_exactly_ten(value):
    number = int(value)
    if number == 10:
        return number
    else:
        raise TypeError("Hey! you need to provide exactly the number 10!")

@Gooey(program_name='Validation Example', use_events=[Events.VALIDATE_FORM])
def main():
    parser = ArgumentParser(description="Checkout this validation!")
    parser.add_argument('--ten', metavar='This field should be 10', type=must_be_exactly_ten)
    args = parser.parse_args()
    print(args)

Lifecycle Events and UI control Copy Chapter

:warning:
Note! This functionality is experimental. Its API may be changed or removed altogether. Feedback on this feature is welcome and encouraged!

As of 1.2.0, Gooey now exposes coarse grain lifecycle hooks to your program. This means you can now take additional follow-up actions in response to successful runs or failures and even control the current state of the UI itself!

Currently, two primary hooks are exposed:

• on_success
• on_error

These fire exactly when you'd expect: after your process has completed.

Anatomy of an lifecycle handler:

Both on_success and on_error have the same type signature.

from typing import Mapping, Any, Optional
from gooey.types import PublicGooeyState  

def on_success(args: Mapping[str, Any], state: PublicGooeyState) -> Optional[PublicGooeyState]:
    """
    You can do anything you want in the handler including 
    returning an updated UI state for your next run!   
    """ 
    return state
    
def on_error(args: Mapping[str, Any], state: PublicGooeyState) -> Optional[PublicGooeyState]:
    """
    You can do anything you want in the handler including 
    returning an updated UI state for your next run!   
    """ 
    return state

• args This is the parsed Argparse object (e.g. the output of parse_args()). This will be a mapping of the user's arguments as existed when your program was invoked.
• state This is the current state of Gooey's UI. If your program uses subparsers, this currently just lists the state of the active parser/form. Whatever updated version of this state you return will be reflected in the UI!

Attaching the handlers:

Handlers are attached when instantiating the GooeyParser.

parser = GooeyParser(
    on_success=my_success_handler,
    on_failure=my_failure_handler)

Subscribing to the lifecycle events

Just like Validation, these lifecycle events are opt-in. Pass the event you'd like to subscribe to into the use_events Gooey decorator argument.

from gooey import Gooey, Events 

@Gooey(use_events=[Events.ON_SUCCESS, Events.ON_ERROR])
def main(): 
    ...

Showing Progress Copy Chapter

Giving visual progress feedback with Gooey is easy! If you're already displaying textual progress updates, you can tell Gooey to hook into that existing output in order to power its Progress Bar.

For simple cases, output strings which resolve to a numeric representation of the completion percentage (e.g. Progress 83%) can be pattern matched and turned into a progress bar status with a simple regular expression (e.g. @Gooey(progress_regex=r"^progress: (\d+)%$")).

For more complicated outputs, you can pass in a custom evaluation expression (progress_expr) to transform regular expression matches as needed.

Output strings which satisfy the regular expression can be hidden from the console via the hide_progress_msg parameter (e.g. @Gooey(progress_regex=r"^progress: (\d+)%$", hide_progress_msg=True).

Regex and Processing Expression

@Gooey(progress_regex=r"^progress: (?P<current>\d+)/(?P<total>\d+)$",
       progress_expr="current / total * 100")

Program Output:

progress: 1/100
progress: 2/100
progress: 3/100
...

There are lots of options for telling Gooey about progress as your program is running. Checkout the Gooey Examples repository for more detailed usage and examples!

Elapsed / Remaining Time Copy Section

Gooey also supports tracking elapsed / remaining time when progress is used! This is done in a similar manner to that of the project tqdm. This can be enabled with timing_options, the timing_options argument takes in a dictionary with the keys show_time_remaining and hide_time_remaining_on_complete. The default behavior is True for show_time_remaining and False for hide_time_remaining_on_complete. This will only work when progress_regex and progress_expr are used.

@Gooey(progress_regex=r"^progress: (?P<current>\d+)/(?P<total>\d+)$",
       progress_expr="current / total * 100",
       timing_options = {
        'show_time_remaining':True,
        'hide_time_remaining_on_complete':True,
    })

Customizing Icons Copy Chapter

Gooey comes with a set of six default icons. These can be overridden with your own custom images/icons by telling Gooey to search additional directories when initializing. This is done via the image_dir argument to the Gooey decorator.

@Gooey(program_name='Custom icon demo', image_dir='/path/to/my/image/directory')
def main():
    # rest of program

Images are discovered by Gooey based on their filenames. So, for example, in order to supply a custom configuration icon, simply place an image with the filename config_icon.png in your images directory. These are the filenames which can be overridden:

• program_icon.png
• success_icon.png
• running_icon.png
• loading_icon.gif
• config_icon.png
• error_icon.png

Packaging Copy Chapter

Thanks to some awesome contributors, packaging Gooey as an executable is super easy.

The tl;dr pyinstaller version is to drop this build.spec into the root directory of your application. Edit its contents so that the APPPNAME and name are relevant to your project and the pathex value points to your applications root, then execute pyinstaller -F --windowed build.spec to bundle your app into a ready-to-go executable.

Detailed step by step instructions can be found here.

Screenshots Copy Chapter

Wanna help? Copy Chapter

Code, translation, documentation, or graphics? All pull requests are welcome. Just make sure to checkout the contributing guidelines first.

Overview (`gooey/tests/integration/README.md`) Copy Section

These integration tests must be run one at a time. I can't figure out how to clear the wx context between runs and Unittest doesn't allow process isolation..

Gooey Options (`docs/Gooey-Options.md`) Copy Section

Gooey Options

Using GooeyParser we can extend the API of argparse to support lots of cool additional functionality.

The main addition to the top-level argparse API is that we pick up extra keywords: widget and gooey_options. widget is used to specified which UI element to provide for the argument, i.e., a listbox or a file browser. gooey_options accepts a dictionary of configuration parameters that lets you specify things like custom validators, style overrides, and a bunch of behavioral extensions for the various widget classes.

GooeyParser is a drop-in replacement for argparse. You can import it from the root Gooey namespace like this:

from gooey import GooeyParser

and replace ArgumentParser with GooeyParser

# parser = ArgumentParser()   # old busted
parser = GooeyParser()        # new hotness

and with that, you're ready to rock.

Overview Copy Chapter

• Global Style/Layout Options
• Global Config Options
• Custom Widget Options
  • Textarea
  • BlockCheckbox
  • Listbox
  • RadioGroups
• Argument Group Options

Global Style / Layout Options Copy Chapter

All widgets in Gooey (with the exception of RadioGroups) are made up of three basic components.

1. Label
2. Help Text
3. Input Control

The following options apply to all Widget types in Gooey.

parser.add_argument('-my-arg', gooey_options={
    'label_color': '#ffffff',
    'label_bg_color': '#ffffff', 
    'help_color': '#ffffff',
    'help_bg_color': '#ffffff',
    'error_color': '#ffffff',
    'error_bg_color': '#ffffff',
    'show_label': bool,
    'show_help': bool, 
    'visible': bool,
    'full_width': bool
})

Global Config Options Copy Chapter

new in 1.0.8

All widgets in Gooey accept an initial_value option to seed the UI.

parser.add_argument('-my-arg', widget='Textarea', gooey_options={
    'initial_value': 'Hello world!'  
})

Individual Widget Options Copy Chapter

A few widgets have additional options for controlling their layout and behavior.

Textarea Copy Section

parser.add_argument('-my-arg', widget='Textarea', gooey_options={
    # height of the text area in pixels
    'height': int,    
    # prevents the user from editing when true
    'readonly': bool  
})

IntegerField Copy Section

parser.add_argument('-my-arg', widget='IntegerField', gooey_options={
    'min': int, 
    'max': int, 
    'increment': int  
})

DecimalField Copy Section

parser.add_argument('-my-arg', widget='IntegerField', gooey_options={
    'min': float, 
    'max': float, 
    'increment': float,
    'precision': int  # 0 - 20
})

Slider Copy Section

The Slider is just a reskinned IntegerField, so it has the same options

parser.add_argument('-my-arg', widget='Slider', gooey_options={
    'min': int, 
    'max': int, 
    'increment': int  
})

BlockCheckbox Copy Section

parser.add_argument('-my-arg', widget='BlockCheckbox', gooey_options={
    # allows customizing the checkbox's label
    'checkbox_label': str  
})

Listbox Copy Section

parser.add_argument('-my-arg', widget='Listbox', gooey_options={
    # height of the listbox in pixels
    'height': int
})

Radio Group Copy Section

parser.add_mutually_exclusive_group(gooey_options={
    # Pre-select a specific option within a mutually exclusive group. 
    # default behavior is to have all options unselected by default.  
    'initial_selection': int
})

Argument Groups Copy Chapter

Argument Groups take a number of gooey_options to help control layout.

parser.add_argument_group('MyGroup', desription='my cool group', gooey_options={
    'show_border': bool,
    'show_underline': bool,
    'label_color': '#FF9900',
    'columns': int,
    'margin_top': int
})

File and Folder choosers Copy Chapter

File and Folder Choosers Groups take a number of gooey_options to help control default values.

/* Detailed source-code truncated for AI context efficiency. */

Gracefully Stopping (`docs/Gracefully-Stopping.md`) Copy Section

Gracefully Stopping a Running Process

New in v1.0.9!

Contents:

• How to tell Gooey which shutdown signal to use
• How to catch KeyboardInterrupts
• How to catch general interrupt signals

By default, Gooey will kill the child process without any chance for cleanup. This guide will explain how to adjust that behavior so that you can detect when Gooey is attempting to close your process and use that signal to shutdown gracefully.

Basics: How to tell Gooey which shutdown signal to use: Copy Section

You can control the signal Gooey sends while stopping your process via shutdown_signal decorator argument. Signal values come from the builtin signal python module. On linux, any of the available constants may be used as a value. However, on Windows, only CTRL_BREAK_EVENT, CTRL_C_EVENT and SIGTERM are supported by the OS.

import signal 
@Gooey(shutdown_signal=signal.CTRL_C_EVENT)
def main():
    ...

How to catch KeyboardInterrupts: Copy Section

Keyboard interrupts are triggered in response to the CTRL_C_EVENT signal.

import signal 
@Gooey(shutdown_signal=signal.CTRL_C_EVENT)
def main():
    ...

Catching them in your code is really easy! They conveniently show up as top-level Exceptions. Just wrap your main logic in a try/except and you'll be able to catch when Gooey tries to shut down your process.

try
   # your code here
except KeyboardInterrupt: 
   # cleanup and shutdown or ignore

How to catch general interrupt signals Copy Section

Handling other signals is only slightly more involved than the CTRL_C_EVENT one. You need to install a handler via the signal module and tie it to the specific signal you want to handle. Let's use the CTRL_BREAK_EVENT signal as example.

import signal

# (1)
def handler(*args): 
    print("I am called in response to an external signal!")
    raise Exception("Kaboom!")

# (2) 
signal.signal(signal.SIGBREAK, handler)

# (3)
@Gooey(shutdown_signal=signal.CTRL_BREAK_EVENT)
def main():
    # your code here 
    # ...

Here we setup a handler called handler (1). This function can do anything you want in response to the signal including ignoring it entirely. Next we tie the signal we're interested in to the handler (2). Finally, we tell Gooey to send the BREAK signal(3) when the stop button is clicked.

Note: pay close attention to the different constants used while specifying a handler (e.g. SIGBREAK) versus specifying which signal will be sent (e.g. CTRL_BREAK_SIGNAL).

Using Richtext Controls (`docs/Using-Richtext-Controls.md`) Copy Section

Using the Richtext Controls

Gooey has a support for basic terminal control sequences. These let you control weight and color of the output font. For a full runnable example, checkout the code from the examples repository

You can enable this mode by passing the richtext_controls option to the Gooey decorator.

@Gooey(richtext_controls=True)
def main():
   ...

Usage Copy Section

The colored library provides functions for adding markup controls to your text. Gooey supports the foreground (fg) and attributes (attr).

from colored import stylize, attr, fg

You can modify your text's output by wrapping it in the stylize function provided by colored.py. For instance, this line will be displayed as bold (attr(1)) and red (fg('red')) when rendered by Gooey.

print(stylize('Hello world!', fg('red') + attr('bold')))

Note that you combine the foreground and attribute functions with the + operator.

Attributes: Copy Section

Richtext currently supports the following attributes:

These can be used either via their code (attr(1)) or their verbose form (attr('bold'))

Foreground Colors: Copy Section

Similar to the Attributes, foreground colors can be specified either by their code (fg(2)) or verbose form (fg('green'))

Pull Request Template (`docs/pull_request_template.md`) Copy Section

Hello there!

Make sure you've followed the Contributing guidelines before finalizing your pull request.

TL;DR:

• You're opening this PR against the current release branch
• Works on both Python 2.7 & Python 3.x
• Commits have been squashed and includes the relevant issue number
• Pull request description contains link to relevant issue or detailed notes on changes
• This must include example code demonstrating your feature or the bug being fixed
• All existing tests pass
• Your bug fix / feature has associated test coverage
• README.md is updated (if relevant)

Packaging Packaging Custom Images (`docs/packaging/Packaging-Custom-Images.md`) Copy Section

Using Custom Images while Packaging

Note: if you're new to packaging Gooey, checkout the main Packaging Guide first!

Gooey comes with a set of six default icons. These can be overridden with your own custom images/icons by telling Gooey to search additional directories when initializing. This is done via the image_dir argument to the Gooey decorator.

@Gooey(program_name='Custom icon demo', image_dir='/path/to/images')
def main():
    # rest of program

While this works for regular executions, a little additional work is required to make sure that your images will actually be available when running as a stand alone executable.

To make your custom images available after packaging, you have to do two things.

Step 1: wrap the path to your image directory in the local_resource_path() function provided by Gooey. When PyInstaller runs your application, it decompresses all the contents to a random temp directory. This function will handle the logic of resolving that directory and fetching your resources from it.

from gooey import Gooey, local_resource_path

@Gooey(image_dir=local_resource_path('relative/path/to/images'))
def main():
   ...

Step 2: Update build.spec to include the image directory during bundling. This is done by giving the path to your Images as a Tree object to Pyinstaller's EXE section.

# -*- mode: python ; coding: utf-8 -*-

import os
...
# LOOK AT ME! I AM A TREE OBJECT 
image_overrides = Tree('path/to/images', prefix='path/to/images')

...

exe = EXE(pyz,
          a.scripts,
          a.binaries,
          a.zipfiles,
          a.datas,
          options,
          image_overrides,  # <-- NEW 
          name='APPNAME',
          debug=False,
          strip=None,
          upx=True,
          console=False,
          icon=os.path.join(gooey_root, 'images', 'program_icon.ico'))

And then build via PyInstaller as usual.

pyinstaller -F --windowed build.spec

PyInstaller will now include your images in its bundle.

Packaging Packaging Gooey (`docs/packaging/Packaging-Gooey.md`) Copy Section

Packaging Gooey as a Stand Alone Application

:warning: Packaging Gooey is an ongoing science. Gooey currently runs on all the major platforms, can be installed in a bajillion different ways, and has several active versions in wide usage. In short, edge cases abound. If you run into any problems, hit up this issue.

You can package all of your programs files into a single easy to distribute executable using PyInstaller.

Packing Gooey into a standalone executable is super straight forward thanks to PyInstaller. It is the only dependency you'll need and can be installed via the following.

pip install pyinstaller

Setting up the build:

PyInstaller uses spec files to determine how to bundle the project. These are a bit like setup.py files, but contain rules for how PyInstaller should bundle your whole application as a stand alone executable.

This file is usually placed in the root of your project. e.g.

MyProject/
   - src/
   - build.spec  # <-- goes here!
   - LICENCE.txt
   - README.md

Download Spec Files

• Windows users can grab a pre-built spec file here.
• For OSX users, you'll want this one.

The exact contents of the spec files will vary based on your OS, but at a high level, they'll share the same core pieces: Analysis, EXE, and, if you're on OSX, BUNDLE

# -*- mode: python ; coding: utf-8 -*-

block_cipher = None

a = Analysis(
    ['main.py'],  # replace me with the main entry point 
    pathex=['/path/to/main.py'],  # replace me with the appropriate path
    ...
    )

pyz = PYZ(a.pure)

options = [('u', None, 'OPTION'), ('v', None, 'OPTION'), ('w', None, 'OPTION')]

exe = EXE(pyz,
       ...
       name='MyCoolApplication'  # replace me with exe name
       console=False)
       
## OSX only below!       
app = BUNDLE(exe,
             name='APPNAME.app',  # osx users replace me!
             bundle_identifier=None,
             info_plist=info_plist
            )

The Analysis section is where you'll tell PyInstaller about your program. Using the build.spec from above, you'll need to make two edits to this section.

1. replace APPNAME in the Analysis() section with the name of your application
2. replace the pathex value in the Analysis() section with the path to your application's root

note: If you use additional data resources (e.g. images, data, etc..) you'll also need to explicitly add them to the EXE section. See [packaging custom images] for more info.

Next is EXE. In this section you'll replace the name argument with what you'd like the final .exe to be named.

Note: if you're providing your own icon file, EXE is where you'll provide it. If you're on Windows, you must provide an .ico file (not PNG).

If you're on OSX, you'll have an additional BUNDLE section. You'll need to make one final edit here as well to control the name of the .app bundle that PyInstaller produces. Additionally, if you're customizing the bundle's icon, this is where you would supply the override (versus Windows, which places it in the EXE section).

Once you've updated the .spec to reflect your program's details. All that's left to do is build the executable!

Running the .spec file Copy Section

From the command line, run

pyinstaller -F --windowed build.spec

• -F tells PyInstaller to create a single bundled output file
• --windowed disables the terminal which would otherwise launch when you opened your app.

And that's it. Inside of the dist/ directory, you'll find a beautiful stand-alone executable that you can distribute to your users.

Troubleshooting Copy Chapter

PROBLEM: My bundled Application won't work!

First things first: See if you can package your application without Gooey!

Read and understand all of the PyInstaller docs. If you're referencing binaries or external data files, you may have to do a little extra work in your .spec to get PyInstaller to understand all of your dependencies.

Rebuild your bundle with debug=True set in the .spec file. This will give lots of useful output when your application bootstraps which can make pinning down the problem much easier.

Rebuild your bundle without the -F flag (e.g. just pyinstaller build.spec). This will build a directory with all of your dependencies. This can make it easier to poke around and see what PyInstaller's view of your project actually is.

PROBLEM: I'm seeing the wrong icon on my executable

First things first: Is Windows gas lighting you?

Windows caches icons semi-aggressively. This can lead to it showing an icon in the file explorer that doesn't actually reflect reality.

Right-click on the executable and select "properties." This will show you the icon that's actually associated with file. As long as everything looks good there, you're golden. Windows will catch up... eventually.

PROBLEM: Exception: This program needs access to the screen. Please run with a Framework build of python, and only when you are logged in on the main display of your Mac.

This happens on OSX when you neglect the --windowed flag during your build step.

wrong:

pyinstaller build.spec  ## oops! forgot the required flags

Correct:

pyinstaller --windowed build.spec

Checkout the Pyinstaller Manual for more details.

Releases 1.0.3 Release Notes (`docs/releases/1.0.3-release-notes.md`) Copy Section

Gooey 1.0.3 Released!

After cooking for far too long, Gooey 1.0.3 is released!

Grab the latest version:

• github
• PyPi

Runnable demos for all the new features can be found in the Examples repo.

Overview: Copy Chapter

A lot of focus was put on settling Gooey down into a more stable mature project. In addition to all of the new features, a lot of time was spent writing documentation, stamping down cross platform issues / quirks, and making numerous tweaks and additions to enable a smoother experience when packaging Gooey for distribution.

What's new Copy Chapter

Fancy Layout controls! Copy Section

The main goal of this release was enabling more complex real-world layouts and more customization of Gooey's UI. As of 1.1.0, you now have have control over every color, font, and display status within the application. You can now brand Gooey to your organization's colors, logically group related items under a central heading, and optionally show/hide all the individual components that make up an input widget.

Menu Bars Copy Section

Gooey now includes a simple declarative system for creating top level menu bars and items.

The menu option currently supports three flavors:

AboutDialog

This is an AboutDialog as rendered natively by your OS. It's a good place to show standard info like version info, descriptions, licenses, etc.. in a standard way across platforms.

MessageDialogs

Next up are general message dialogs. You can display any informational text inside of these.

Link

Finally, you can create fixed menu items that simply link to external resources, for instance, your site, documentation, pdfs, etc..

Rich Text Controls Copy Chapter

Thanks to @NathanRichard, Gooey can now optionally honor terminal control sequences and display Rich Text in the output panel.

New Gooey Program Icon Copy Section

New icon provided by professional cool guy and crazy talented UX designer Justin Rhee.

Additional features Copy Chapter

• OSX now shows program Icon in Dock
• show_error_modal option to toggle whether or not failures additionally raise alert modals.
• BlockCheckbox widget.
• Hyperlinks written to the console appear as such and will launch a browser on click
• clear_before_run option lets you control whether or not subsequent program runs start from a fresh terminal or preserve the previous output.
• Conditionally show/hide restart button
• requires_shell option - controls how Popen spawns your program. By default (and historically), this value is False.
• Optionally silence textual progress updates when using the Progress widget (via @conradhilley)
• Multi-Directory Choosers - these were accidentally dropped from the project. @HenrykHaniewicz added them back!
• Additional explicit wx imports to make packaging on OSX easier
• Textfields can now be made Readonly for informational purposes
• better custom target support via suppress_gooey_flag which prevents the --ignore-gooey flag from being injected

Breaking Changes Copy Chapter

No breaking changes between 1.0.0 and 1.1.0!

Language Additions / Improvements Copy Chapter

• Completed Italian translation - @gison93

• Updated French translation - @NathanRichard

• Updated Hebrew translation - @eturkes

Bug Fixes Copy Chapter

• Fixed 5 year old bug(!) where an errant lambda function wasn't passing through all of its arguments which caused frustratingly opaque failures under specific conditions.
• Fixed bug where external updates weren't applied to ListBox
• Fix bug where tuples weren't coerced to List which causes concatenation errors
• Fixed bug where string coercion in argparse_to_json was too broad and caused type errors
• Fixed bug where wrong validator was applied to Dropdown type causing preflight checks to always fail
• Fixed bug where Radio Groups would apply too much vertical spacing between components
• Fixed bug where subgroups with single items were attached to the wrong UI parent
• Fixed bug where legacy default groups weren't being translated
• Fixed bug where certain languages would sometimes cause components to be rendered off screen

Releases 1.0.4 Release Notes (`docs/releases/1.0.4-release-notes.md`) Copy Section

Gooey 1.0.4 Released!

Gooey picked up some cool new widget types thanks to awesome contributions from @NathanRichard and @conradhilley.

The rest of this release was focused on bug fixes and quality improvements. My commitment is to having Gooey be a stable, reliable project. This has required slowly shedding it's fast and loose hobby project past. Test coverage more than doubled between 1.0.3 and 1.0.4 and several bugs were fixed along the way as a result of this. The next few releases of Gooey will be similarly focused on bringing its codebase up to snuff so that wider changes can be made without introducing unexpected regressions.

Upgrading from 1.0.3 to 1.0.4 Copy Chapter

Translation notice! Yes/No options in confirmation modals are now backed by the language files. Previously, they were fixed to english regardless of the selected language. If the new language options aren't configured for your language, you will now see a translation request in the button label!

What's new Copy Chapter

Widgets: TimeChooser Copy Section

Usage:

parser = GooeyParser()
parser.add_argument('--time', widget='TimeChooser')

@NathanRichard added this one after an excellent deep dive into the complexities of dealing with time inside of WX. See the README for notes on usage.

Widgets: ColourChooser Copy Section

Usage:

parser = GooeyParser()
parser.add_argument('--color', widget='ColourChooser')

@conradhilley brought this one to life. You can now select colors from an awesome little chooser widget.

CLI based defaults Copy Section

@jschultz added the ability to use arguments passed on the command line as defaults in Gooey. Enable this functionality by passing use_cmd_args to the Gooey decorator.

@Gooey(use_cmd_args=True)
def main():
    parser = ArgumentParser()
    parser.add_argument('--foo')

Now any CLI args you pass when invoking your program will show up as defaults in Gooey.

python my_program.py --foo "hello!"

Additional features Copy Section

• Added option to start Gooey in full screen mode

Language Additions / Improvements Copy Chapter

• @foben - documentation fixes
• @gediz - turkish translations
• @dsardelic - bosnian & Croatian translations
• @partrita - Korean translations

Bug Fixes Copy Chapter

• Main README image had a typo "Command Lines Applications"
• Truthy values
• Fixed bug where nargs in textfields weren't being mapped correctly
• Fixed bug where argparse's SUPPRESS flag was showing in the UI
• Fixed missing i18n capabilities in modals
• Fixed bug where program_description wasn't being honored
• Fixed bug where gooey_options weren't being honored in the Header
• Fixed bug where RadioGroup wasn't enabling it's child widget when initial_selection was set
• Fixed bug where checkboxes weren't honoring visibility options
• Fixed bug where gooey_options weren't being passed to footer

Releases 1.0.5 Release Notes (`docs/releases/1.0.5-release-notes.md`) Copy Section

Gooey 1.0.5 Released! Copy Chapter

Gooey is now using WX 4.1.0!

This change should resolve several issues in Ubuntu as well as the numerous other quirks which have been reported.

Thank you to the current Patreon supporters! Copy Chapter

• Qteal
• Joseph Rhodes

New widgets:

FilterableDropdown Copy Section

You can checkout a runnable example in the GooeyExamples repo here

Example Code:

add_argument(
    choices=['a', 'b', 'c'],
    widget='FilterableDropdown',
    gooey_options={
        'no_match': 'No results found!',
        'placeholder': 'Type something!'
})

This introduces a new language translation key: "no_matches_found" to handle the case where the user's input doesn't match any of the choices. This is used by default, but can be overridden via gooey options

Elapsed Time / Estimated time remaining Copy Section

@JackMcKew put in a herculean effort and introduced a new feature where elapsed and estimated remaining time can be shown in addition to the standard progress bar.

You can checkout an example here

Example Code:

@Gooey(timing_options={
    'show_time_remaining':True,
    'hide_time_remaining_on_complete':True
})

Breaking Changes Copy Chapter

• (documentation breaking)terminal_font_weight's public documented API allowed the strings "NORMAL" and "BOLD" while its internal implementation relied on numeric font weights (light=200, normal=300, etc..). The documentation was updated to show the correct usage and a constants file was added to the public API.

Functionality Copy Chapter

• @neonbunny enabled Parsers to use configuration from parents.
• @eladeyal-intel updated RichTextConsole to allow control+scrollwheel to zoom the text

Language Additions / Improvements Copy Chapter

• @soleil0-0 - Additional Chinese translation
• @dancergraham - Additional French translation
• @ajvirSingh1313 - Hindi translation

Bug Fixes Copy Chapter

• Fixed bug where dynamic updates to a Dropdown would cause the selection to be lost
• Fixed performance issues where dynamic updates with large items would cause Gooey to hang
• @rotu fixed a bug in dynamic updates related to Popen usage.
• @neonbunny - resolved warning cause by missing return statement
• Fixed bug where terminal font and colors were not being set correctly
• Fixed mysterious RadioGroup issue where underlying WxWidgets would 'forget' the current selection under certain circumstances

Releases 1.0.6 Release Notes (`docs/releases/1.0.6-release-notes.md`) Copy Section

Gooey 1.0.6 Released! Copy Chapter

This is a minor release beefing up the new FilterableDropdown's search capabilities and performance. In the previous release, the dropdown was backed by WX's ListBox widget. 1.0.6 replaces this for a fully virtualized version which allows Gooey to operate on massive datasets without taking a hit to UI performance. Additionally, how Gooey internally filters for matches has also been updated. Choice are now backed by a trie for super fast lookup even against large data sets. Tokenization and match strategies can be customized to support just about any lookup style.

Head over to the Examples Repo to see the updated demo which now uses a dataset consisting of about 25k unique items.

New Gooey Options:

FilterableDropdown now takes a search_strategy in its gooey_options.

from gooey import Gooey, GooeyParser, PrefixTokenizers

gooey_options={
    'label_color': (255, 100, 100),
    'placeholder': 'Start typing to view suggestions',
    'search_strategy': {
        'type': 'PrefixFilter',
        'choice_tokenizer': PrefixTokenizers.ENTIRE_PHRASE,
        'input_tokenizer': PrefixTokenizers.REGEX('\s'),
        'ignore_case': True,
        'operator': 'AND',
        'index_suffix': False
    }
})

This gives control over how the choices and user input get tokenized, as well as how those tokenized matches get treated (ANDed together vs ORd). Want to match on any part of any word? Enable the index_suffix option to index all of your candidate words by their individual parts. e.g.

Word: 'Banana' 
Suffixes: ['Banana', 'anana', 'nana', 'ana']

These all get loaded into a trie for super fast lookup. Combine this with the WORDs tokenizer, and you get really fine grained search though your options!

Thank you to the current Patreon supporters! Copy Chapter

• Qteal
• Joseph Rhodes

Breaking Changes Copy Chapter

No breaking changes from 1.0.5.

Releases 1.0.7 Release Notes (`docs/releases/1.0.7-release-notes.md`) Copy Section

Gooey 1.0.7 Released! Copy Chapter

Lots of new stuff this release! We've got 3 new widget types, new gooey_options, as well as some quality of Life improvements for using Gooey Options.

New Widgets: IntegerField, DecimalField, and Slider Copy Section

Gooey now has 3 inputs specifically geared towards accepting numeric inputs. Previously, all Gooey had were text fields which you could add validators to in order to enforce only numbers were entered, but now we have top level widgets which do all of that out of the box!

Important Usage Note: since these numeric inputs don't allow any non-numeric characters to be entered, they do not give you the ability to blank them out. Unlike a TextField which can be left empty and thus have its value not passed to your program, the numeric inputs will always send a value. Thus, you have to have sane handling in user-land.

Checkout the Options docs for more details.

New Gooey Options: placeholder Copy Section

Widgets with text inputs now all accept a placeholder Gooey option.

add_argument('--foo', widget='TextField', gooey_options=options.TextField(
    placeholder='Type some text here!'
)

# or without the options helper 
add_argument('--foo', widget='TextField', gooey_options={
    'placeholder': 'Type some text here!'
})

New Validator option: RegexValidator Copy Section

add_argument('--foo', widget='TextField', gooey_options=options.TextField(
    placeholder='Type some text here!',
    validator=options.RegexValidator(
        test='\d{4}',
        message='Must be exactly 4 digits long!'
    )
)

# or without the options helper 
add_argument('--foo', widget='TextField', gooey_options={
    'placeholder': 'Type some text here!',
    'validator': {
        'type': 'RegexValidator',
        'test': '\d{4}',
        'message': 'Must be exactly 4 digits long!'
    }
})

New feature: Options helpers Copy Section

Gooey now has a top-level options module which can be imported. Previously, Gooey Options have been an opaque map. While great for openness / extensibility, it's pretty terrible from a discoverability / "what does this actually take again..?" perspective. The new options module aims to make using gooey_options easier and more discoverable.

from gooey import options

The goal is to enable IDE's to provide better auto-completion help as well as more REPL driven usefulness via help() and docstrings.

from gooey import options

parser.add_argument(
    '--foo', 
    help='Some foo thing',
    widget='FilterableDropdown',
    gooey_options=options.FilterableDropdown(
        placeholder='Search for a Foo',
        search_strategy=options.PrefixSearchStrategy(
            ignore_case=True 
        )
    ))

Note that these are just helpers for generating the right data shapes. They're still generating plain data behind the scenes and thus all existing gooey_options code remains 100% compatible.

Better Docs:

Which is to say, documentation which actually exists rather than not exist. You can inspect the docs live in the REPL or by hopping to the symbol in editors which support such things.

/* Detailed source-code truncated for AI context efficiency. */

Ideally, and eventually, we'll be able to completely type these options to increase visibility / usability even more. However, for backwards compatibility reasons, Gooey will continue to be sans anything more than the most basic of type hinting for the time being.

Breaking Changes Copy Chapter

No breaking API changes from 1.0.6 to 1.0.7. However, the strictness of existing Gooey Options has been increased, which could result in issues when upgrading from 1.0.6. In an attempt to be helpful, Gooey now throws an exception if invalid Gooey Options are supplied. This is to catch things like invalid types or ill-formed data. If you were passing bad data in 1.0.6, it will now be flagged as such in 1.0.7.

Thank you to the current [Patreon supporters](https://www.patreon.com/chriskiehl)! Copy Chapter

• Sponsors:
  • Qteal
• Individuals:
  • Joseph Rhodes
  • Nicholas

Releases 1.0.8 Release Notes (`docs/releases/1.0.8-release-notes.md`) Copy Section

Gooey 1.0.8 Released! Copy Chapter

Another minor Gooey release! This one brings a new global Gooey Option for setting initial values in the UI, support for version action types, plus a few bug/linting fixes.

Additionally, I continue to plug away at getting the test coverage to useful levels. We're now pushing 80% coverage which is making working on Gooey with confidence much easier!

New Gooey Options: initial_value Copy Section

This option lets you specify the value present in the widget when Gooey starts.

parser.add_argument('-my-arg', widget='Textarea', gooey_options={
    'initial_value': 'Hello world!'  
})

Or, using the new options helpers:

from gooey import options 
parser.add_argument('-my-arg', widget='Textarea', gooey_options=options.Textarea(
    initial_value='Hello World!'
))

If you've been using Gooey awhile, you'll recognize that this overlaps with the current behavior of default. The new initial_value enables you to supply a truly optional seed value to the UI. When using default, even if the user clears your value out of the UI, argparse will add it back in when it parses the CLI string. While this is often useful behavior, it prevents certain workflows from being possible. initial_value let's you control the UI independent of argparse. This means you can now, for instance, set a checkbox to be checked by default in the UI, but optionally allow the user to deselect it without having argprase re-populate the 'checked' state (a behavior which comes up frequently in the issue tracker due to it being technically correct, but also very confusing!).

action=version support Copy Section

When using action='version' Gooey will now map it a CheckBox widget type.

Other Fixes / Changes: Copy Section

• Bug fix: add missing translation step for tabbed group titles (@neonbunny)
• Linting: swap is not for != (@DrStrinky)

Breaking Changes Copy Chapter

No breaking API changes from 1.0.7 to 1.0.8

Thank you to the current [Patreon supporters](https://www.patreon.com/chriskiehl)! Copy Chapter

• Sponsors:
  • Qteal
• Individuals:
  • Joseph Rhodes
  • Nicholas
  • Joey

Releases 1.0.8.1 Release Notes (`docs/releases/1.0.8.1-release-notes.md`) Copy Section

Gooey 1.0.8.1 Released! Copy Chapter

This is a tiny intermediate release which just loosen Gooey's WxPython dependency from =4.1.0 to >=4.1.0 in setup.py. The strict version requirement was causing numerous installation issues across environments.

Releases 1.2.0 ALPHA Release Notes (`docs/releases/1.2.0-ALPHA-release-notes.md`) Copy Section

Gooey 1.2.0-ALPHA Released!

Warning: Copy Section

Upgrade with caution! 1.2.0 removes the experimental Dynamic Updates feature and replaces it with a new experimental Dynamic Updates feature! The two APIs are incompatible.

This release brings a whole host of new features to Gooey. Chief among them are the new Dynamic Updates and Validation functionality. This was effectively a rebuild of a substantial portion of Gooey's internal to enable a more client/server style functionality. This means that you have more control over the gooey's lifecycle, and can subscribe to high level events. Currently, FormSubmit, OnComplete, and OnError are supported, but more are on their way! Soon you'll be able to have fine grained control over the UI and its presentation, and still without having to write a single line of traditional GUI code!

Breaking Changes (1.0.8 -> 1.2.0) Copy Section

• Validation - the validation mechanism available via gooey_options has been removed entirely in favor of the new API.
• Dynamic Updates - there was previously minimal support for loading new data at run time. This has been revomed in favor of a new system which gives advanced control over the state of the UI.

New Features Copy Section

• Dynamic Updates and Validation - Checkout the README for details on how to get started. This feature is really hairy behind the scenes and involves all kinds of crazy monkey patching in order to work. Odds of encountering a bug or scenario that doesn't work for your use case is high in this initial release. Please fill out an issue if any problems pop up! Checkout the examples repo to see the new lifecycle hooks in action.
• Graceful Shutdown control - Gooey previously would SIGTERM your application when you tried to halt it while running. However, with 1.2.0, you have control over which signal Gooey sends when you request a shutdown. This gives you a chance to catch that signal and clean up and resources currently un use before shutting down.
• Better sys.argv handling - Gooey no longer mutates the global sys.argv variable. This caused people all kinds of problems -- most frequent being Gooey spawning multiple windows. This is now removed, and hopefully all the pain stemming from it as well.

Releases Pypi Distribution (`docs/releases/pypi-distribution.md`) Copy Section

Testing PyPi distribution before upload

The 1.0.4 release was botched when uploading to PyPi as it pulled in the 1.0.3 artifacts sitting in my dev directory. This meant that the 1.0.4 version was now clobbered on PyPi and could no longer be used. More care is needed when deploying.

How to test locally before uploading Copy Section

1. build the wheel

python pip_build_wheel.py

this will output the wheel to the dist/ directory.

2/. Copy the file location.

Copy the absolute path to the .gz output file. It will look something like this:

dist/Gooey-1.0.4.tar.gz

3. In a different virtual environment, install the local wheel

cd ~/projects/GooeyExamples
virtualenv venv 
source ./venv/Scripts/activate
pip install /path/to/local/dist/Gooey-1.0.4.tar.gz

If everything installs OK, you're good to upload.

python pip_deploy.py

Releases Release Checklist (`docs/releases/release-checklist.md`) Copy Section

Release Checklist

• Release commit is tagged
• The next release-branch is created
• CONTRIBUTING.md has been updated to point at the next release branch
• Release is created on Github
• All tests pass on 2.7 and 3.x
• All warnings are resolved (run tests with PYTHONWARNINGS=default)
• All Gooey Examples run and work as expected
• All new features have corresponding examples
• All new features have README updates
• Wx Inspection tool is removed from the runner
• all debug prints removed
• setup.py version is updated
• init.py version is updated
• types check (for the most part) ./venv/Scripts/python.exe -m mypy /path/to/python_bindings/types.py
• pip install of release branch works.
  • All Gooey Examples run and work as expected
• pypi is updated
• pypi pip install tested 2.7 & 3.x
  • All Gooey Examples run and work as expected
• Release notes written:
  • major features
  • bug fixes
  • language additions
  • breaking changes
  • contributors

--- METRICS ---

• Files Extracted: 18
• Estimated Token Budget: ~23233 tokens
• Canonical Reference: https://codewiki.google/github.com/chriskiehl/Gooey