Enum - Choices
To define a CLI parameter that can take a value from a predefined set of values you can use a standard Python enum.Enum:
from enum import Enum
import typer_cloup as typer
class NeuralNetwork(str, Enum):
simple = "simple"
conv = "conv"
lstm = "lstm"
def main(network: NeuralNetwork = NeuralNetwork.simple):
typer.echo(f"Training neural network of type: {network.value}")
if __name__ == "__main__":
typer.run(main)
Tip
Notice that the function parameter network will be an Enum, not a str.
To get the str value in your function's code use network.value.
Check it:
$ python main.py --help
// Notice the predefined values [simple|conv|lstm]
Usage: main.py [OPTIONS]
Options:
--network [simple|conv|lstm] [default: simple]
--help Show this message and exit.
// Try it
$ python main.py --network conv
Training neural network of type: conv
// Invalid value
$ python main.py --network capsule
Usage: main.py [OPTIONS]
Try "main.py --help" for help.
Error: Invalid value for '--network': invalid choice: capsule. (choose from simple, conv, lstm)
Case insensitive Enum choices¶
You can make an Enum (choice) CLI parameter be case-insensitive with the case_sensitive parameter:
from enum import Enum
import typer_cloup as typer
class NeuralNetwork(str, Enum):
simple = "simple"
conv = "conv"
lstm = "lstm"
def main(
network: NeuralNetwork = typer.Option(NeuralNetwork.simple, case_sensitive=False)
):
typer.echo(f"Training neural network of type: {network.value}")
if __name__ == "__main__":
typer.run(main)
And then the values of the Enum will be checked no matter if lower case, upper case, or a mix:
// Notice the upper case CONV
$ python main.py --network CONV
Training neural network of type: conv
// A mix also works
$ python main.py --network LsTm
Training neural network of type: lstm
Literal choices¶
You can also use typing.Literal to declare a set of choices directly:
from typing import Annotated, Literal
import typer_cloup as typer
def main(
network: Annotated[Literal["simple", "conv", "lstm"], typer.Option()] = "simple",
):
typer.echo(f"Training neural network of type: {network}")
if __name__ == "__main__":
typer.run(main)
The value passed to the function is the matching literal value. String choices
produce strings, while integer choices such as Literal[1, 2] produce integers.
$ python main.py --help
Usage: main.py [OPTIONS]
Options:
--network [simple|conv|lstm] [default: simple]
--help Show this message and exit.
$ python main.py --network conv
Training neural network of type: conv
$ python main.py --network capsule
Usage: main.py [OPTIONS]
Try 'main.py --help' for help.
Error: Invalid value for '--network': 'capsule' is not one of 'simple', 'conv', 'lstm'.
Literal works with both CLI arguments and options, with or without
Annotated. For example, the older declaration style is also supported:
def main(network: Literal["simple", "conv", "lstm"] = typer.Option("simple")):
typer.echo(f"Training neural network of type: {network}")
Use case_sensitive=False in typer.Option() or typer.Argument() to accept
different casing. The function still receives the spelling declared in
Literal. Use an annotation such as Literal["simple", "conv"] | None with a
default of None for an optional value.
Note
Literal inside list or tuple annotations, such as
list[Literal["simple", "conv"]], is currently unsupported. This also applies
to lists declared with shell_quoted_list=True.