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

docs/tutorial/parameter-types/enum.md

@@ -74,6 +74,37 @@ Training neural network of type: lstm
 
 </div>
 
+### Using Enum names instead of values
+
+Sometimes 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`:
+
+{* docs_src/parameter_types/enum/tutorial007_an_py310.py hl[18] *}
+
+And then the names of the `Enum` can 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:
+
+{* docs_src/parameter_types/enum/tutorial005_an_py310.py hl[8:11,18] *}
+
+```console
+$ python main.py --access protected
+
+Access level: protected (2)
+```
+
+
 ### List of Enum values
 
 A *CLI parameter* can also take a list of `Enum` values:
@@ -112,6 +143,29 @@ Buying groceries: Eggs, Bacon
 
 </div>
 
+You can also combine `enum_by_name=True` with a list of enums:
+
+{* docs_src/parameter_types/enum/tutorial006_an_py310.py hl[18] *}
+
+This works exactly the same, but you're using the enum names instead of values:
+
+<div class="termy">
+
+```console
+// Try it with a single value
+$ python main.py --groceries "f1"
+
+Buying groceries: Eggs
+
+// Try it with multiple values
+$ python main.py --groceries "f1" --groceries "f2"
+
+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/tutorial005_an_py310.py

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

docs_src/parameter_types/enum/tutorial005_py310.py

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

docs_src/parameter_types/enum/tutorial006_an_py310.py

@@ -0,0 +1,24 @@
+from enum import Enum
+from typing import Annotated
+
+import typer
+
+
+class Food(str, Enum):
+    f1 = "Eggs"
+    f2 = "Bacon"
+    f3 = "Cheese"
+
+
+app = typer.Typer()
+
+
+@app.command()
+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__":
+    app()

docs_src/parameter_types/enum/tutorial006_py310.py

@@ -0,0 +1,21 @@
+from enum import Enum
+
+import typer
+
+
+class Food(str, Enum):
+    f1 = "Eggs"
+    f2 = "Bacon"
+    f3 = "Cheese"
+
+
+app = typer.Typer()
+
+
+@app.command()
+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__":
+    app()

docs_src/parameter_types/enum/tutorial007_an_py310.py

@@ -0,0 +1,23 @@
+import enum
+import logging
+from typing import Annotated
+
+import typer
+
+
+class LogLevel(enum.Enum):
+    debug = logging.DEBUG
+    info = logging.INFO
+    warning = logging.WARNING
+
+
+app = typer.Typer()
+
+
+@app.command()
+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__":
+    app()

docs_src/parameter_types/enum/tutorial007_py310.py

@@ -0,0 +1,22 @@
+import enum
+import logging
+
+import typer
+
+
+class LogLevel(enum.Enum):
+    debug = logging.DEBUG
+    info = logging.INFO
+    warning = logging.WARNING
+
+
+app = typer.Typer()
+
+
+@app.command()
+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__":
+    app()

pyproject.toml

@@ -232,6 +232,7 @@ ignore = [
 "docs_src/options_autocompletion/tutorial008_an_py310.py" = ["B006"]
 "docs_src/options_autocompletion/tutorial009_an_py310.py" = ["B006"]
 "docs_src/parameter_types/enum/tutorial003_an_py310.py" = ["B006"]
+"docs_src/parameter_types/enum/tutorial006_an_py310.py" = ["B006"]
 # Loop control variable `value` not used within loop body
 "docs_src/progressbar/tutorial001_py310.py" = ["B007"]
 "docs_src/progressbar/tutorial003_py310.py" = ["B007"]

tests/test_tutorial/test_parameter_types/test_enum/test_tutorial005.py

@@ -0,0 +1,43 @@
+import importlib
+import subprocess
+import sys
+from types import ModuleType
+
+import pytest
+from typer.testing import CliRunner
+
+runner = CliRunner()
+
+
+@pytest.fixture(
+    name="mod",
+    params=[
+        pytest.param("tutorial005_py310"),
+        pytest.param("tutorial005_an_py310"),
+    ],
+)
+def get_mod(request: pytest.FixtureRequest) -> ModuleType:
+    module_name = f"docs_src.parameter_types.enum.{request.param}"
+    mod = importlib.import_module(module_name)
+    return mod
+
+
+def test_int_enum_default(mod: ModuleType):
+    result = runner.invoke(mod.app)
+    assert result.exit_code == 0
+    assert "Access level: private (1)" in result.output
+
+
+def test_int_enum(mod: ModuleType):
+    result = runner.invoke(mod.app, ["--access", "open"])
+    assert result.exit_code == 0
+    assert "Access level: open (4)" in result.output
+
+
+def test_script(mod: ModuleType):
+    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_tutorial006.py

@@ -0,0 +1,57 @@
+import importlib
+import subprocess
+import sys
+from types import ModuleType
+
+import pytest
+from typer.testing import CliRunner
+
+runner = CliRunner()
+
+
+@pytest.fixture(
+    name="mod",
+    params=[
+        pytest.param("tutorial006_py310"),
+        pytest.param("tutorial006_an_py310"),
+    ],
+)
+def get_mod(request: pytest.FixtureRequest) -> ModuleType:
+    module_name = f"docs_src.parameter_types.enum.{request.param}"
+    mod = importlib.import_module(module_name)
+    return mod
+
+
+def test_help(mod: ModuleType):
+    result = runner.invoke(mod.app, ["--help"])
+    assert result.exit_code == 0
+    assert "--groceries" in result.output
+    assert "[f1|f2|f3]" in result.output
+    assert "default: f1, f3" in result.output
+
+
+def test_call_no_arg(mod: ModuleType):
+    result = runner.invoke(mod.app)
+    assert result.exit_code == 0
+    assert "Buying groceries: Eggs, Cheese" in result.output
+
+
+def test_call_single_arg(mod: ModuleType):
+    result = runner.invoke(mod.app, ["--groceries", "f2"])
+    assert result.exit_code == 0
+    assert "Buying groceries: Bacon" in result.output
+
+
+def test_call_multiple_arg(mod: ModuleType):
+    result = runner.invoke(mod.app, ["--groceries", "f1", "--groceries", "f2"])
+    assert result.exit_code == 0
+    assert "Buying groceries: Eggs, Bacon" in result.output
+
+
+def test_script(mod: ModuleType):
+    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_tutorial007.py

@@ -0,0 +1,43 @@
+import importlib
+import subprocess
+import sys
+from types import ModuleType
+
+import pytest
+from typer.testing import CliRunner
+
+runner = CliRunner()
+
+
+@pytest.fixture(
+    name="mod",
+    params=[
+        pytest.param("tutorial007_py310"),
+        pytest.param("tutorial007_an_py310"),
+    ],
+)
+def get_mod(request: pytest.FixtureRequest) -> ModuleType:
+    module_name = f"docs_src.parameter_types.enum.{request.param}"
+    mod = importlib.import_module(module_name)
+    return mod
+
+
+def test_enum_names_default(mod: ModuleType):
+    result = runner.invoke(mod.app)
+    assert result.exit_code == 0
+    assert "Log level set to: WARNING" in result.output
+
+
+def test_enum_names(mod: ModuleType):
+    result = runner.invoke(mod.app, ["--log-level", "debug"])
+    assert result.exit_code == 0
+    assert "Log level set to: DEBUG" in result.output
+
+
+def test_script(mod: ModuleType):
+    result = subprocess.run(
+        [sys.executable, "-m", "coverage", "run", mod.__file__, "--help"],
+        capture_output=True,
+        encoding="utf-8",
+    )
+    assert "Usage" in result.stdout