Skip to content

Run

The main access, start here. Wrap your configuration dataclass into run to access the interface. An interface is chosen automatically, with the preference of the graphical one, regressed to a text interface for machines without display. Besides, if given a configuration dataclass, the function enriches it with the CLI commands and possibly with the default from a config file if such exists. It searches the config file in the current working directory, with the program name ending on .yaml, ex: program.py will fetch ./program.yaml.

Parameters:

Name Type Description Default
env_or_list Type[EnvClass] | list[Type[Command]] | None
  • dataclass Dataclass with the configuration. Their values will be modified with the CLI arguments.
  • list of Commands let you create multiple commands within a single program, each with unique options.
  • None You need just the dialogs, no CLI/config file parsing.
None
ask_on_empty_cli bool

If program was launched with no arguments (empty CLI), invokes self.form() to edit the fields. (Withdrawn when ask_for_missing happens.)

@dataclass
class Env:
number: int = 3
text: str = ""
m = run(Env, ask_on_empty=True)

$ program.py  #  omitting all parameters
# Dialog for `number` and `text` appears
$ program.py --number 3
# No dialog appears
False
title str

The main title. If not set, taken from prog or program name.

''
config_file Path | str | bool

File to load YAML to be merged with the configuration. You do not have to re-define all the settings in the config file, you can choose a few. If set to True (default), we try to find one in the current working dir, whose name stem is the same as the program's. Ex: program.py will search for program.yaml. If False, no config file is used.

True
add_verbosity bool

Adds the verbose flag that automatically sets the level to logging.INFO (-v) or logging.DEBUG (-vv).

import logging
logger = logging.getLogger(__name__)

m = run(Env, add_verbosity=True)
logger.info("Info shown") # needs `-v` or `--verbose`
logger.debug("Debug not shown")  # needs `-vv`
# $ program.py --verbose
# Info shown
$ program.py --verbose
Info shown
True
ask_for_missing bool

If some required fields are missing at startup, we ask for them in a UI instead of program exit.

@dataclass
class Env:
    required_number: int
m = run(Env, ask_for_missing=True)
$ program.py  # omitting --required-number
# Dialog for `required_number` appears
True
interface Type[Mininterface] | Literal['gui'] | Literal['tui']

Which interface to prefer. By default, we use the GUI, the fallback is the TUI. You may write "gui" or "tui" literal or pass a specific Mininterface type, see the full list of possible interfaces.

None
args Optional[Sequence[str]]

Parse arguments from a sequence instead of the command line.

None

Kwargs: The same as for argparse.ArgumentParser.

Returns:

Type Description
Mininterface[EnvClass]

An interface, ready to be used.

You cay context manager the function by a with statement. The stdout will be redirected to the interface (ex. a GUI window).

from dataclasses import dataclass
from mininterface import run

@dataclass
class Env:
    my_number: int = 4

with run(Env) as m:
    print(f"Your important number is {m.env.my_number}")
    boolean = m.is_yes("Is that alright?")

Small window with the text 'Your important number' The same in terminal'