typer.utils

  1import inspect
  2import sys
  3from copy import copy
  4from typing import Any, Callable, Dict, List, Tuple, Type, cast
  5
  6from typing_extensions import Annotated, get_args, get_origin, get_type_hints
  7
  8from .models import ArgumentInfo, OptionInfo, ParameterInfo, ParamMeta
  9
 10
 11def _param_type_to_user_string(param_type: Type[ParameterInfo]) -> str:
 12    # Render a `ParameterInfo` subclass for use in error messages.
 13    # User code doesn't call `*Info` directly, so errors should present the classes how
 14    # they were (probably) defined in the user code.
 15    if param_type is OptionInfo:
 16        return "`Option`"
 17    elif param_type is ArgumentInfo:
 18        return "`Argument`"
 19    # This line shouldn't be reachable during normal use.
 20    return f"`{param_type.__name__}`"  # pragma: no cover
 21
 22
 23class AnnotatedParamWithDefaultValueError(Exception):
 24    argument_name: str
 25    param_type: Type[ParameterInfo]
 26
 27    def __init__(self, argument_name: str, param_type: Type[ParameterInfo]):
 28        self.argument_name = argument_name
 29        self.param_type = param_type
 30
 31    def __str__(self) -> str:
 32        param_type_str = _param_type_to_user_string(self.param_type)
 33        return (
 34            f"{param_type_str} default value cannot be set in `Annotated`"
 35            f" for {self.argument_name!r}. Set the default value with `=` instead."
 36        )
 37
 38
 39class MixedAnnotatedAndDefaultStyleError(Exception):
 40    argument_name: str
 41    annotated_param_type: Type[ParameterInfo]
 42    default_param_type: Type[ParameterInfo]
 43
 44    def __init__(
 45        self,
 46        argument_name: str,
 47        annotated_param_type: Type[ParameterInfo],
 48        default_param_type: Type[ParameterInfo],
 49    ):
 50        self.argument_name = argument_name
 51        self.annotated_param_type = annotated_param_type
 52        self.default_param_type = default_param_type
 53
 54    def __str__(self) -> str:
 55        annotated_param_type_str = _param_type_to_user_string(self.annotated_param_type)
 56        default_param_type_str = _param_type_to_user_string(self.default_param_type)
 57        msg = f"Cannot specify {annotated_param_type_str} in `Annotated` and"
 58        if self.annotated_param_type is self.default_param_type:
 59            msg += " default value"
 60        else:
 61            msg += f" {default_param_type_str} as a default value"
 62        msg += f" together for {self.argument_name!r}"
 63        return msg
 64
 65
 66class MultipleTyperAnnotationsError(Exception):
 67    argument_name: str
 68
 69    def __init__(self, argument_name: str):
 70        self.argument_name = argument_name
 71
 72    def __str__(self) -> str:
 73        return (
 74            "Cannot specify multiple `Annotated` Typer arguments"
 75            f" for {self.argument_name!r}"
 76        )
 77
 78
 79class DefaultFactoryAndDefaultValueError(Exception):
 80    argument_name: str
 81    param_type: Type[ParameterInfo]
 82
 83    def __init__(self, argument_name: str, param_type: Type[ParameterInfo]):
 84        self.argument_name = argument_name
 85        self.param_type = param_type
 86
 87    def __str__(self) -> str:
 88        param_type_str = _param_type_to_user_string(self.param_type)
 89        return (
 90            "Cannot specify `default_factory` and a default value together"
 91            f" for {param_type_str}"
 92        )
 93
 94
 95def _split_annotation_from_typer_annotations(
 96    base_annotation: Type[Any],
 97) -> Tuple[Type[Any], List[ParameterInfo]]:
 98    if get_origin(base_annotation) is not Annotated:
 99        return base_annotation, []
100    base_annotation, *maybe_typer_annotations = get_args(base_annotation)
101    return base_annotation, [
102        annotation
103        for annotation in maybe_typer_annotations
104        if isinstance(annotation, ParameterInfo)
105    ]
106
107
108def get_params_from_function(func: Callable[..., Any]) -> Dict[str, ParamMeta]:
109    if sys.version_info >= (3, 10):
110        signature = inspect.signature(func, eval_str=True)
111    else:
112        signature = inspect.signature(func)
113
114    type_hints = get_type_hints(func)
115    params = {}
116    for param in signature.parameters.values():
117        annotation, typer_annotations = _split_annotation_from_typer_annotations(
118            param.annotation,
119        )
120        if len(typer_annotations) > 1:
121            raise MultipleTyperAnnotationsError(param.name)
122
123        default = param.default
124        if typer_annotations:
125            # It's something like `my_param: Annotated[str, Argument()]`
126            [parameter_info] = typer_annotations
127
128            # Forbid `my_param: Annotated[str, Argument()] = Argument("...")`
129            if isinstance(param.default, ParameterInfo):
130                raise MixedAnnotatedAndDefaultStyleError(
131                    argument_name=param.name,
132                    annotated_param_type=type(parameter_info),
133                    default_param_type=type(param.default),
134                )
135
136            parameter_info = copy(parameter_info)
137
138            # When used as a default, `Option` takes a default value and option names
139            # as positional arguments:
140            #   `Option(some_value, "--some-argument", "-s")`
141            # When used in `Annotated` (ie, what this is handling), `Option` just takes
142            # option names as positional arguments:
143            #   `Option("--some-argument", "-s")`
144            # In this case, the `default` attribute of `parameter_info` is actually
145            # meant to be the first item of `param_decls`.
146            if (
147                isinstance(parameter_info, OptionInfo)
148                and parameter_info.default is not ...
149            ):
150                parameter_info.param_decls = (
151                    cast(str, parameter_info.default),
152                    *(parameter_info.param_decls or ()),
153                )
154                parameter_info.default = ...
155
156            # Forbid `my_param: Annotated[str, Argument('some-default')]`
157            if parameter_info.default is not ...:
158                raise AnnotatedParamWithDefaultValueError(
159                    param_type=type(parameter_info),
160                    argument_name=param.name,
161                )
162            if param.default is not param.empty:
163                # Put the parameter's default (set by `=`) into `parameter_info`, where
164                # typer can find it.
165                parameter_info.default = param.default
166
167            default = parameter_info
168        elif param.name in type_hints:
169            # Resolve forward references.
170            annotation = type_hints[param.name]
171
172        if isinstance(default, ParameterInfo):
173            parameter_info = copy(default)
174            # Click supports `default` as either
175            # - an actual value; or
176            # - a factory function (returning a default value.)
177            # The two are not interchangeable for static typing, so typer allows
178            # specifying `default_factory`. Move the `default_factory` into `default`
179            # so click can find it.
180            if parameter_info.default is ... and parameter_info.default_factory:
181                parameter_info.default = parameter_info.default_factory
182            elif parameter_info.default_factory:
183                raise DefaultFactoryAndDefaultValueError(
184                    argument_name=param.name, param_type=type(parameter_info)
185                )
186            default = parameter_info
187
188        params[param.name] = ParamMeta(
189            name=param.name, default=default, annotation=annotation
190        )
191    return params