Types

Various types are supported:

• scalars
• functions
• well-known objects (Path, datetime)
• iterables (like list[Path])
• custom classes (somewhat)
• union types (like int | None)

Take a look how it works with the variables organized in a dataclass:

from dataclasses import dataclass
from pathlib import Path

from mininterface import run


@dataclass
class Env:
    my_number: int = 1
    """ A dummy number """
    my_boolean: bool = True
    """ A dummy boolean """
    my_conditional_number: int | None = None
    """ A number that can be null if left empty """
    my_path: Path = Path("/tmp")
    """ A dummy path """


m = run(Env)  # m.env contains an Env instance
m.form()  # Prompt a dialog; m.form() without parameter edits m.env
print(m.env)
# Env(my_number=1, my_boolean=True, my_path=PosixPath('/tmp'),
#  my_point=<__main__.Point object at 0x7ecb5427fdd0>)

Variables organized in a dict:

Along scalar types, there is (basic) support for common iterables or custom classes.

from mininterface import run

class Point:
    def __init__(self, i: int):
        self.i = i

    def __str__(self):
        return str(self.i)


values = {"my_number": 1,
          "my_list": [1, 2, 3],
          "my_point": Point(10)
          }

m = run()
m.form(values)  # Prompt a dialog
print(values)  # {'my_number': 2, 'my_list': [2, 3], 'my_point': <__main__.Point object...>}
print(values["my_point"].i)  # 100

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

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.aliases 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: str = False

The user can select multiple files.

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 Tag.choices