Overview
Via the run function you get access to the CLI, possibly enriched from the config file. Then, you receive all data as m.env object and dialog methods in a proper UI.
graph LR
subgraph mininterface
run --> GUI
run --> TUI
run --> env
CLI --> run
id1[config file] --> CLI
end
program --> run
Basic usage
Use a common dataclass, a Pydantic BaseModel or an attrs model to store the configuration. Wrap it to the run function that returns an interface m. Access the configuration via m.env or use it to prompt the user m.is_yes("Is that alright?").
There are a lot of supported types you can use, not only scalars and well-known objects (Path, datetime), but also functions, iterables (like list[Path]) and union types (like int | None). To do even more advanced things, stick the value to a powerful Tag or its subclasses. Ex. for a validation only, use its Validation alias.
At last, use Facet to tackle the interface from the back-end (m) or the front-end (Tag) side.
IDE suggestions
The immediate benefit is the type suggestions you see in an IDE. Imagine following code:
from dataclasses import dataclass
from mininterface import run
@dataclass
class Env:
my_paths: list[Path]
""" The user is forced to input Paths. """
@dataclass
class Dialog:
my_number: int = 2
""" A number """
Now, accessing the main env will trigger the hint.
Calling the form with an empty parameter will trigger editing the main env
Putting there a dict will return the dict too.
Putting there a dataclass type causes it to be resolved.
Should you have a resolved dataclass instance, put it there.
As you see, its attributes are hinted alongside their description.
Should the dataclass cannot be easily investigated by the IDE (i.e. a required field), just annotate the output.
Bash completion
Run your program with a hidden --integrate-to-system flag and a tutorial will install bash completion.
Nested configuration
You can easily nest the configuration. (See also Tyro Hierarchical Configs).
Just put another dataclass inside the config file:
@dataclass
class FurtherConfig:
token: str
host: str = "example.org"
@dataclass
class Env:
further: FurtherConfig
...
m = run(Env)
print(m.env.further.host) # example.org
The attributes can by defaulted by CLI:
And in a YAML config file. Note that you are not obliged to define all the attributes, a subset will do.
(Ex. you do not need to specify token too.)