Types

These useful types can be imported from mininterface.types. They are all subclasses of the Tag, the main object for storing values. Normally, you don't need to use or know much about those but they can be helpful when you need to further specify the functionality, such as restricting a Path to directories only.

mininterface.types.rich_tags

CallbackTag

Callback function is guaranteed to receives the Tag as a parameter.

Warning

Experimental. May change.

For the following examples, we will use these custom callback functions:

from mininterface import run

def callback_raw():
    """ Dummy function """
    print("Priting text")
    return 50

def callback_tag(tag: Tag):
    """ Receives a tag """
    print("Printing", type(tag))
    return 100

m = run()

Use as buttons in a form:

m.form({"Button": callback_raw})
m.form({"Button": CallbackTag(callback_tag)})

Via form, we receive the function handler:

out = m.form({
    "My choice": Tag(choices=[callback_raw, CallbackTag(callback_tag)])
})
print(out)  # {'My choice': <function callback_raw at 0x7ae5b3e74ea0>}

Via choice, we receive the function output:

out = m.choice({
    "My choice1": callback_raw,
    "My choice2": CallbackTag(callback_tag),
    # Not supported: "My choice3": Tag(callback_tag, annotation=CallbackTag),
})
print(out)  # output of callback0 or callback_tag, ex:
#    Printing <class 'mininterface.types.CallbackTag'>
#    100

You may use callback in a dataclass.

@dataclass
class Callbacks:
    p1: Callable = callback0
    p2: Annotated[Callable, CallbackTag(description="Foo")] = callback_tag
    # Not supported: p3: CallbackTag = callback_tag
    # Not supported: p4: CallbackTag = field(default_factory=CallbackTag(callback_tag))
    # Not supported: p5: Annotated[Callable, Tag(description="Bar", annotation=CallbackTag)] = callback_tag

m = run(Callbacks)
m.form()

PathTag

Contains a Path or their list. Use this helper object to select files.

In the following example, we see that it is not always needed to use this object.

• File 1 – plain detection, button to a file picker appeared.
• File 2 – the same.
• File 3 – we specified multiple paths can be selected.

from pathlib import Path
from mininterface import run, Tag
from mininterface.types import PathTag

m = run()
out = m.form({
    "File 1": Path("/tmp"),
    "File 2": Tag("", annotation=Path),
    "File 3": PathTag([Path("/tmp")], multiple=True),
})
print(out)
# {'File 1': PosixPath('/tmp'), 'File 2': PosixPath('.')}
# {'File 3': [PosixPath('/tmp')]}

multiple: Optional[bool] = None

The user can select multiple files.

exist: Optional[bool] = None

If True, validates that the selected file exists

is_dir: Optional[bool] = None

If True, validates that the selected path is a directory

is_file: Optional[bool] = None

If True, validates that the selected path is a file

DatetimeTag

Datetime, date and time types are supported.

from datetime import datetime
from dataclasses import dataclass
from mininterface import run

@dataclass
class Env:
    my_date: datetime

m = run(Env)

The arrows change the day (or the datetime part the keyboard caret is currently editing).

In this code, we want only the date part.

from datetime import date
from dataclasses import dataclass
from mininterface import run

@dataclass
class Env:
    my_date: date

m = run(Env)

After clicking the button (or hitting Ctrl+Shift+C), a calendar appear.

date: bool = False

The date part is active. True for datetime and date.

time: bool = False

The time part is active. True for datetime and time.

full_precision: bool = False

Include full time precison, seconds, microseconds.

SecretTag

Contains a secret value that should be masked in the UI.

from mininterface import run, Tag
from mininterface.types import SecretTag

m = run()
out = m.form({
    "My password": SecretTag("TOKEN"),
})
print(out)
# {'My password': 'TOKEN'}

show_toggle: bool = True

Toggle visibility button (eye icon)

toggle_visibility()

Toggle the masked state

__repr__()

Ensure secrets are not accidentally exposed in logs/repr

__hash__()

Make SecretTag hashable for use with Annotated

EnumTag

Handle choices – radio buttons / select box. The value serves as the initially selected choice. It is constrained to those defined in the choices attribute.

choices: ChoicesType | None = None

The possible values.

m.form({"My restrained": EnumTag(choices=("one", "two"))})

You can denote the choices in many ways. Either put options in an iterable, or to a dict with keys as a values. You can also you tuples for keys to get a table-like formatting. Use the Enums or nested Tags... See the ChoicesType for more details.

Here we focus at the EnumTag itself and its Choices alias. It can be used to annotate a default value in a dataclass.

from dataclasses import dataclass
from typing import Annotated
from mininterface import run, Choices
from mininterface.types import EnumTag

@dataclass
class Env:
    foo: Annotated["str", Choices("one", "two")] = "one"
    # `Choices` is an alias for `EnumTag(choices=)`
    #   so the same would be:
    # foo: Annotated["str", EnumTag(choices=("one", "two"))] = "one"

m = run(Env)
m.form()  # prompts a dialog

Tip

When dealing with a simple use case, use the mininterface.choice dialog.

update(ui_value)

UI value is the label. We store the key.

mininterface.types.alias

Validation(check)

Alias to Tag(validation=...)

from mininterface import Tag, Validation
@dataclass
class Env:
    my_text: Annotated[str, Validation(not_empty) = "will not be emtpy"

    # which is an alias for:
    # my_text: Annotated[str, Tag(validation=not_empty)] = "will not be emtpy"

Parameters:

Name	Type	Description	Default
check	Callable[[Tag], ValidationResult | tuple[ValidationResult, TagValue]]	Callback function.	required

Choices(*choices)

An alias, see EnumTag.choices