ArgUI

An automatic, terminal based interactive interface for any Python 3 argparse command line with keyboard and mouse support.

• ArgUI
  • See It in Action
  • Usage
    • Install as a Dependency
    • Setup Your Argparse
    • Run Your Program
    • Navigation
    • Advanced Argument Types
      • Example Usage
      • File Select
  • Development Setup

---

See It in Action

Get a feel for the features of ArgUI using the Demo.py code included in this project.

Usage

Install as a Dependency

The ArgUI package is available on PyPi.

It can be installed by calling: pip install argparse-interface

Setup Your Argparse

ArgUI supports wrapping any implementation of the Python 3 argparse native library. This will all you to use both standard terminal and interface modes to interact with your program.

# Import
import argparse
import argui

# Setup your ArgumentParser normally
parser = argparse.ArgumentParser(prog="Demo")

# `add_argument`, `add_argument_group`, etc...

# Wrap your parser
interface = argui.Wrapper(parser)

# Get arguments
args: argparse.Namespace = interface.parseArgs()

# `args` is the same as if you had called `parser.parse_args()`

See Demo.py for more information.

Run Your Program

Your program can now be run in both CLI and GUI modes.

To run in CLI mode, simply use your script as normal like python foo.py -h.

To run in GUI mode, provide only the --gui (by default) argument like python foo.py --gui.

Navigation

Mouse navigation of the GUI is possible in most terminals.

There are known issues with the VSCode terminal on Windows 10 and some others. However, Mouse navigation does work in Powershell when opened on its own.

Keyboard navigation is always available using Tab, Arrow Keys, and Enter. But make note that if you are using a terminal within another program (like VSCode), that some more advanced keyboard commands (like CTRL+S) may be captured by the container program and not sent to the GUI.

Advanced Argument Types

ArgUI also provides a number of meta types to be used with the .add_argument(type=...) function to add additional functionality to the interface mode.

These can be accessed with import argui.types.

Example Usage

Meta Types can be used for the type keyword argument anywhere you call the add_argument(...) function.

# Import
import argparse
import argui
from argui.types import FileSelectFile

# Setup your ArgumentParser normally
parser = argparse.ArgumentParser(prog="Demo")

# Define your arguments
parser.add_argument(
    "-p",
    "--path",
    type=FileSelectFile(exts=[".png", ".jpg"]), # Instantiate the Meta Type
    help="A file or directory path argument"
)

# Wrap the parser with ArgUI and use as normal (see above)

File Select

All options will show the File Select input in the GUI mode and operate as advanced types in the CLI mode.

Type	Effect	Notes
pathlib.Path (native)	Allows for any file or directory to be selected.	Provided as an uninstantiated type like: type=Path
FileSelectFile	Allows only files to be selected. Optionally restricts selection to specified file types.	Accepts a list of extensions to whitelist.
FileSelectDir	Allows only directories to be selected.

Development Setup

1. Clone this repo and enter the directory with a terminal.
2. Setup a Python Env: python -m venv .venv --prompt "argUI"
3. Enter the Python Env.
4. Install requirements: pip install -r requirements.txt