Skip to content

Settings

UI Settings

The UI behaviour might be modified via an settings object. This can be passed to the run function or defined through a config file. Settings defined in the config file have bigger priority. Every interface has its own settings object.

Passing the settings to the run method:

from mininterface.settings import MininterfaceSettings

opt = MininterfaceSettings()
run(settings=opt)

Specifying only the GuiSettings: 

from mininterface.settings import GuiSettings

opt = GuiSettings(combobox_since=1)
run(settings=opt)

Specifying the GuiSettings + turning off the mnemonic for all UIs (not only gui, but also text, ...): 

from mininterface.settings import MininterfaceSettings, GuiSettings, UiSettings

opt = MininterfaceSettings(
    gui=GuiSettings(combobox_since=1),
    ui=UiSettings(mnemonic=False)
)
run(settings=opt)

Specifying via dataclasses is very convenient as your ID suggests all the options available, including its hints.

Config file special section

In a YAML config file, use a special section 'mininterface' to set up the UI. For example, this stub will enforce your program to use the Tui interface.

mininterface:
    interface: tui

Complete example

Source of program.py, we have one single attribute foo:

from typing import Annotated
from dataclasses import dataclass
from mininterface import run, Options

@dataclass
class Env:
    foo: Annotated["str", Options("one", "two")] = "one"

m = run(Env)
m.form()

Source of program.yaml will enforce the comboboxes:

number: 5
mininterface:
    gui:
        combobox_since: 1

The difference when using such configuration file.

Configuration not used Configuration used

Inheritance

The individual setting items are inherited, while the descendants have the higher priority. Ex. TuiSettings works as a default for TextSettings and TextualSettings.

graph LR
GuiSettings --> UiSettings
TuiSettings  --> UiSettings
TextualSettings --> TuiSettings
TextSettings --> TuiSettings

Ex. this config file sets the UiSettings item mnemonic to None for TuiSettings and more specifically to False for TextSettings.

mininterface:
    tui:
        mnemonic: null
    text:
        mnemonic: False

For the different interfaces, the value varies this way:

interface mnemonic value
gui True (the UiSettings item default)
textual None
text False

The settings object

MininterfaceSettings

interface: Optional[InterfaceName] = None

Enforce an interface. By default, we choose automatically.

UiSettings

toggle_widget: str = 'f4'

Shortcut to toggle widgets like secret fields, file picker, and datetime dialog.

The shortcut should be in Textual format (e.g., "ctrl+t", "f4"). This format will be automatically converted to the appropriate format for each interface (e.g., "" for Tkinter).

Examples:

  • "ctrl+t" for Control+T
  • "alt+f" for Alt+F
  • "f4" for F4 key
  • "cmd+s" for Command+S (macOS)

mnemonic: Optional[bool] = True

Allow users to access fields with the Alt+char shortcut.

  • True: All Tags with Tag(mnemonic=char|True|None) will have a mnemonic enabled.
  • False: All mnemonic is disabled, even if configured via Tag(mnemonic=char).
  • None: All Tags with Tag(mnemonic=char|True) will have a mnemonic enabled.

mnemonic_hidden: bool = False

If True, the field label is not underlined to mark the mnemonic.

GuiSettings

combobox_since: int = 10

The threshold to switch from radio buttons to a combobox.

Without combobox:

Default

With combobox:

Combobox

(Note, there must be multiple fields for combobox to appear.)

radio_select_on_focus: bool = False

Select the radio button on focus. Ex. when navigating by arrows.

TuiSettings

TextualSettings

TextSettings

mnemonic_over_number: Optional[bool] = None

Even when mnemonic can be determined, use rather number as a shortcut.

By default if None, determine those with Tag(mnemonic=char|True):

>     ok
[1] foo1: ×
[2] foo2: ×
[g] foo3: ×

If True, determine also those having Tag(mnemonic=None):

>     ok
[f] foo1: ×
[o] foo2: ×
[g] foo3: ×

If False, we prefer numbers:

>     ok
[1] foo1: ×
[2] foo2: ×
[3] foo3: ×

The original code:

from dataclasses import dataclass
from typing import Annotated
from mininterface import Tag, run
from mininterface.settings import MininterfaceSettings, TextSettings


@dataclass
class Env:
    foo1: bool = False
    foo2: bool = False
    foo3: Annotated[bool, Tag(mnemonic="g")] = False


m = run(Env, settings=MininterfaceSettings(text=TextSettings(mnemonic_over_number=True)))
m.form()
quit()

CliSettings

omit_arg_prefixes: bool = False

Simplify argument names by removing parent field prefixes from flags.

$ ./program.py --help
# omit_arg_prefixes = False
usage: program.py [-h] [-v] --arg.subarg.text STR
# omit_arg_prefixes = True
usage: program.py [-h] [-v] --text STR
Code 
@dataclass
class SubMessage:
    text: str

@dataclass
class Message:
    subarg: SubMessage

@dataclass
class Env:
    arg: Message

run(Env, settings=CliSettings(omit_arg_prefixes=True/False))

See: https://brentyi.github.io/tyro/api/tyro/conf/#tyro.conf.OmitArgPrefixes

omit_subcommand_prefixes: bool = False

Simplify subcommand names by removing parent field prefixes from subcommands.

$ ./program.py --help
# omit_subcommand_prefixes = False
usage: program.py [-h] [-v] {subcommand:message,subcommand:console}
# omit_subcommand_prefixes = True
usage: program.py [-h] [-v] {message,console}
Code 
@dataclass
class SubMessage:
    text: str

@dataclass
class Message:
    subarg: SubMessage

@dataclass
class Env:
    subcommand: Message | Console

run(Env, settings=CliSettings(omit_subcommand_prefixes=True/False))

See: https://brentyi.github.io/tyro/api/tyro/conf/#tyro.conf.OmitSubcommandPrefixes

disallow_none: bool = False

Disallow passing None in via the command-line interface for union types containing None.

$ ./program.py --help
# disallow_none = False
usage: program.py [-h] [-v] [--field {None}|INT]
# disallow_none = True
usage: program.py [-h] [-v] [--field INT]
Code 
@dataclass
class Env:
    field: int | None = None
run(Env, settings=CliSettings(disallow_none=True/False))

See: https://brentyi.github.io/tyro/api/tyro/conf/#tyro.conf.DisallowNone

flag_create_pairs_off: bool = False

Disable creation of matching flag pairs for boolean types.

$ ./program.py --help
# flag_create_pairs_off = False
usage: program.py [-h] [-v] [--foo | --no-foo]
# flag_create_pairs_off = True
usage: program.py [-h] [-v] [--foo]
Code 
@dataclass
class Env:
    foo: bool = False
run(Env, settings=CliSettings(flag_create_pairs_off=True/False))

See: https://brentyi.github.io/tyro/api/tyro/conf/#tyro.conf.FlagCreatePairsOff