Qargparse.py

QArgparse

Build settings-style graphical user interfaces with Python's argparse syntax.

import sys
from Qt import QtWidgets
from qargparse import QArgumentParser

app = QtWidgets.QApplication(sys.argv)

parser = QArgumentParser(description="My first graphical parser")
parser.add_argument("name", type=str, help="Your name")
parser.add_argument("age", type=int, help="Your age")
parser.add_argument("height", type=float, help="Your height")
parser.add_argument("alive", type=bool, help="Your state")
parser.show()

app.exec_()

Features

• [x] Automatic user interface for settings-style GUIs
• [x] Automatic tooltips from argument help=
• [x] Persistence to disk
• [x] Rich selection of types
• [x] Infer type from default value
• [x] Imperative and declarative mode
• [x] Tab-support for transitioning between arguments
• [x] Automatic label from name
• [x] Dual PEP8 and Qt syntax
• [ ] Theme support
• [x] HDPI support
• [x] Min/max values for sliders
• [ ] Wrap any instance of argparse.ArgumentParser with a GUI
• [ ] Argument Icons, for extra flare
• [ ] Argument Groups, e.g. tree view or side-panel

An example of use from within Maya.

<img width=600 src=https://user-images.githubusercontent.com/2152766/98442256-8a0e3880-20fb-11eb-8f1a-4524f297f324.gif>

• See examples.py

<br>

Types

In addition to being able to subclass and create your own widgets, these are the ones included out-of-the-box.

| Type | Description | Example |:------------|:--------------------------|:--------------------------------- | Boolean | Checkbox for on/off state | | Tristate | Checkbox with 3 states | | Integer | Whole number | | Float | Fraction | | Range | Two numbers, a start and an end | | String | A single line of text | | Text | A multi-line segment of text | | Info | Read-only single line of text | | Color | An RGB or HSV color | | Button | A clickable button | | Toggle | A checkable button | | Enum | Multiple choice | | Separator | A visual separation between subsequent arguments | | List | Multiple string-values | | Path | A formatted string, with OS-specific file-browser | | EnvironmentVariable | A key/value string with limited character support | | EnvironmentPath | An os.pathsep-separated string | | Color | A color with visual swatch and hex, HSV and RGB support | | Image | A Path with thumbnail and restrictions on file extension |

<br>

Install

Download or copy/paste qargparse.py into your project, there are no dependencies other than PyQt5 or PySide2.

# Test it from a command-line like this
$ python -m qargparse --demo

<br>

Usage

Use qargparse.QArgumentParser as you would argparse.ArgumentParser.

import sys
from Qt import QtWidgets
from qargparse import QArgumentParser

app = QtWidgets.QApplication(sys.argv)

parser = QArgumentParser(description="My first graphical parser")
parser.add_argument("name", type=str, help="Your name")
parser.add_argument("age", type=int, help="Your age")
parser.add_argument("height", type=float, help="Your height")
parser.add_argument("alive", type=bool, help="Your state")
parser.show()

app.exec_()

Or declaratively, using explicit types.

import qargparse
parser = qargparse.QArgumentParser([
    qargparse.String("name", help="Your name"),
    qargparse.Integer("age", help="Your age"),
    qargparse.Float("height", help="Your height"),
    qargparse.Boolean("alive", help="Your state"),
])

Types can also be inferred by their default value.

import qargparse
parser = qargparse.QArgumentParser()
parser.add_argument("name", default="My Name")  # `str` inferred
parser.add_argument("age", default=54)  # `int` inferred

<br>

Default and Initial Values

There are two seemingly similar values per argument.

Boolean("alive", default=True, initial=False)

What does this mean?

1. False is the initial value displayed in the UI
2. True is the value returned to when the value is reset

This way, you can store the current state of values elsewhere, such as on disk, and launch the UI with those values set, whilst still allowing the user to spot which values differs from their default values.

"Initial" is the value you would typically store on disk, keeping defaults as immutable somewhere in your application code.

<br>

Types

In addition to standard types, QArgparse also supports user interface types.

import qargparse
qargparse.Button("press me", help="See what happens!")

<br>

Camel and Snake

Consistency is important. Sometimes you work with a camel_case codebase, sometimes not. This library supports both, use the one which best suits your current codebase.

import qargparse
qargparse.addArgument()
qargparse.add_argument()

<br>

Style

Customise the user experience, with qargparse.DefaultStyle.

style = qargparse.DefaultStyle.copy()
style["comboboxFillWidth"] = True
parser = qargparse.QArgumentParser(style=style)
parser.show()

<br>

Signals

Respond to any change via the .changed signal.

import qargparse

def on_changed(argument):
    print("%s was changed!" % argument["name"])

args = [
    qargparse.Integer("age")
]

parser = qargparse.QArgumentParser(args)
parser.changed.connect(on_changed)

Or respond to individual changes.

import qargparse

def on_pressed():
    print("%s was changed!" % button["name"])

button = qargparse.Button("press me")
button.changed.connect(on_pressed)

parser = qargparse.QArgumentParser([button])