Skip to content

Prepared annotations

CLI flags have no effect in the UI. Great for CLI so that the user writes less.

mininterface.tag.flag.Blank = Annotated[T | None, None]

This marker specifies:

  1. The default value can also be None (for the case the flag is omitted).
  2. A different behavior when the flag is provided without a value.

If the flag is left blank, it evaluates to True (or to the value specified by a Literal). If the flag is omitted entirely from the CLI, it returns the default value.

from dataclasses import dataclass
from mininterface import run
from mininterface.tag.flag import Blank

@dataclass
class Env:
    test: Blank[int] = None

print(run(Env).env.test)

Let's try:

$ program.py --help
usage: program.py [-h] [-v] [--test BLANK|int]

╭─ options ───────────────────────────────────────────────────────────────────────╮
│ -h, --help              show this help message and exit                         │
│ -v, --verbose           verbosity level, can be used multiple times to increase │
│ --test BLANK|int        (default: 'None / or if left blank: True')              │
╰─────────────────────────────────────────────────────────────────────────────────╯

$ program.py           # None
$ program.py  --test   # True
$ program.py  --test 5 # 5

The default blank value might be specified by a Literal in the Annotated statement.

@dataclass
class Env
    test: Annotated[Blank[int], Literal[2]] = None

print(run(Env).env.test)

Let's try:

$ program.py           # None
$ program.py  --test   # 2
$ program.py  --test 5 # 5

You can use multiple types together:

@dataclass
class Env:
    test: Blank[int|bool] = 0

print(run(Env).env.test)

Note that you can not use 'True' or 'False' for values, as the parameter becomes a bool.

Let's try:

$ program.py               # 0
$ program.py  --test       # True
$ program.py  --test False # False

Warning

Experimental.

Discussion

The design is working but syntax Annotated[str, Blank(True)] might be a cleaner design. Do you have an opinion? Let us know.

mininterface.tag.flag.BlankTrue = Annotated[list[str] | bool | None, PrimitiveConstructorSpec(nargs='*', metavar='blank=True|BOOL', instance_from_str=_assure_blank_or_bool, is_instance=lambda instance: True, str_from_instance=lambda instance: [instance])]

When left blank, this flag produces True.

Returns:

Name Type Description
bool

for 0/false/off/1/true/on in the parameter
True

When parameter is left blank.

Raises:

Type Description
ValueError

Raised on an unknown parameter.

Warning

Experimental.

mininterface.tag.flag.Dir = Annotated[Path, PathTag(is_dir=True)]

An existing directory. from mininterface import run from mininterface.tag.flag import Dir

@dataclass
class Env:
    my_dir: Dir

m = run(Env)
m.env.my_dir  # guaranteed to be an existing dir

Warning

EXPERIMENTAL.

mininterface.tag.flag.File = Annotated[Path, PathTag(is_file=True)]

An existing file. from mininterface import run from mininterface.tag.flag import File

@dataclass
class Env:
    my_file: File

m = run(Env)
m.env.my_file  # guaranteed to be an existing dir

Warning

EXPERIMENTAL.