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

docs/tutorial/parameter-types/enum.md

@@ -66,3 +66,32 @@ Training neural network of type: lstm
 ```
 
 </div>
+
+
+### Using Enum names instead of values
+
+Some times you want to accept `Enum` names from command line and convert 
+that into `Enum` values in command handler. You can enable this with 
+`names=True` parameter:
+
+```Python hl_lines="14"
+{!../docs_src/parameter_types/enum/tutorial003.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>
+
+If `IntEnum` type is given, then enum names are used implicitly.
+
+```Python hl_lines="14"
+{!../docs_src/parameter_types/enum/tutorial004.py!}
+```

docs_src/parameter_types/enum/tutorial003.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(LogLevel.warning, names=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.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(Access.private)):
+    typer.echo(f"Access level: {access.name}")
+
+
+if __name__ == "__main__":
+    typer.run(main)

tests/test_tutorial/test_parameter_types/test_enum/test_tutorial003.py

@@ -0,0 +1,27 @@
+import subprocess
+
+import typer
+from typer.testing import CliRunner
+
+from docs_src.parameter_types.enum import tutorial003 as mod
+
+runner = CliRunner()
+
+app = typer.Typer()
+app.command()(mod.main)
+
+
+def test_enum_names():
+    result = runner.invoke(app, ["--log-level", "debug"])
+    assert result.exit_code == 0
+    assert "Log level set to: DEBUG" in result.output
+
+
+def test_script():
+    result = subprocess.run(
+        ["coverage", "run", mod.__file__, "--help"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        encoding="utf-8",
+    )
+    assert "Usage" in result.stdout

tests/test_tutorial/test_parameter_types/test_enum/test_tutorial004.py

@@ -0,0 +1,27 @@
+import subprocess
+
+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_int_enum():
+    result = runner.invoke(app, ["--access", "open"])
+    assert result.exit_code == 0
+    assert "Access level: open" in result.output
+
+
+def test_script():
+    result = subprocess.run(
+        ["coverage", "run", mod.__file__, "--help"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        encoding="utf-8",
+    )
+    assert "Usage" in result.stdout

typer/main.py

@@ -463,6 +463,18 @@ def convertor(value: Any) -> Any:
     return convertor
 
 
+def generate_enum_name_convertor(enum: Type[Enum]) -> Callable[..., Any]:
+    lower_name_map = {str(item.name).lower(): item for item in enum}
+
+    def convertor(value: Any) -> Any:
+        if value is not None:
+            low = str(value).lower()
+            if low in lower_name_map:
+                return lower_name_map[low]
+
+    return convertor
+
+
 def generate_iter_convertor(convertor: Callable[[Any], Any]) -> Callable[..., Any]:
     def internal_convertor(value: Any) -> List[Any]:
         return [convertor(v) for v in value]
@@ -580,10 +592,11 @@ def get_click_type(
             atomic=parameter_info.atomic,
         )
     elif lenient_issubclass(annotation, Enum):
-        return click.Choice(
-            [item.value for item in annotation],
-            case_sensitive=parameter_info.case_sensitive,
-        )
+        if use_enum_names(parameter_info, annotation):
+            choices = [item.name for item in annotation]
+        else:
+            choices = [item.value for item in annotation]
+        return click.Choice(choices, case_sensitive=parameter_info.case_sensitive)
     raise RuntimeError(f"Type not yet supported: {annotation}")  # pragma no cover
 
 
@@ -593,6 +606,15 @@ def lenient_issubclass(
     return isinstance(cls, type) and issubclass(cls, class_or_tuple)
 
 
+def use_enum_names(parameter_info: ParameterInfo, annotation: Type[Enum]) -> bool:
+    """Check if Enum names or values should be used
+
+    If ParameterInfo.names is explicitly set to True, always use names, but also
+    try to guess if names should be used in cases, when Enum is ant IntEnum.
+    """
+    return parameter_info.names or issubclass(annotation, int)
+
+
 def get_click_param(
     param: ParamMeta,
 ) -> Tuple[Union[click.Argument, click.Option], Any]:
@@ -660,7 +682,10 @@ def get_click_param(
     if lenient_issubclass(main_type, Path):
         convertor = param_path_convertor
     if lenient_issubclass(main_type, Enum):
-        convertor = generate_enum_convertor(main_type)
+        if use_enum_names(parameter_info, main_type):
+            convertor = generate_enum_name_convertor(main_type)
+        else:
+            convertor = generate_enum_convertor(main_type)
     if convertor and is_list:
         convertor = generate_iter_convertor(convertor)
         # TODO: handle recursive conversion for tuples

typer/models.py

@@ -173,6 +173,7 @@ def __init__(
         hidden: bool = False,
         # Choice
         case_sensitive: bool = True,
+        names: bool = False,
         # Numbers
         min: Optional[Union[int, float]] = None,
         max: Optional[Union[int, float]] = None,
@@ -211,6 +212,7 @@ def __init__(
         self.hidden = hidden
         # Choice
         self.case_sensitive = case_sensitive
+        self.names = names
         # Numbers
         self.min = min
         self.max = max
@@ -262,6 +264,7 @@ def __init__(
         show_envvar: bool = True,
         # Choice
         case_sensitive: bool = True,
+        names: bool = False,
         # Numbers
         min: Optional[Union[int, float]] = None,
         max: Optional[Union[int, float]] = None,
@@ -301,6 +304,7 @@ def __init__(
             hidden=hidden,
             # Choice
             case_sensitive=case_sensitive,
+            names=names,
             # Numbers
             min=min,
             max=max,
@@ -353,6 +357,7 @@ def __init__(
         hidden: bool = False,
         # Choice
         case_sensitive: bool = True,
+        names: bool = False,
         # Numbers
         min: Optional[Union[int, float]] = None,
         max: Optional[Union[int, float]] = None,
@@ -392,6 +397,7 @@ def __init__(
             hidden=hidden,
             # Choice
             case_sensitive=case_sensitive,
+            names=names,
             # Numbers
             min=min,
             max=max,

typer/params.py

@@ -28,6 +28,7 @@ def Option(
     show_envvar: bool = True,
     # Choice
     case_sensitive: bool = True,
+    names: bool = False,
     # Numbers
     min: Optional[Union[int, float]] = None,
     max: Optional[Union[int, float]] = None,
@@ -75,6 +76,7 @@ def Option(
         show_envvar=show_envvar,
         # Choice
         case_sensitive=case_sensitive,
+        names=names,
         # Numbers
         min=min,
         max=max,
@@ -117,6 +119,7 @@ def Argument(
     hidden: bool = False,
     # Choice
     case_sensitive: bool = True,
+    names: bool = False,
     # Numbers
     min: Optional[Union[int, float]] = None,
     max: Optional[Union[int, float]] = None,
@@ -159,6 +162,7 @@ def Argument(
         hidden=hidden,
         # Choice
         case_sensitive=case_sensitive,
+        names=names,
         # Numbers
         min=min,
         max=max,