Skip to content

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.

You can ask questions about Typer. Try:
How can I terminate a program?
How to launch applications?
How to add help to CLI argument?