Tag

Wrapper around a value that encapsulates a description, validation etc. When you provide a value to an interface, you may instead use this object.

Bridge between the input values and a UI widget. The widget is created with the help of this object, then transforms the value back (str to int conversion etc).

val: TagValue = None

The value wrapped by Tag. It can be any value.

from mininterface import run, Tag

tag = Tag(True, "This is my boolean", bool)
m = run()
m.form({"My boolean": tag})
print(tag.val)  # True/False
print()

The encapsulated value is True, tag.description is 'This is my boolean', tag.annotation is bool and 'My boolean' is used as tag.name.

Tip

If the Tag is nested, the info is fetched to the outer Tag. When updated, the inner Tag value updates accordingly.

tag = Tag(Tag(True))

description: str = ''

The description displayed in the UI.

annotation: type | None = None

Used for validation (ex. to convert an empty string to None). If not set, will be determined automatically from the val type.

name: str | None = None

Name displayed in the UI.

validation: Callable[[Tag], ValidationResult | tuple[ValidationResult, TagValue]] | None = None

When the user submits the form, the values are validated (and possibly transformed) with a callback function. If the validation fails, user is prompted to edit the value. Return True if validation succeeded or False or an error message when it failed.

ValidationResult is a bool or the error message (that implicitly means it has failed).

def check(tag: Tag):
    if tag.val < 10:
        return "The value must be at least 10"
m.form({"number", Tag(12, validation=check)})

Either use a custom callback function or mininterface.validators.

from mininterface.validators import not_empty
m.form({"number", Tag("", validation=not_empty)})
# User cannot leave the field empty.

You may use the validation in a type annotation.

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"

NOTE Undocumented feature, we can return tuple [ValidationResult, FieldValue] to set the self.val.

choices: ChoicesType | None = None

Print the radio buttons / select box. Constraint the value.

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

@dataclass
class Env:
    foo: Annotated["str", Choices("one", "two")] = "one"
    # `Choices` is an alias for `Tag(choices=)`

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

Info

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

on_change: Callable[[Tag], Any] | None = None

Accepts a callback that launches whenever the value changes (if the validation succeeds). The callback runs while the dialog is still running. The return value of the callback is currently not used.

In the following example, we alter the heading title according to the chosen value.

from mininterface import run, Tag

def callback(tag: Tag):
    tag.facet.set_title(f"Value changed to {tag.val}")

m = run()
m.facet.set_title("Click the checkbox")
m.form({
    "My choice": Tag(choices=["one", "two"], on_change=callback)
})

facet: Optional[Facet] = None

Access to the UI facet from the front-end side. (Read Mininterface.facet to access from the back-end side.)

Set the UI facet from within a callback, ex. a validator.

from mininterface import run, Tag

def my_check(tag: Tag):
    tag.facet.set_title("My form title")
    return "Validation failed"

with run(title='My window title') as m:
    m.form({"My form": Tag(1, validation=my_check)})

This happens when you click ok.

original_val = None

Meant to be read only in callbacks. The original value, preceding UI change. Handy while validating.

def check(tag.val):
    if tag.val != tag.original_val:
        return "You have to change the value."
m.form({"number", Tag(8, validation=check)})

set_val

Sets the value without any checks.

update

UI value → Tag value → original value. (With type conversion and checks.)

Parameters:

Name	Type	Description	Default
ui_value	TagValue	The value as it has been updated in a UI. Update accordingly the value in the original linked dict/object the mininterface was invoked with. Validates the type and do the transformation. (Ex: Some values might be nulled from "".)	required

Returns:

Type	Description
bool	bool, whether the value is alright or whether the revision is needed.

Choices(*choices)

An alias, see Tag.choices