# Technical Documentation: chriskiehl/Gooey
> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/chriskiehl/Gooey)
### Overview (`README.md`)
# Gooey
Turn (almost) any Python 3 Console Program into a GUI application with one line
Table of Contents
-----------------
- [Gooey](#gooey)
- [Table of contents](#table-of-contents)
- [Latest Update](#latest-update)
- [Quick Start](#quick-start)
- [Installation Instructions](#installation-instructions)
- [Usage](#usage)
- [Examples](#examples)
- [What It Is](#what-is-it)
- [Why Is It](#why)
- [Who is this for](#who-is-this-for)
- [How does it work](#how-does-it-work)
- [Internationalization](#internationalization)
- [Global Configuration](#global-configuration)
- [Layout Customization](#layout-customization)
- [Run Modes](#run-modes)
- [Full/Advanced](#advanced)
- [Basic](#basic)
- [No Config](#no-config)
- [Menus](#menus)
- [Dynamic Validation](#dynamic-validation)
- [Lifecycle Events and UI control](#lifecycle-events-and-ui-control)
- [Showing Progress](#showing-progress)
- [Elapsed / Remaining Time](#elapsed--remaining-time)
- [Customizing Icons](#customizing-icons)
- [Packaging](#packaging)
- [Screenshots](#screenshots)
- [Contributing](#wanna-help)
- [Image Credits](#image-credits)
----------------
## Quick Start
### Installation instructions
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
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](#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](#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
Gooey downloaded and installed? Great! Wanna see it in action? Head over the the [Examples Repository](https://github.com/chriskiehl/GooeyExamples) 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](https://github.com/chriskiehl/GooeyExamples/archive/master.zip)
What is it?
-----------
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?
---
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?
----------------
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?
-----------------
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.
| Parser Action | Widget | Example |
|:----------------------|-----------|------|
| store | TextCtrl | 
|
| store_const | CheckBox |
|
| store_true | CheckBox | |
| store_False | CheckBox| |
| version | CheckBox| |
| append | TextCtrl | |
| count | DropDown | 
|
| Mutually Exclusive Group | RadioGroup | 
|choice | DropDown | 
|
### GooeyParser
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:**
| Widget | Example |
|----------------|------------------------------|
| DirChooser, FileChooser, MultiFileChooser, FileSaver, MultiFileSaver | 
|
| DateChooser/TimeChooser | 
Please note that for both of these widgets the values passed to the application will always be in [ISO format](https://www.wxpython.org/Phoenix/docs/html/wx.DateTime.html#wx.DateTime.FormatISOTime) while localized values may appear in some parts of the GUI depending on end-user settings.
|
| PasswordField | 
|
| Listbox | |
| BlockCheckbox |
The default InlineCheck box can look less than ideal if a large help text block is present. `BlockCheckbox` moves the text block to the normal position and provides a short-form `block_label` for display next to the control. Use `gooey_options.checkbox_label` to control the label text |
| ColourChooser | 
|
| FilterableDropdown | 
|
| IntegerField | 
|
| DecimalField | 
|
| Slider | 
|
Internationalization
--------------------
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](https://github.com/chriskiehl/Gooey/graphs/contributors), Gooey currently comes pre-stocked with over 18 different translations!
Want to add another one? Submit a [pull request!](https://github.com/chriskiehl/Gooey/compare)
-------------------------------------------
Global Configuration
--------------------
Just about everything in Gooey's overall look and feel can be customized by passing arguments to the decorator.
| Parameter | Summary |
|-----------|---------|
| encoding | Text encoding to use when displaying characters (default: 'utf-8') |
| use_legacy_titles | Rewrites the default argparse group name from "Positional" to "Required". This is primarily for retaining backward compatibility with previous versions of Gooey (which had poor support/awareness of groups and did its own naive bucketing of arguments). |
| advanced | Toggles whether to show the 'full' configuration screen, or a simplified version |
| auto_start | Skips the configuration all together and runs the program immediately |
| language | Tells Gooey which language set to load from the `gooey/languages` directory.|
| target | Tells Gooey how to re-invoke itself. By default Gooey will find python, but this allows you to specify the program (and arguments if supplied).|
| suppress_gooey_flag | Should be set when using a custom `target`. Prevent Gooey from injecting additional CLI params |
|program_name | The name displayed in the title bar of the GUI window. If not supplied, the title defaults to the script name pulled from `sys.argv[0]`. |
| program_description | Sets the text displayed in the top panel of the `Settings` screen. Defaults to the description pulled from `ArgumentParser`. |
| default_size | Initial size of the window |
| fullscreen | start Gooey in fullscreen mode |
| required_cols | Controls how many columns are in the Required Arguments section
:warning: **Deprecation notice:** See [Layout Customization](https://github.com/chriskiehl/Gooey#layout-customization) for modern layout controls|
| optional_cols | Controls how many columns are in the Optional Arguments section
:warning: **Deprecation notice:** See [Layout Customization](https://github.com/chriskiehl/Gooey#layout-customization) for modern layout controls|
| dump_build_config | Saves a `json` copy of its build configuration on disk for reuse/editing |
| load_build_config | Loads a `json` copy of its build configuration from disk |
| monospace_display | Uses a mono-spaced font in the output screen
:warning: **Deprecation notice:** See [Layout Customization](https://github.com/chriskiehl/Gooey#layout-customization) for modern font configuration|
| image_dir | Path to the directory in which Gooey should look for custom images/icons |
| language_dir | Path to the directory in which Gooey should look for custom languages files |
| disable_stop_button | Disable the `Stop` button when running |
| show_stop_warning | Displays a warning modal before allowing the user to force termination of your program |
| force_stop_is_error | Toggles whether an early termination by the shows the success or error screen |
| show_success_modal | Toggles whether or not to show a summary modal after a successful run |
| show_failure_modal | Toggles whether or not to show a summary modal on failure |
| show_restart_button | Toggles whether or not to show the restart button at the end of execution |
| run_validators | Controls whether or not to have Gooey perform validation before calling your program |
| poll_external_updates | (Experimental!) When True, Gooey will call your code with a `gooey-seed-ui` CLI argument and use the response to fill out dynamic values in the UI (See: [Using Dynamic Values](#using-dynamic-values))|
| use_cmd_args | Substitute any command line arguments provided at run time for the default values specified in the Gooey configuration |
| return_to_config | When True, Gooey will return to the configuration settings window upon successful run |
| progress_regex | A text regex used to pattern match runtime progress information. See: [Showing Progress](#showing-progress) for a detailed how-to |
| progress_expr | A python expression applied to any matches found via the `progress_regex`. See: [Showing Progress](#showing-progress) for a detailed how-to |
| hide_progress_msg | Option to hide textual progress updates which match the `progress_regex`. See: [Showing Progress](#showing-progress) for a detailed how-to |
| disable_progress_bar_animation | Disable the progress bar |
| timing_options | This contains the options for displaying time remaining and elapsed time, to be used with `progress_regex` and `progress_expr`. [Elapsed / Remaining Time](#elapsed--remaining-time). Contained as a dictionary with the options `show_time_remaining` and `hide_time_remaining_on_complete`. Eg: `timing_options={'show_time_remaining':True,'hide_time_remaining_on_complete':True}` |
| show_time_remaining | Disable the time remaining text see [Elapsed / Remaining Time](#elapsed--remaining-time) |
| hide_time_remaining_on_complete | Hide time remaining on complete screen see [Elapsed / Remaining Time](#elapsed--remaining-time) |
| requires_shell | Controls whether or not the `shell` argument is used when invoking your program. [More info here](https://stackoverflow.com/questions/3172470/actual-meaning-of-shell-true-in-subprocess#3172488) |
| shutdown_signal | Specifies the `signal` to send to the child process when the `stop` button is pressed. See [Gracefully Stopping](https://github.com/chriskiehl/Gooey/tree/master/docs) in the docs for more info. |
| navigation | Sets the "navigation" style of Gooey's top level window.
Options: | TABBED | SIDEBAR |
|---|
 |  |
|
| 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](https://github.com/chriskiehl/Gooey/tree/master/docs) for additional details |
| menus | Show custom menu groups and items (see: [Menus](#menus) |
| clear_before_run | When true, previous output will be cleared from the terminal when running program again |
Layout Customization
--------------------
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.
| `show_sidebar=True` | `show_sidebar=False` | `navigation='TABBED'` | `tabbed_groups=True` |
|---------------------|----------------------|----------------------|------------------------|
| |
|
| |
**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
---------
Gooey has a handful of presentation modes so you can tailor its layout to your content type and user's level or experience.
### Advanced
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
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
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.
```python
@Gooey(auto_start=True)
def main ():
...
```
--------------------------------------
### Menus
>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:
```python
{
'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:
```python
{
'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](https://wxpython.org/Phoenix/docs/html/html_overview.html).
Example:
```python
{
'type': 'HtmlDialog',
'menuTitle': 'Fancy Dialog!',
'caption': 'Demo of the HtmlDialog',
'html': '''
![](/path/to/your/image.png")
Hello world!
Lorem ipsum dolor sit amet, consectetur
'''
}
```
**A full example:**
Two menu groups ("File" and "Help") with four menu items between them.
```python
@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
>: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.
```python
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.
```python
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.
```python
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
>: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.
```python
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`.
```python
parser = GooeyParser(
on_success=my_success_handler,
on_failure=my_failure_handler)
```
**Subscribing to the lifecycle events**
Just like [Validation](#dynamic-validation), these lifecycle events are opt-in. Pass the event you'd like to subscribe to into the `use_events` Gooey decorator argument.
```python
from gooey import Gooey, Events
@Gooey(use_events=[Events.ON_SUCCESS, Events.ON_ERROR])
def main():
...
```
-------------------------------------
## Showing Progress
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**
```python
@Gooey(progress_regex=r"^progress: (?P\d+)/(?P\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](https://github.com/chriskiehl/GooeyExamples) repository for more detailed usage and examples!
### Elapsed / Remaining Time
Gooey also supports tracking elapsed / remaining time when progress is used! This is done in a similar manner to that of the project [tqdm](https://github.com/tqdm/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.
```python
@Gooey(progress_regex=r"^progress: (?P\d+)/(?P\d+)$",
progress_expr="current / total * 100",
timing_options = {
'show_time_remaining':True,
'hide_time_remaining_on_complete':True,
})
```
--------------------------------------
## Customizing Icons
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
Thanks to some [awesome contributors](https://github.com/chriskiehl/Gooey/issues/58), packaging Gooey as an executable is super easy.
The tl;dr [pyinstaller](https://github.com/pyinstaller/pyinstaller) version is to drop this [build.spec](https://raw.githubusercontent.com/chriskiehl/Gooey/master/docs/packaging/build-win.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](https://github.com/chriskiehl/Gooey/blob/master/docs/packaging/Packaging-Gooey.md).
Screenshots
------------
| Flat Layout | Column Layout |Success Screen | Error Screen | Warning Dialog |
|-------------|---------------|---------------|--------------|----------------|
| 
| 
| 
| 
| 
|
| Custom Groups | Tabbed Groups | Tabbed Navigation | Sidebar Navigation | Input Validation |
|-------------|---------------|---------------|--------------|----------------|
| 
| | | | |
----------------------------------------------
Wanna help?
-----------
Code, translation, documentation, or graphics? All pull requests are welcome. Just make sure to checkout [the contributing guidelines](https://github.com/chriskiehl/Gooey/blob/master/CONTRIBUTING.md) first.
---
### Overview (`gooey/tests/integration/README.md`)
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`)
# 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:
```python
from gooey import GooeyParser
```
and replace `ArgumentParser` with `GooeyParser`
```python
# parser = ArgumentParser() # old busted
parser = GooeyParser() # new hotness
```
and with that, you're ready to rock.
## Overview
* Global Style/Layout Options
* Global Config Options
* Custom Widget Options
* Textarea
* BlockCheckbox
* Listbox
* RadioGroups
* Argument Group Options
## Global Style / Layout Options
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.
```python
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
})
```
| Keyword | Type | Description |
|---------|------|-------------|
| label_color | hex string | The foreground color of the label text (e.g. `#ff0000`) |
| label_bg_color | hex string | The background color of the label text. |
| help_color | hex string | The foreground color of the help text. |
| help_bg_color | hex string | The background color of the help text. |
| error_color | hex string | The foreground color of the error text (when visible). |
| error_bg_color | hex string | The background color of the error text (when visible). |
| show_label | bool | Toggles whether or not to display the label text |
| show_help | bool | Toggles whether or not to display the help text |
| visible | bool | Hides the entire widget when `False`. Note: the widget is still present in the UI and will still send along any default values that have been provided in code. This option is here for when you want to hide certain advanced / dangerous inputs from your GUI users. |
| full_width | bool | This is a layout hint for this widget. When `True` the widget will fill the entire available space within a given row. Otherwise, it will be sized based on the column rules provided elsewhere. |
## Global Config Options
> new in 1.0.8
All widgets in Gooey accept an `initial_value` option to seed the UI.
```python
parser.add_argument('-my-arg', widget='Textarea', gooey_options={
'initial_value': 'Hello world!'
})
```
## Individual Widget Options
A few widgets have additional options for controlling their layout and behavior.
### Textarea
```python
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
```python
parser.add_argument('-my-arg', widget='IntegerField', gooey_options={
'min': int,
'max': int,
'increment': int
})
```
### DecimalField
```python
parser.add_argument('-my-arg', widget='IntegerField', gooey_options={
'min': float,
'max': float,
'increment': float,
'precision': int # 0 - 20
})
```
### Slider
The Slider is just a reskinned IntegerField, so it has the same options
```python
parser.add_argument('-my-arg', widget='Slider', gooey_options={
'min': int,
'max': int,
'increment': int
})
```
### BlockCheckbox
```python
parser.add_argument('-my-arg', widget='BlockCheckbox', gooey_options={
# allows customizing the checkbox's label
'checkbox_label': str
})
```
### Listbox
```python
parser.add_argument('-my-arg', widget='Listbox', gooey_options={
# height of the listbox in pixels
'height': int
})
```
### Radio Group
```python
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
Argument Groups take a number of `gooey_options` to help control layout.
```python
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
})
```
| Keyword | Type | Description |
|---------|------|-------------|
| show_border | bool | When `True` a labeled border will surround all widgets added to this group. |
| show_underline | bool | Controls whether or not to display the underline when using the default border style |
| label_color | hex string | The foreground color for the group name |
| columns | int | Controls the number of widgets on each row |
| margin_top | int | specifies the top margin in pixels for this group |
## File and Folder choosers
File and Folder Choosers Groups take a number of `gooey_options` to help control default values.
```
/* Detailed source-code truncated for AI context efficiency. */
```
| Keyword | Type | Description |
|---------|------|-------------|
| wildcard | string | Sets the wildcard, which can contain multiple file types, for example: "BMP files (.bmp)|.bmp|GIF files (.gif)|.gif" |
| message | string | Sets the message that will be displayed on the dialog. |
| default_dir | string | The default directory |
| default_file | string | The default filename |
| default_path | string | The default path |
---
### Gracefully Stopping (`docs/Gracefully-Stopping.md`)
# Gracefully Stopping a Running Process
>New in v1.0.9!
**Contents:**
* [How to tell Gooey which shutdown signal to use](#how-to-tell-gooey-which-signal-to-use)
* [How to catch KeyboardInterrupts](#How-to-catch-KeyboardInterrupts)
* [How to catch general interrupt signals](#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:
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.
```python
import signal
@Gooey(shutdown_signal=signal.CTRL_C_EVENT)
def main():
...
```
### How to catch KeyboardInterrupts:
Keyboard interrupts are triggered in response to the `CTRL_C_EVENT` signal.
```python
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.
```python
try
# your code here
except KeyboardInterrupt:
# cleanup and shutdown or ignore
```
### How to catch general interrupt signals
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.
```python
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`)
# 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](https://github.com/chriskiehl/GooeyExamples/blob/master/examples/richtext_demo.py)
You can enable this mode by passing the `richtext_controls` option to the Gooey decorator.
```python
@Gooey(richtext_controls=True)
def main():
...
```
### Usage
The [colored library](https://pypi.org/project/colored/) provides functions for adding markup controls to your text. Gooey supports the foreground (`fg`) and attributes (`attr`).
```python
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.
```python
print(stylize('Hello world!', fg('red') + attr('bold')))
```
> Note that you combine the foreground and attribute functions with the `+` operator.
### Attributes:
Richtext currently supports the following attributes:
|Code | Description |
|:----|------------------|
| 1 | bold |
| 4 | underlined |
| 0 | reset |
| 21 | res_bold |
| 24 | res_underlined |
These can be used either via their code (`attr(1)`) or their verbose form (`attr('bold')`)
### Foreground Colors:
Similar to the Attributes, foreground colors can be specified either by their code (`fg(2)`) or verbose form (`fg('green')`)
|Code | Description |
|:----|---------------------|
| 0 | black |
| 1 | red |
| 2 | green |
| 3 | yellow |
| 4 | blue |
| 5 | magenta |
| 6 | cyan |
| 7 | light_gray |
| 8 | dark_gray |
| 9 | light_red |
| 10 | light_green |
| 11 | light_yellow |
| 12 | light_blue |
| 13 | light_magenta |
| 14 | light_cyan |
| 15 | white |
| 16 | grey_0 |
| 17 | navy_blue |
| 18 | dark_blue |
| 19 | blue_3a |
| 20 | blue_3b |
| 21 | blue_1 |
| 22 | dark_green |
| 23 | deep_sky_blue_4a |
| 24 | deep_sky_blue_4b |
| 25 | deep_sky_blue_4c |
| 26 | dodger_blue_3 |
| 27 | dodger_blue_2 |
| 28 | green_4 |
| 29 | spring_green_4 |
| 30 | turquoise_4 |
| 31 | deep_sky_blue_3a |
| 32 | deep_sky_blue_3b |
| 33 | dodger_blue_1 |
| 34 | green_3a |
| 35 | spring_green_3a |
| 36 | dark_cyan |
| 37 | light_sea_green |
| 38 | deep_sky_blue_2 |
| 39 | deep_sky_blue_1 |
| 40 | green_3b |
| 41 | spring_green_3b |
| 42 | spring_green_2a |
| 43 | cyan_3 |
| 44 | dark_turquoise |
| 45 | turquoise_2 |
| 46 | green_1 |
| 47 | spring_green_2b |
| 48 | spring_green_1 |
| 49 | medium_spring_green |
| 50 | cyan_2 |
| 51 | cyan_1 |
| 52 | dark_red_1 |
| 53 | deep_pink_4a |
| 54 | purple_4a |
| 55 | purple_4b |
| 56 | purple_3 |
| 57 | blue_violet |
| 58 | orange_4a |
| 59 | grey_37 |
| 60 | medium_purple_4 |
| 61 | slate_blue_3a |
| 62 | slate_blue_3b |
| 63 | royal_blue_1 |
| 64 | chartreuse_4 |
| 65 | dark_sea_green_4a |
| 66 | pale_turquoise_4 |
| 67 | steel_blue |
| 68 | steel_blue_3 |
| 69 | cornflower_blue |
| 70 | chartreuse_3a |
| 71 | dark_sea_green_4b |
| 72 | cadet_blue_2 |
| 73 | cadet_blue_1 |
| 74 | sky_blue_3 |
| 75 | steel_blue_1a |
| 76 | chartreuse_3b |
| 77 | pale_green_3a |
| 78 | sea_green_3 |
| 79 | aquamarine_3 |
| 80 | medium_turquoise |
| 81 | steel_blue_1b |
| 82 | chartreuse_2a |
| 83 | sea_green_2 |
| 84 | sea_green_1a |
| 85 | sea_green_1b |
| 86 | aquamarine_1a |
| 87 | dark_slate_gray_2 |
| 88 | dark_red_2 |
| 89 | deep_pink_4b |
| 90 | dark_magenta_1 |
| 91 | dark_magenta_2 |
| 92 | dark_violet_1a |
| 93 | purple_1a |
| 94 | orange_4b |
| 95 | light_pink_4 |
| 96 | plum_4 |
| 97 | medium_purple_3a |
| 98 | medium_purple_3b |
| 99 | slate_blue_1 |
| 100 | yellow_4a |
| 101 | wheat_4 |
| 102 | grey_53 |
| 103 | light_slate_grey |
| 104 | medium_purple |
| 105 | light_slate_blue |
| 106 | yellow_4b |
| 107 | dark_olive_green_3a |
| 108 | dark_green_sea |
| 109 | light_sky_blue_3a |
| 110 | light_sky_blue_3b |
| 111 | sky_blue_2 |
| 112 | chartreuse_2b |
| 113 | dark_olive_green_3b |
| 114 | pale_green_3b |
| 115 | dark_sea_green_3a |
| 116 | dark_slate_gray_3 |
| 117 | sky_blue_1 |
| 118 | chartreuse_1 |
| 119 | light_green_2 |
| 120 | light_green_3 |
| 121 | pale_green_1a |
| 122 | aquamarine_1b |
| 123 | dark_slate_gray_1 |
| 124 | red_3a |
| 125 | deep_pink_4c |
| 126 | medium_violet_red |
| 127 | magenta_3a |
| 128 | dark_violet_1b |
| 129 | purple_1b |
| 130 | dark_orange_3a |
| 131 | indian_red_1a |
| 132 | hot_pink_3a |
| 133 | medium_orchid_3 |
| 134 | medium_orchid |
| 135 | medium_purple_2a |
| 136 | dark_goldenrod |
| 137 | light_salmon_3a |
| 138 | rosy_brown |
| 139 | grey_63 |
| 140 | medium_purple_2b |
| 141 | medium_purple_1 |
| 142 | gold_3a |
| 143 | dark_khaki |
| 144 | navajo_white_3 |
| 145 | grey_69 |
| 146 | light_steel_blue_3 |
| 147 | light_steel_blue |
| 148 | yellow_3a |
| 149 | dark_olive_green_3 |
| 150 | dark_sea_green_3b |
| 151 | dark_sea_green_2 |
| 152 | light_cyan_3 |
| 153 | light_sky_blue_1 |
| 154 | green_yellow |
| 155 | dark_olive_green_2 |
| 156 | pale_green_1b |
| 157 | dark_sea_green_5b |
| 158 | dark_sea_green_5a |
| 159 | pale_turquoise_1 |
| 160 | red_3b |
| 161 | deep_pink_3a |
| 162 | deep_pink_3b |
| 163 | magenta_3b |
| 164 | magenta_3c |
| 165 | magenta_2a |
| 166 | dark_orange_3b |
| 167 | indian_red_1b |
| 168 | hot_pink_3b |
| 169 | hot_pink_2 |
| 170 | orchid |
| 171 | medium_orchid_1a |
| 172 | orange_3 |
| 173 | light_salmon_3b |
| 174 | light_pink_3 |
| 175 | pink_3 |
| 176 | plum_3 |
| 177 | violet |
| 178 | gold_3b |
| 179 | light_goldenrod_3 |
| 180 | tan |
| 181 | misty_rose_3 |
| 182 | thistle_3 |
| 183 | plum_2 |
| 184 | yellow_3b |
| 185 | khaki_3 |
| 186 | light_goldenrod_2a |
| 187 | light_yellow_3 |
| 188 | grey_84 |
| 189 | light_steel_blue_1 |
| 190 | yellow_2 |
| 191 | dark_olive_green_1a |
| 192 | dark_olive_green_1b |
| 193 | dark_sea_green_1 |
| 194 | honeydew_2 |
| 195 | light_cyan_1 |
| 196 | red_1 |
| 197 | deep_pink_2 |
| 198 | deep_pink_1a |
| 199 | deep_pink_1b |
| 200 | magenta_2b |
| 201 | magenta_1 |
| 202 | orange_red_1 |
| 203 | indian_red_1c |
| 204 | indian_red_1d |
| 205 | hot_pink_1a |
| 206 | hot_pink_1b |
| 207 | medium_orchid_1b |
| 208 | dark_orange |
| 209 | salmon_1 |
| 210 | light_coral |
| 211 | pale_violet_red_1 |
| 212 | orchid_2 |
| 213 | orchid_1 |
| 214 | orange_1 |
| 215 | sandy_brown |
| 216 | light_salmon_1 |
| 217 | light_pink_1 |
| 218 | pink_1 |
| 219 | plum_1 |
| 220 | gold_1 |
| 221 | light_goldenrod_2b |
| 222 | light_goldenrod_2c |
| 223 | navajo_white_1 |
| 224 | misty_rose1 |
| 225 | thistle_1 |
| 226 | yellow_1 |
| 227 | light_goldenrod_1 |
| 228 | khaki_1 |
| 229 | wheat_1 |
| 230 | cornsilk_1 |
| 231 | grey_100 |
| 232 | grey_3 |
| 233 | grey_7 |
| 234 | grey_11 |
| 235 | grey_15 |
| 236 | grey_19 |
| 237 | grey_23 |
| 238 | grey_27 |
| 239 | grey_30 |
| 240 | grey_35 |
| 241 | grey_39 |
| 242 | grey_42 |
| 243 | grey_46 |
| 244 | grey_50 |
| 245 | grey_54 |
| 246 | grey_58 |
| 247 | grey_62 |
| 248 | grey_66 |
| 249 | grey_70 |
| 250 | grey_74 |
| 251 | grey_78 |
| 252 | grey_82 |
| 253 | grey_85 |
| 254 | grey_89 |
| 255 | grey_93 |
| 256 | default |
---
### Pull Request Template (`docs/pull_request_template.md`)
Hello there!
Make sure you've followed the [Contributing](https://github.com/chriskiehl/Gooey/blob/master/CONTRIBUTING.md) guidelines before finalizing your pull request.
TL;DR:
- [ ] You're opening this PR against the current [release branch](https://github.com/chriskiehl/Gooey/blob/master/CONTRIBUTING.md#development-overview)
- [ ] 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`)
# Using Custom Images while Packaging
> Note: if you're new to packaging Gooey, checkout the main [Packaging Guide](https://github.com/chriskiehl/Gooey/blob/doc-improvements/docs/packaging/Packaging-Gooey.md) 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.
```python
@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.
```python
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`)
# 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](https://github.com/chriskiehl/Gooey/issues/259).
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](http://www.pyinstaller.org/). 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](http://pythonhosted.org/PyInstaller/#using-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](https://raw.githubusercontent.com/chriskiehl/Gooey/master/docs/packaging/build-win.spec).
* For OSX users, you'll want [this one](https://raw.githubusercontent.com/chriskiehl/Gooey/master/docs/packaging/build-osx.spec).
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
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
**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](https://github.com/pyinstaller/pyinstaller/wiki/FAQ) for more details.
---
### Releases 1.0.3 Release Notes (`docs/releases/1.0.3-release-notes.md`)
# Gooey 1.0.3 Released!
After cooking for far too long, **Gooey 1.0.3 is released!**
Grab the latest version:
* [github](https://github.com/chriskiehl/Gooey)
* [PyPi](TODO)
Runnable demos for all the new features can be found in the [Examples repo](https://github.com/chriskiehl/GooeyExamples).
## Overview:
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
### Fancy Layout controls!
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
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
Thanks to @NathanRichard, Gooey can now optionally honor terminal control sequences and display Rich Text in the output panel.
### New Gooey Program Icon
New icon provided by professional cool guy and crazy talented UX designer [Justin Rhee](https://www.linkedin.com/in/justinrhee/).
## Additional features
* 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
No breaking changes between `1.0.0` and `1.1.0`!
## Language Additions / Improvements
* Completed Italian translation - @gison93
* Updated French translation - @NathanRichard
* Updated Hebrew translation - @eturkes
## Bug Fixes
* 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`)
# 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
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
### Widgets: TimeChooser
Usage:
```python
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
Usage:
```python
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
@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.
```python
@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
- Added option to start Gooey in full screen mode
## Language Additions / Improvements
* @foben - documentation fixes
* @gediz - turkish translations
* @dsardelic - bosnian & Croatian translations
* @partrita - Korean translations
## Bug Fixes
- 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`)
## Gooey 1.0.5 Released!
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!
* Qteal
* Joseph Rhodes
# New widgets:
### FilterableDropdown
You can checkout a runnable example in the GooeyExamples repo [here](https://github.com/chriskiehl/GooeyExamples/blob/1.0.5-release/examples/FilterableDropdown.py)
Example Code:
```python
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
@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](https://github.com/chriskiehl/GooeyExamples/blob/master/examples/example_time_remaining.py)
Example Code:
```python
@Gooey(timing_options={
'show_time_remaining':True,
'hide_time_remaining_on_complete':True
})
```
## Breaking Changes
* (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
* @neonbunny enabled Parsers to use configuration from parents.
* @eladeyal-intel updated `RichTextConsole` to allow control+scrollwheel to zoom the text
## Language Additions / Improvements
* @soleil0-0 - Additional Chinese translation
* @dancergraham - Additional French translation
* @ajvirSingh1313 - Hindi translation
## Bug Fixes
* 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`)
## Gooey 1.0.6 Released!
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](https://github.com/chriskiehl/GooeyExamples) 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`.
```python
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!
* Qteal
* Joseph Rhodes
## Breaking Changes
No breaking changes from 1.0.5.
---
### Releases 1.0.7 Release Notes (`docs/releases/1.0.7-release-notes.md`)
## Gooey 1.0.7 Released!
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
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](https://github.com/chriskiehl/Gooey/blob/master/docs/Gooey-Options.md) for more details.
### New Gooey Options: placeholder
Widgets with text inputs now all accept a `placeholder` Gooey option.
```python
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
```python
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
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.
```python
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.
```python
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
**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)!
* Sponsors:
* Qteal
* Individuals:
* Joseph Rhodes
* Nicholas
---
### Releases 1.0.8 Release Notes (`docs/releases/1.0.8-release-notes.md`)
## Gooey 1.0.8 Released!
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
This option lets you specify the value present in the widget when Gooey starts.
```python
parser.add_argument('-my-arg', widget='Textarea', gooey_options={
'initial_value': 'Hello world!'
})
```
Or, using the new `options` helpers:
```python
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
When using `action='version'` Gooey will now map it a CheckBox widget type.
### Other Fixes / Changes:
* Bug fix: add missing translation step for tabbed group titles (@neonbunny)
* Linting: swap `is not` for `!=` (@DrStrinky)
## Breaking Changes
**No breaking API changes from 1.0.7 to 1.0.8**
## Thank you to the current [Patreon supporters](https://www.patreon.com/chriskiehl)!
* Sponsors:
* Qteal
* Individuals:
* Joseph Rhodes
* Nicholas
* Joey
---
### Releases 1.0.8.1 Release Notes (`docs/releases/1.0.8.1-release-notes.md`)
## Gooey 1.0.8.1 Released!
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`)
# Gooey 1.2.0-ALPHA Released!
### Warning:
>**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)
* **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
* **Dynamic Updates and Validation** - Checkout the [README](https://github.com/chriskiehl/Gooey/blob/master/README.md) 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](https://github.com/chriskiehl/GooeyExamples/blob/master/examples/lifecycle_hooks.py) 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`)
# 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
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`)
# 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