✨ Add option to use Enum names instead of values on the commandline

docs/tutorial/parameter-types/enum.md

@@ -153,3 +153,38 @@ Buying groceries: Eggs, Bacon
 ```
 
 </div>
+
+
+### Using Enum names instead of values
+
+Some times you want to accept `Enum` names from the command line and convert
+that into `Enum` values in the command handler. You can enable this by setting
+`enum_by_name=True`:
+
+```Python hl_lines="14"
+{!../docs_src/parameter_types/enum/tutorial004.py!}
+```
+
+And then the names of the `Enum` will be used instead of values:
+
+<div class="termy">
+
+```console
+$ python main.py --log-level debug
+
+Log level set to DEBUG
+```
+
+</div>
+
+This can be particularly useful if the enum values are not strings:
+
+```Python hl_lines="7-10, 13"
+{!../docs_src/parameter_types/enum/tutorial005.py!}
+```
+
+```console
+$ python main.py --access protected
+
+Access level: protected (2)
+```

docs_src/multiple_values/options_with_multiple_values/tutorial002.py

@@ -0,0 +1,25 @@
+from enum import Enum
+from typing import Tuple
+
+import typer
+
+
+class Food(str, Enum):
+    f1 = "Eggs"
+    f2 = "Bacon"
+    f3 = "Cheese"
+
+
+def main(user: Tuple[str, int, bool, Food] = typer.Option((None, None, None, Food.f1))):
+    username, coins, is_wizard, food = user
+    if not username:
+        print("No user provided")
+        raise typer.Abort()
+    print(f"The username {username} has {coins} coins")
+    if is_wizard:
+        print("And this user is a wizard!")
+    print(f"And they love eating {food.value}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/multiple_values/options_with_multiple_values/tutorial002_an.py

@@ -0,0 +1,33 @@
+from enum import Enum
+from typing import Tuple
+
+import typer
+from typing_extensions import Annotated
+
+
+class Food(str, Enum):
+    f1 = "Eggs"
+    f2 = "Bacon"
+    f3 = "Cheese"
+
+
+def main(
+    user: Annotated[Tuple[str, int, bool, Food], typer.Option()] = (
+        None,
+        None,
+        None,
+        Food.f1,
+    ),
+):
+    username, coins, is_wizard, food = user
+    if not username:
+        print("No user provided")
+        raise typer.Abort()
+    print(f"The username {username} has {coins} coins")
+    if is_wizard:
+        print("And this user is a wizard!")
+    print(f"And they love eating {food.value}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/multiple_values/options_with_multiple_values/tutorial003.py

@@ -0,0 +1,29 @@
+from enum import Enum
+from typing import Tuple
+
+import typer
+
+
+class Food(str, Enum):
+    f1 = "Eggs"
+    f2 = "Bacon"
+    f3 = "Cheese"
+
+
+def main(
+    user: Tuple[str, int, bool, Food] = typer.Option(
+        (None, None, None, "f1"), enum_by_name=True
+    ),
+):
+    username, coins, is_wizard, food = user
+    if not username:
+        print("No user provided")
+        raise typer.Abort()
+    print(f"The username {username} has {coins} coins")
+    if is_wizard:
+        print("And this user is a wizard!")
+    print(f"And they love eating {food.value}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/multiple_values/options_with_multiple_values/tutorial003_an.py

@@ -0,0 +1,33 @@
+from enum import Enum
+from typing import Tuple
+
+import typer
+from typing_extensions import Annotated
+
+
+class Food(str, Enum):
+    f1 = "Eggs"
+    f2 = "Bacon"
+    f3 = "Cheese"
+
+
+def main(
+    user: Annotated[Tuple[str, int, bool, Food], typer.Option(enum_by_name=True)] = (
+        None,
+        None,
+        None,
+        "f1",
+    ),
+):
+    username, coins, is_wizard, food = user
+    if not username:
+        print("No user provided")
+        raise typer.Abort()
+    print(f"The username {username} has {coins} coins")
+    if is_wizard:
+        print("And this user is a wizard!")
+    print(f"And they love eating {food.value}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/parameter_types/enum/tutorial004.py

@@ -0,0 +1,18 @@
+import enum
+import logging
+
+import typer
+
+
+class LogLevel(enum.Enum):
+    debug = logging.DEBUG
+    info = logging.INFO
+    warning = logging.WARNING
+
+
+def main(log_level: LogLevel = typer.Option("warning", enum_by_name=True)):
+    typer.echo(f"Log level set to: {logging.getLevelName(log_level.value)}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/parameter_types/enum/tutorial004_an.py

@@ -0,0 +1,19 @@
+import enum
+import logging
+
+import typer
+from typing_extensions import Annotated
+
+
+class LogLevel(enum.Enum):
+    debug = logging.DEBUG
+    info = logging.INFO
+    warning = logging.WARNING
+
+
+def main(log_level: Annotated[LogLevel, typer.Option(enum_by_name=True)] = "warning"):
+    typer.echo(f"Log level set to: {logging.getLevelName(log_level.value)}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/parameter_types/enum/tutorial005.py

@@ -0,0 +1,18 @@
+import enum
+
+import typer
+
+
+class Access(enum.IntEnum):
+    private = 1
+    protected = 2
+    public = 3
+    open = 4
+
+
+def main(access: Access = typer.Option("private", enum_by_name=True)):
+    typer.echo(f"Access level: {access.name} ({access.value})")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/parameter_types/enum/tutorial005_an.py

@@ -0,0 +1,19 @@
+import enum
+
+import typer
+from typing_extensions import Annotated
+
+
+class Access(enum.IntEnum):
+    private = 1
+    protected = 2
+    public = 3
+    open = 4
+
+
+def main(access: Annotated[Access, typer.Option(enum_by_name=True)] = "private"):
+    typer.echo(f"Access level: {access.name} ({access.value})")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/parameter_types/enum/tutorial006.py

@@ -0,0 +1,18 @@
+from enum import Enum
+from typing import List
+
+import typer
+
+
+class Food(str, Enum):
+    f1 = "Eggs"
+    f2 = "Bacon"
+    f3 = "Cheese"
+
+
+def main(groceries: List[Food] = typer.Option(["f1", "f3"], enum_by_name=True)):
+    print(f"Buying groceries: {', '.join([f.value for f in groceries])}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

docs_src/parameter_types/enum/tutorial006_an.py

@@ -0,0 +1,21 @@
+from enum import Enum
+from typing import List
+
+import typer
+from typing_extensions import Annotated
+
+
+class Food(str, Enum):
+    f1 = "Eggs"
+    f2 = "Bacon"
+    f3 = "Cheese"
+
+
+def main(
+    groceries: Annotated[List[Food], typer.Option(enum_by_name=True)] = ["f1", "f3"],
+):
+    print(f"Buying groceries: {', '.join([f.value for f in groceries])}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

tests/test_tutorial/test_multiple_values/test_options_with_multiple_values/test_tutorial002.py

@@ -0,0 +1,49 @@
+import subprocess
+import sys
+
+import typer
+from typer.testing import CliRunner
+
+from docs_src.multiple_values.options_with_multiple_values import tutorial002 as mod
+
+runner = CliRunner()
+app = typer.Typer()
+app.command()(mod.main)
+
+
+def test_main():
+    result = runner.invoke(app)
+    assert result.exit_code != 0
+    assert "No user provided" in result.output
+    assert "Aborted" in result.output
+
+
+def test_user_1():
+    result = runner.invoke(app, ["--user", "Camila", "50", "yes", "Eggs"])
+    assert result.exit_code == 0
+    assert "The username Camila has 50 coins" in result.output
+    assert "And this user is a wizard!" in result.output
+    assert "And they love eating Eggs" in result.output
+
+
+def test_user_2():
+    result = runner.invoke(app, ["--user", "Morty", "3", "no", "Bacon"])
+    assert result.exit_code == 0
+    assert "The username Morty has 3 coins" in result.output
+    assert "And this user is a wizard!" not in result.output
+    assert "And they love eating Bacon" in result.output
+
+
+def test_invalid_user():
+    result = runner.invoke(app, ["--user", "Camila", "50"])
+    assert result.exit_code != 0
+    assert "Option '--user' requires 4 arguments" 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_multiple_values/test_options_with_multiple_values/test_tutorial002_an.py

@@ -0,0 +1,49 @@
+import subprocess
+import sys
+
+import typer
+from typer.testing import CliRunner
+
+from docs_src.multiple_values.options_with_multiple_values import tutorial002_an as mod
+
+runner = CliRunner()
+app = typer.Typer()
+app.command()(mod.main)
+
+
+def test_main():
+    result = runner.invoke(app)
+    assert result.exit_code != 0
+    assert "No user provided" in result.output
+    assert "Aborted" in result.output
+
+
+def test_user_1():
+    result = runner.invoke(app, ["--user", "Camila", "50", "yes", "Eggs"])
+    assert result.exit_code == 0
+    assert "The username Camila has 50 coins" in result.output
+    assert "And this user is a wizard!" in result.output
+    assert "And they love eating Eggs" in result.output
+
+
+def test_user_2():
+    result = runner.invoke(app, ["--user", "Morty", "3", "no", "Bacon"])
+    assert result.exit_code == 0
+    assert "The username Morty has 3 coins" in result.output
+    assert "And this user is a wizard!" not in result.output
+    assert "And they love eating Bacon" in result.output
+
+
+def test_invalid_user():
+    result = runner.invoke(app, ["--user", "Camila", "50"])
+    assert result.exit_code != 0
+    assert "Option '--user' requires 4 arguments" 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