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

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

The user can select multiple files.

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.

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