Annotations

Interfacy uses type annotations to convert command-line strings into Python values.

def report(path: str, limit: int = 10, ratio: float = 0.5) -> None:
    ...

$ python app.py data.csv --limit 20 --ratio 0.8

The callable receives path as str, limit as int, and ratio as float.

Common shapes

Annotation	CLI behavior
str	string value
int / float	numeric conversion
bool	flag behavior
Path	path-like value
list[T]	repeated values converted as T
tuple[A, B]	fixed number of values converted per element
Literal[...]	choice validation
Enum	choice validation
T | None	optional value
dataclass / Pydantic / plain class	structured model flags

Out of the box, Interfacy also parses a few standard-library types: datetime.date, datetime.datetime, datetime.time, datetime.timedelta, decimal.Decimal, fractions.Fraction, dict, range, and slice.

Missing annotations

An untyped parameter is accepted. CLI input for it is passed through as str, so Interfacy cannot do type-specific conversion or help formatting for it.

def echo(value):
    return value

Annotations make parsing predictable and help output more specific.

Optional values

T | None marks a value as optional.

def find(name: str | None = None) -> str | None:
    return name

$ python app.py
$ python app.py --name Ada

Optional list values work too:

def tags(items: list[str] | None = None) -> list[str] | None:
    return items