Coverage for typer / utils.py: 100%

1import inspect 7 ctx1aecfbdg

2from collections.abc import Callable 7 ctx1aecfbdg

3from copy import copy 7 ctx1aecfbdg

4from typing import Any, cast 7 ctx1aecfbdg

5 

6from ._typing import Annotated, get_args, get_origin, get_type_hints 7 ctx1aecfbdg

7from .models import ArgumentInfo, OptionInfo, ParameterInfo, ParamMeta 7 ctx1aecfbdg

8 

9 

10def _param_type_to_user_string(param_type: type[ParameterInfo]) -> str: 7 ctx1aecfbdg

11 # Render a `ParameterInfo` subclass for use in error messages. 

12 # User code doesn't call `*Info` directly, so errors should present the classes how 

13 # they were (probably) defined in the user code. 

14 if param_type is OptionInfo: 7 ctx1aecfbdg

15 return "`Option`" 7 ctx1aecfbdg

16 elif param_type is ArgumentInfo: 7 ctx1aecfbdg

17 return "`Argument`" 7 ctx1aecfbdg

18 # This line shouldn't be reachable during normal use. 

19 return f"`{param_type.__name__}`" # pragma: no cover 

20 

21 

22class AnnotatedParamWithDefaultValueError(Exception): 7 ctx1aecfbdg

23 argument_name: str 4 ctx1acbd

24 param_type: type[ParameterInfo] 4 ctx1acbd

25 

26 def __init__(self, argument_name: str, param_type: type[ParameterInfo]): 7 ctx1aecfbdg

27 self.argument_name = argument_name 7 ctx1aecfbdg

28 self.param_type = param_type 7 ctx1aecfbdg

29 

30 def __str__(self) -> str: 7 ctx1aecfbdg

31 param_type_str = _param_type_to_user_string(self.param_type) 7 ctx1aecfbdg

32 return ( 7 ctx1aecfbdg

33 f"{param_type_str} default value cannot be set in `Annotated`" 

34 f" for {self.argument_name!r}. Set the default value with `=` instead." 

35 ) 

36 

37 

38class MixedAnnotatedAndDefaultStyleError(Exception): 7 ctx1aecfbdg

39 argument_name: str 4 ctx1acbd

40 annotated_param_type: type[ParameterInfo] 4 ctx1acbd

41 default_param_type: type[ParameterInfo] 4 ctx1acbd

42 

43 def __init__( 7 ctx1aecfbdg

44 self, 

45 argument_name: str, 

46 annotated_param_type: type[ParameterInfo], 

47 default_param_type: type[ParameterInfo], 

48 ): 

49 self.argument_name = argument_name 7 ctx1aecfbdg

50 self.annotated_param_type = annotated_param_type 7 ctx1aecfbdg

51 self.default_param_type = default_param_type 7 ctx1aecfbdg

52 

53 def __str__(self) -> str: 7 ctx1aecfbdg

54 annotated_param_type_str = _param_type_to_user_string(self.annotated_param_type) 7 ctx1aecfbdg

55 default_param_type_str = _param_type_to_user_string(self.default_param_type) 7 ctx1aecfbdg

56 msg = f"Cannot specify {annotated_param_type_str} in `Annotated` and" 7 ctx1aecfbdg

57 if self.annotated_param_type is self.default_param_type: 7 ctx1aecfbdg

58 msg += " default value" 7 ctx1aecfbdg

59 else: 

60 msg += f" {default_param_type_str} as a default value" 7 ctx1aecfbdg

61 msg += f" together for {self.argument_name!r}" 7 ctx1aecfbdg

62 return msg 7 ctx1aecfbdg

63 

64 

65class MultipleTyperAnnotationsError(Exception): 7 ctx1aecfbdg

66 argument_name: str 4 ctx1acbd

67 

68 def __init__(self, argument_name: str): 7 ctx1aecfbdg

69 self.argument_name = argument_name 7 ctx1aecfbdg

70 

71 def __str__(self) -> str: 7 ctx1aecfbdg

72 return ( 7 ctx1aecfbdg

73 "Cannot specify multiple `Annotated` Typer arguments" 

74 f" for {self.argument_name!r}" 

75 ) 

76 

77 

78class DefaultFactoryAndDefaultValueError(Exception): 7 ctx1aecfbdg

79 argument_name: str 4 ctx1acbd

80 param_type: type[ParameterInfo] 4 ctx1acbd

81 

82 def __init__(self, argument_name: str, param_type: type[ParameterInfo]): 7 ctx1aecfbdg

83 self.argument_name = argument_name 7 ctx1aecfbdg

84 self.param_type = param_type 7 ctx1aecfbdg

85 

86 def __str__(self) -> str: 7 ctx1aecfbdg

87 param_type_str = _param_type_to_user_string(self.param_type) 7 ctx1aecfbdg

88 return ( 7 ctx1aecfbdg

89 "Cannot specify `default_factory` and a default value together" 

90 f" for {param_type_str}" 

91 ) 

92 

93 

94def _split_annotation_from_typer_annotations( 7 ctx1aecfbdg

95 base_annotation: type[Any], 

96) -> tuple[type[Any], list[ParameterInfo]]: 

97 if get_origin(base_annotation) is not Annotated: 7 ctx1aecfbdg

98 return base_annotation, [] 7 ctx1aecfbdg

99 base_annotation, *maybe_typer_annotations = get_args(base_annotation) 7 ctx1aecfbdg

100 return base_annotation, [ 7 ctx1aecfbdg

101 annotation 

102 for annotation in maybe_typer_annotations 

103 if isinstance(annotation, ParameterInfo) 

104 ] 

105 

106 

107def get_params_from_function(func: Callable[..., Any]) -> dict[str, ParamMeta]: 7 ctx1aecfbdg

108 signature = inspect.signature(func, eval_str=True) 7 ctx1aecfbdg

109 type_hints = get_type_hints(func) 7 ctx1aecfbdg

110 params = {} 7 ctx1aecfbdg

111 for param in signature.parameters.values(): 7 ctx1aecfbdg

112 annotation, typer_annotations = _split_annotation_from_typer_annotations( 7 ctx1aecfbdg

113 param.annotation, 

114 ) 

115 if len(typer_annotations) > 1: 7 ctx1aecfbdg

116 raise MultipleTyperAnnotationsError(param.name) 7 ctx1aecfbdg

117 

118 default = param.default 7 ctx1aecfbdg

119 if typer_annotations: 7 ctx1aecfbdg

120 # It's something like `my_param: Annotated[str, Argument()]` 

121 [parameter_info] = typer_annotations 7 ctx1aecfbdg

122 

123 # Forbid `my_param: Annotated[str, Argument()] = Argument("...")` 

124 if isinstance(param.default, ParameterInfo): 7 ctx1aecfbdg

125 raise MixedAnnotatedAndDefaultStyleError( 7 ctx1aecfbdg

126 argument_name=param.name, 

127 annotated_param_type=type(parameter_info), 

128 default_param_type=type(param.default), 

129 ) 

130 

131 parameter_info = copy(parameter_info) 7 ctx1aecfbdg

132 

133 # When used as a default, `Option` takes a default value and option names 

134 # as positional arguments: 

135 # `Option(some_value, "--some-argument", "-s")` 

136 # When used in `Annotated` (ie, what this is handling), `Option` just takes 

137 # option names as positional arguments: 

138 # `Option("--some-argument", "-s")` 

139 # In this case, the `default` attribute of `parameter_info` is actually 

140 # meant to be the first item of `param_decls`. 

141 if ( 2 ctx1ab

142 isinstance(parameter_info, OptionInfo) 

143 and parameter_info.default is not ... 

144 ): 

145 parameter_info.param_decls = ( 7 ctx1aecfbdg

146 cast(str, parameter_info.default), 

147 *(parameter_info.param_decls or ()), 

148 ) 

149 parameter_info.default = ... 7 ctx1aecfbdg

150 

151 # Forbid `my_param: Annotated[str, Argument('some-default')]` 

152 if parameter_info.default is not ...: 7 ctx1aecfbdg

153 raise AnnotatedParamWithDefaultValueError( 7 ctx1aecfbdg

154 param_type=type(parameter_info), 

155 argument_name=param.name, 

156 ) 

157 if param.default is not param.empty: 7 ctx1aecfbdg

158 # Put the parameter's default (set by `=`) into `parameter_info`, where 

159 # typer can find it. 

160 parameter_info.default = param.default 7 ctx1aecfbdg

161 

162 default = parameter_info 7 ctx1aecfbdg

163 elif param.name in type_hints: 7 ctx1aecfbdg

164 # Resolve forward references. 

165 annotation = type_hints[param.name] 7 ctx1aecfbdg

166 

167 if isinstance(default, ParameterInfo): 7 ctx1aecfbdg

168 parameter_info = copy(default) 7 ctx1aecfbdg

169 # Click supports `default` as either 

170 # - an actual value; or 

171 # - a factory function (returning a default value.) 

172 # The two are not interchangeable for static typing, so typer allows 

173 # specifying `default_factory`. Move the `default_factory` into `default` 

174 # so click can find it. 

175 if parameter_info.default is ... and parameter_info.default_factory: 7 ctx1aecfbdg

176 parameter_info.default = parameter_info.default_factory 7 ctx1aecfbdg

177 elif parameter_info.default_factory: 7 ctx1aecfbdg

178 raise DefaultFactoryAndDefaultValueError( 7 ctx1aecfbdg

179 argument_name=param.name, param_type=type(parameter_info) 

180 ) 

181 default = parameter_info 7 ctx1aecfbdg

182 

183 params[param.name] = ParamMeta( 7 ctx1aecfbdg

184 name=param.name, default=default, annotation=annotation 

185 ) 

186 return params 7 ctx1aecfbdg

187 

188 

189def parse_boolean_env_var(env_var_value: str | None, default: bool) -> bool: 7 ctx1aecfbdg

190 if env_var_value is None: 7 ctx1aecfbdg

191 return default 7 ctx1aecfbdg

192 value = env_var_value.lower() 7 ctx1aecfbdg

193 if value in ("y", "yes", "t", "true", "on", "1"): 7 ctx1aecfbdg

194 return True 7 ctx1aecfbdg

195 if value in ("n", "no", "f", "false", "off", "0"): 7 ctx1aecfbdg

196 return False 7 ctx1aecfbdg

197 return default 7 ctx1aecfbdg