✨ Support typing.Literal to define a set of predefined choices (#429)

Co-authored-by: Dan Walters <dan@walters.io>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Sebastián Ramírez <tiangolo@gmail.com>
Co-authored-by: svlandeg <svlandeg@github.com>
Co-authored-by: Sofie Van Landeghem <svlandeg@users.noreply.github.com>
Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com>

Author: 6 people

docs/tutorial/parameter-types/enum.md

@@ -111,3 +111,37 @@ Buying groceries: Eggs, Bacon
 ```
 
 </div>
+
+### Literal choices
+
+You can also use `Literal` to represent a set of possible predefined choices, without having to use an `Enum`:
+
+{* docs_src/parameter_types/enum/tutorial004_an.py hl[6] *}
+
+<div class="termy">
+
+```console
+$ 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': 'capsule' is not one of 'simple', 'conv', 'lstm'.
+```
+
+</div>

docs_src/parameter_types/enum/tutorial004.py

@@ -0,0 +1,10 @@
+import typer
+from typing_extensions import Literal
+
+
+def main(network: Literal["simple", "conv", "lstm"] = typer.Option("simple")):
+    print(f"Training neural network of type: {network}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/parameter_types/enum/tutorial004_an.py

@@ -0,0 +1,12 @@
+import typer
+from typing_extensions import Annotated, Literal
+
+
+def main(
+    network: Annotated[Literal["simple", "conv", "lstm"], typer.Option()] = "simple",
+):
+    print(f"Training neural network of type: {network}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

tests/test_tutorial/test_parameter_types/test_enum/test_tutorial004.py

@@ -0,0 +1,46 @@
+import subprocess
+import sys
+
+import typer
+from typer.testing import CliRunner
+
+from docs_src.parameter_types.enum import tutorial004 as mod
+
+runner = CliRunner()
+
+app = typer.Typer()
+app.command()(mod.main)
+
+
+def test_help():
+    result = runner.invoke(app, ["--help"])
+    assert result.exit_code == 0
+    assert "--network [simple|conv|lstm]" in result.output.replace("  ", "")
+
+
+def test_main():
+    result = runner.invoke(app, ["--network", "conv"])
+    assert result.exit_code == 0
+    assert "Training neural network of type: conv" in result.output
+
+
+def test_invalid():
+    result = runner.invoke(app, ["--network", "capsule"])
+    assert result.exit_code != 0
+    assert "Invalid value for '--network'" in result.output
+    assert (
+        "invalid choice: capsule. (choose from" in result.output
+        or "'capsule' is not one of" in result.output
+    )
+    assert "simple" in result.output
+    assert "conv" in result.output
+    assert "lstm" in result.output
+
+
+def test_script():
+    result = subprocess.run(
+        [sys.executable, "-m", "coverage", "run", mod.__file__, "--help"],
+        capture_output=True,
+        encoding="utf-8",
+    )
+    assert "Usage" in result.stdout

tests/test_tutorial/test_parameter_types/test_enum/test_tutorial004_an.py

@@ -0,0 +1,46 @@
+import subprocess
+import sys
+
+import typer
+from typer.testing import CliRunner
+
+from docs_src.parameter_types.enum import tutorial004_an as mod
+
+runner = CliRunner()
+
+app = typer.Typer()
+app.command()(mod.main)
+
+
+def test_help():
+    result = runner.invoke(app, ["--help"])
+    assert result.exit_code == 0
+    assert "--network [simple|conv|lstm]" in result.output.replace("  ", "")
+
+
+def test_main():
+    result = runner.invoke(app, ["--network", "conv"])
+    assert result.exit_code == 0
+    assert "Training neural network of type: conv" in result.output
+
+
+def test_invalid():
+    result = runner.invoke(app, ["--network", "capsule"])
+    assert result.exit_code != 0
+    assert "Invalid value for '--network'" in result.output
+    assert (
+        "invalid choice: capsule. (choose from" in result.output
+        or "'capsule' is not one of" in result.output
+    )
+    assert "simple" in result.output
+    assert "conv" in result.output
+    assert "lstm" in result.output
+
+
+def test_script():
+    result = subprocess.run(
+        [sys.executable, "-m", "coverage", "run", mod.__file__, "--help"],
+        capture_output=True,
+        encoding="utf-8",
+    )
+    assert "Usage" in result.stdout

typer/_typing.py

@@ -93,7 +93,9 @@ def is_callable_type(type_: Type[Any]) -> bool:
 
 
 def is_literal_type(type_: Type[Any]) -> bool:
-    return Literal is not None and get_origin(type_) is Literal
+    import typing_extensions
+
+    return get_origin(type_) in (Literal, typing_extensions.Literal)
 
 
 def literal_values(type_: Type[Any]) -> Tuple[Any, ...]:

typer/main.py

@@ -17,7 +17,7 @@
 import click
 from typer._types import TyperChoice
 
-from ._typing import get_args, get_origin, is_union
+from ._typing import get_args, get_origin, is_literal_type, is_union, literal_values
 from .completion import get_completion_inspect_parameters
 from .core import (
     DEFAULT_MARKUP_MODE,
@@ -783,6 +783,11 @@ def get_click_type(
             [item.value for item in annotation],
             case_sensitive=parameter_info.case_sensitive,
         )
+    elif is_literal_type(annotation):
+        return click.Choice(
+            literal_values(annotation),
+            case_sensitive=parameter_info.case_sensitive,
+        )
     raise RuntimeError(f"Type not yet supported: {annotation}")  # pragma: no cover