lazy definition of runtimeparam to avoid up-front cost

Author: svlandeg

tests/test_coercion.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 
 import typer
+from typer.core import TyperParameter
 from typer.testing import CliRunner
 
 runner = CliRunner()
@@ -147,8 +148,9 @@ def main(val=Widget(42)):
         seen["val"] = val
 
     param = next(p for p in typer.main.get_command(app).params if p.name == "val")
-    assert param.runtime_param is not None
-    assert param.runtime_param.annotation is Widget
+    assert isinstance(param, TyperParameter)
+    assert param.get_runtime_param() is not None
+    assert param.get_runtime_param().annotation is Widget
 
     result = runner.invoke(app)
     assert result.exit_code == 0
@@ -177,8 +179,9 @@ def main(val: Widget = typer.Option("42", parser=parse_widget)):
         seen["val"] = val
 
     param = next(p for p in typer.main.get_command(app).params if p.name == "val")
-    assert param.runtime_param is not None
-    assert param.runtime_param.annotation is Widget
+    assert isinstance(param, TyperParameter)
+    assert param.get_runtime_param() is not None
+    assert param.get_runtime_param().annotation is Widget
 
     result = runner.invoke(app)
     assert result.exit_code == 0

tests/test_type_conversion.py

@@ -9,6 +9,7 @@
 import pytest
 import typer
 from typer import _click, param_types
+from typer.core import TyperParameter
 from typer.testing import CliRunner
 
 from tests.utils import needs_linux, needs_windows
@@ -445,12 +446,15 @@ def cmd(val=default):
         pass  # pragma: no cover
 
     param = next(p for p in typer.main.get_command(app).params if p.name == "val")
-    assert param.runtime_param is not None
+    assert isinstance(param, TyperParameter)
+    assert param.get_runtime_param() is not None
     if get_origin(expected_annotation) is tuple:
-        assert get_origin(param.runtime_param.annotation) is tuple
-        assert get_args(param.runtime_param.annotation) == get_args(expected_annotation)
+        assert get_origin(param.get_runtime_param().annotation) is tuple
+        assert get_args(param.get_runtime_param().annotation) == get_args(
+            expected_annotation
+        )
     else:
-        assert param.runtime_param.annotation is expected_annotation
+        assert param.get_runtime_param().annotation is expected_annotation
 
 
 @pytest.mark.parametrize(

typer/_click/decorators.py

@@ -40,7 +40,7 @@ def decorator(f: Command) -> Command:
 
 def help_option(param_decls: list[str]) -> Callable[[Command], Command]:
     """Help option which prints the help page and exits the program."""
-    from ..coercion import bool_flag_runtime_param, bool_flag_type_descriptor
+    from ..coercion import bool_flag_type_descriptor
 
     def show_help(ctx: Context, param: Parameter, value: bool) -> None:
         """Callback that print the help page on ``<stdout>`` and exits."""
@@ -58,6 +58,5 @@ def show_help(ctx: Context, param: Parameter, value: bool) -> None:
         help="Show this message and exit.",
         callback=show_help,
         required=False,
-        runtime_param=bool_flag_runtime_param(),
         type_descriptor=bool_flag_type_descriptor(),
     )

typer/adapters.py

@@ -52,17 +52,28 @@ def try_build_adapter(
         return None
 
 
+def validate_annotation_structure(annotation: Any) -> None:
+    """Raise on invalid nested CLI annotations (developer errors)."""
+    origin = get_origin(annotation)
+    if origin is list:
+        args = get_args(annotation)
+        if len(args) != 1:
+            raise ValueError(f"Expected one list item type, got: {args!r}")
+        validate_annotation_structure(args[0])
+    elif origin is tuple:
+        for item_type in get_args(annotation):
+            validate_annotation_structure(item_type)
+
+
 def build_adapter(annotation: Any, parameter_info: ParameterInfo) -> TypeAdapter[Any]:
     """Build a Pydantic TypeAdapter for a parameter annotation and metadata.
     Check for list/tuple and call this function recursively.
     Otherwise, delegate to build_leaf_adapter.
     """
     origin = get_origin(annotation)
     if origin is list:
-        args = get_args(annotation)
-        if len(args) != 1:
-            raise ValueError(f"Expected one list item type, got: {args!r}")
-        list_type = args[0]
+        validate_annotation_structure(annotation)
+        list_type = get_args(annotation)[0]
         adapter = build_adapter(list_type, parameter_info)
 
         def parse_list(value: Any, info: ValidationInfo) -> list[Any]:

typer/coercion.py

@@ -35,7 +35,6 @@
 class TypeDescriptor:
     annotation: ParameterAnnotation
     parameter_info: ParameterInfo
-    adapter: TypeAdapter[Any] | None
     file_annotation: Any | None
 
     @property
@@ -119,15 +118,12 @@ def resolve_type_descriptor(
     annotation: ParameterAnnotation,
     parameter_info: ParameterInfo,
 ) -> TypeDescriptor:
-    """Resolve Pydantic adapter for one parameter annotation."""
+    """Create type descriptor for one parameter annotation."""
+    adapters.validate_annotation_structure(annotation)
     file_annotation = file_coercion_annotation(annotation)
-    adapter = None
-    if file_annotation is None:
-        adapter = adapters.try_build_adapter(annotation, parameter_info)
     return TypeDescriptor(
         annotation=annotation,
         parameter_info=parameter_info,
-        adapter=adapter,
         file_annotation=file_annotation,
     )
 
@@ -224,8 +220,9 @@ def build_runtime_param(descriptor: TypeDescriptor) -> RuntimeParam:
     }
     if descriptor.file_annotation is not None:
         return FileRuntimeParam(**args, file_annotation=descriptor.file_annotation)
-    if descriptor.adapter is not None:
-        return AdapterRuntimeParam(**args, adapter=descriptor.adapter)
+    adapter = adapters.try_build_adapter(**args)
+    if adapter is not None:
+        return AdapterRuntimeParam(**args, adapter=adapter)
     return PassThroughRuntimeParam(**args)
 
 
@@ -237,11 +234,6 @@ def bool_flag_type_descriptor() -> TypeDescriptor:
     )
 
 
-def bool_flag_runtime_param() -> RuntimeParam:
-    """Build runtime coercion for a standalone boolean flag option."""
-    return build_runtime_param(bool_flag_type_descriptor())
-
-
 def prompt_value_proc(
     param_type: Any | None = None,
     default: Any | None = None,

typer/core.py

@@ -19,7 +19,7 @@
 from ._click.parser import _OptionParser
 from ._click.shell_completion import CompletionItem
 from ._typing import Literal
-from .coercion import RuntimeParam, TypeDescriptor
+from .coercion import RuntimeParam, TypeDescriptor, build_runtime_param
 from .display import describe_number_range
 from .param_types import choice_as_str, normalize_choice_value
 from .utils import parse_boolean_env_var
@@ -88,12 +88,19 @@ def compat_autocompletion(
 class TyperParameter(_click.core.Parameter):
     """Typer parameter with runtime coercion."""
 
-    runtime_param: RuntimeParam
+    _runtime_param: RuntimeParam | None
     type_descriptor: TypeDescriptor
     show_choices: bool
 
+    def get_runtime_param(self) -> RuntimeParam:
+        """lazy definition to avoid up-front costs"""
+        if self._runtime_param is None:
+            self._runtime_param = build_runtime_param(self.type_descriptor)
+        assert self._runtime_param is not None
+        return self._runtime_param
+
     def process_value(self, ctx: _click.Context, value: Any) -> Any:
-        value = self.runtime_param.coerce(value, param=self, ctx=ctx)
+        value = self.get_runtime_param().coerce(value, param=self, ctx=ctx)
         if self.required and self.value_is_missing(value):
             raise _click.exceptions.MissingParameter(ctx=ctx, param=self)
         if self.callback is not None:
@@ -200,7 +207,7 @@ def display_type_rich(self, ctx: _click.Context) -> str | None:
         return self.display_type(ctx)
 
     def bare_type(self) -> str:
-        annotation = self.runtime_param.annotation
+        annotation = self.type_descriptor.annotation
         return self._bare_type(annotation)
 
     def _bare_type(self, annotation: type) -> str:
@@ -389,7 +396,6 @@ def __init__(
         *,
         # Parameter
         param_decls: list[str],
-        runtime_param: RuntimeParam,
         type_descriptor: TypeDescriptor,
         required: bool = False,
         default: Any | None = None,
@@ -427,8 +433,8 @@ def __init__(
         self.min = min
         self.max = max
         self.rich_help_panel = rich_help_panel
-        self.runtime_param = runtime_param
         self.type_descriptor = type_descriptor
+        self._runtime_param = None
 
         super().__init__(
             param_decls=param_decls,
@@ -570,7 +576,6 @@ def __init__(
         *,
         # Parameter
         param_decls: list[str],
-        runtime_param: RuntimeParam,
         type_descriptor: TypeDescriptor,
         required: bool = False,
         default: Any | None = None,
@@ -613,8 +618,8 @@ def __init__(
 
         self.min = min
         self.max = max
-        self.runtime_param = runtime_param
         self.type_descriptor = type_descriptor
+        self._runtime_param = None
 
         super().__init__(
             param_decls,

typer/main.py

@@ -16,7 +16,7 @@
 from . import _click
 from ._click.globals import get_current_context
 from ._typing import get_args, get_origin
-from .coercion import build_runtime_param, resolve_type_descriptor
+from .coercion import resolve_type_descriptor
 from .completion import get_completion_inspect_parameters
 from .core import (
     DEFAULT_MARKUP_MODE,
@@ -1498,7 +1498,6 @@ def get_param(param: ParamMeta) -> TyperArgument | TyperOption:
         annotation=annotation,
         parameter_info=parameter_info,
     )
-    runtime_param = build_runtime_param(descriptor)
     tuple_nargs = descriptor.tuple_arity
 
     if isinstance(parameter_info, OptionInfo):
@@ -1547,7 +1546,6 @@ def get_param(param: ParamMeta) -> TyperArgument | TyperOption:
             nargs=tuple_nargs,
             # Rich settings
             rich_help_panel=parameter_info.rich_help_panel,
-            runtime_param=runtime_param,
             type_descriptor=descriptor,
         )
     elif isinstance(parameter_info, ArgumentInfo):
@@ -1581,7 +1579,6 @@ def get_param(param: ParamMeta) -> TyperArgument | TyperOption:
             max=parameter_info.max,
             # Rich settings
             rich_help_panel=parameter_info.rich_help_panel,
-            runtime_param=runtime_param,
             type_descriptor=descriptor,
         )
     raise AssertionError("A Parameter should be returned")  # pragma: no cover