Coverage for typer / models.py: 100%
128 statements
« prev ^ index » next coverage.py v7.13.1, created at 2026-11-18 11:12 +0000
« prev ^ index » next coverage.py v7.13.1, created at 2026-11-18 11:12 +0000
1import inspect 1abcdefghij
2import io 1abcdefghij
3from collections.abc import Callable, Sequence 1abcdefghij
4from typing import TYPE_CHECKING, Any, Optional, TypeVar 1abcdefghij
6from . import _click 1abcdefghij
7from ._click.shell_completion import CompletionItem 1abcdefghij
9if TYPE_CHECKING: # pragma: no cover 1abcdefghij
10 from .core import TyperCommand, TyperGroup
11 from .main import Typer
14NoneType = type(None) 1abcdefghij
16AnyType = type[Any] 1abcdefghij
18Required = ... 1abcdefghij
21class Context(_click.Context): 1abcdefghij
22 """
23 The [`Context`](https://click.palletsprojects.com/en/stable/api/#click.Context) has some additional data about the current execution of your program.
24 When declaring it in a [callback](https://typer.tiangolo.com/tutorial/options/callback-and-context/) function,
25 you can access this additional information.
26 """
28 pass 1abcdefghij
31class FileText(io.TextIOWrapper): 1abcdefghij
32 """ 1abcdefghij
33 Gives you a file-like object for reading text, and you will get a `str` data from it.
34 The default mode of this class is `mode="r"`.
36 **Example**
38 ```python
39 from typing import Annotated
41 import typer
43 app = typer.Typer()
45 @app.command()
46 def main(config: Annotated[typer.FileText, typer.Option()]):
47 for line in config:
48 print(f"Config line: {line}")
50 if __name__ == "__main__":
51 app()
52 ```
53 """
55 pass 1abcdefghij
58class FileTextWrite(FileText): 1abcdefghij
59 """ 1abcdefghij
60 You can use this class for writing text. Alternatively, you can use `FileText` with `mode="w"`.
61 The default mode of this class is `mode="w"`.
63 **Example**
65 ```python
66 from typing import Annotated
68 import typer
70 app = typer.Typer()
72 @app.command()
73 def main(config: Annotated[typer.FileTextWrite, typer.Option()]):
74 config.write("Some config written by the app")
75 print("Config written")
77 if __name__ == "__main__":
78 app()
79 ```
80 """
82 pass 1abcdefghij
85class FileBinaryRead(io.BufferedReader): 1abcdefghij
86 """ 1abcdefghij
87 You can use this class to read binary data, receiving `bytes`.
88 The default mode of this class is `mode="rb"`.
89 It is useful for reading binary files like images:
91 **Example**
93 ```python
94 from typing import Annotated
96 import typer
98 app = typer.Typer()
100 @app.command()
101 def main(file: Annotated[typer.FileBinaryRead, typer.Option()]):
102 processed_total = 0
103 for bytes_chunk in file:
104 # Process the bytes in bytes_chunk
105 processed_total += len(bytes_chunk)
106 print(f"Processed bytes total: {processed_total}")
108 if __name__ == "__main__":
109 app()
110 ```
111 """
113 pass 1abcdefghij
116class FileBinaryWrite(io.BufferedWriter): 1abcdefghij
117 """ 1abcdefghij
118 You can use this class to write binary data: you pass `bytes` to it instead of strings.
119 The default mode of this class is `mode="wb"`.
120 It is useful for writing binary files like images:
122 **Example**
124 ```python
125 from typing import Annotated
127 import typer
129 app = typer.Typer()
131 @app.command()
132 def main(file: Annotated[typer.FileBinaryWrite, typer.Option()]):
133 first_line_str = "some settings\\n"
134 # You cannot write str directly to a binary file; encode it first
135 first_line_bytes = first_line_str.encode("utf-8")
136 # Then you can write the bytes
137 file.write(first_line_bytes)
138 # This is already bytes, it starts with b"
139 second_line = b"la cig\xc3\xbce\xc3\xb1a trae al ni\xc3\xb1o"
140 file.write(second_line)
141 print("Binary file written")
143 if __name__ == "__main__":
144 app()
145 ```
146 """
148 pass 1abcdefghij
151class CallbackParam(_click.Parameter): 1abcdefghij
152 """
153 In a callback function, you can declare a function parameter with type `CallbackParam`
154 to access the specific Click [`Parameter`](https://click.palletsprojects.com/en/stable/api/#click.Parameter) object.
155 """
157 pass 1abcdefghij
160class DefaultPlaceholder: 1abcdefghij
161 """
162 You shouldn't use this class directly.
164 It's used internally to recognize when a default value has been overwritten, even
165 if the new value is `None`.
166 """
168 def __init__(self, value: Any): 1abcdefghij
169 self.value = value 1abcdefghij
171 def __bool__(self) -> bool: 1abcdefghij
172 return bool(self.value) 1abcdefghij
175DefaultType = TypeVar("DefaultType") 1abcdefghij
177CommandFunctionType = TypeVar("CommandFunctionType", bound=Callable[..., Any]) 1abcdefghij
180def Default(value: DefaultType) -> DefaultType: 1abcdefghij
181 """
182 You shouldn't use this function directly.
184 It's used internally to recognize when a default value has been overwritten, even
185 if the new value is `None`.
186 """
187 return DefaultPlaceholder(value) # type: ignore 1abcdefghij
190class CommandInfo: 1abcdefghij
191 def __init__( 1abcdefghij
192 self,
193 name: str | None = None,
194 *,
195 cls: type["TyperCommand"] | None = None,
196 context_settings: dict[Any, Any] | None = None,
197 callback: Callable[..., Any] | None = None,
198 help: str | None = None,
199 epilog: str | None = None,
200 short_help: str | None = None,
201 options_metavar: str = "[OPTIONS]",
202 add_help_option: bool = True,
203 no_args_is_help: bool = False,
204 hidden: bool = False,
205 deprecated: bool = False,
206 # Rich settings
207 rich_help_panel: str | None = None,
208 ):
209 self.name = name 1abcdefghij
210 self.cls = cls 1abcdefghij
211 self.context_settings = context_settings 1abcdefghij
212 self.callback = callback 1abcdefghij
213 self.help = help 1abcdefghij
214 self.epilog = epilog 1abcdefghij
215 self.short_help = short_help 1abcdefghij
216 self.options_metavar = options_metavar 1abcdefghij
217 self.add_help_option = add_help_option 1abcdefghij
218 self.no_args_is_help = no_args_is_help 1abcdefghij
219 self.hidden = hidden 1abcdefghij
220 self.deprecated = deprecated 1abcdefghij
221 # Rich settings
222 self.rich_help_panel = rich_help_panel 1abcdefghij
225class TyperInfo: 1abcdefghij
226 def __init__( 1abcdefghij
227 self,
228 typer_instance: Optional["Typer"] = Default(None),
229 *,
230 name: str | None = Default(None),
231 cls: type["TyperGroup"] | None = Default(None),
232 invoke_without_command: bool = Default(False),
233 no_args_is_help: bool = Default(False),
234 subcommand_metavar: str | None = Default(None),
235 chain: bool = Default(False),
236 result_callback: Callable[..., Any] | None = Default(None),
237 # Command
238 context_settings: dict[Any, Any] | None = Default(None),
239 callback: Callable[..., Any] | None = Default(None),
240 help: str | None = Default(None),
241 epilog: str | None = Default(None),
242 short_help: str | None = Default(None),
243 options_metavar: str = Default("[OPTIONS]"),
244 add_help_option: bool = Default(True),
245 hidden: bool = Default(False),
246 deprecated: bool = Default(False),
247 # Rich settings
248 rich_help_panel: str | None = Default(None),
249 ):
250 self.typer_instance = typer_instance 1abcdefghij
251 self.name = name 1abcdefghij
252 self.cls = cls 1abcdefghij
253 self.invoke_without_command = invoke_without_command 1abcdefghij
254 self.no_args_is_help = no_args_is_help 1abcdefghij
255 self.subcommand_metavar = subcommand_metavar 1abcdefghij
256 self.chain = chain 1abcdefghij
257 self.result_callback = result_callback 1abcdefghij
258 self.context_settings = context_settings 1abcdefghij
259 self.callback = callback 1abcdefghij
260 self.help = help 1abcdefghij
261 self.epilog = epilog 1abcdefghij
262 self.short_help = short_help 1abcdefghij
263 self.options_metavar = options_metavar 1abcdefghij
264 self.add_help_option = add_help_option 1abcdefghij
265 self.hidden = hidden 1abcdefghij
266 self.deprecated = deprecated 1abcdefghij
267 self.rich_help_panel = rich_help_panel 1abcdefghij
270class ParameterInfo: 1abcdefghij
271 def __init__( 1abcdefghij
272 self,
273 *,
274 default: Any | None = None,
275 param_decls: Sequence[str] | None = None,
276 callback: Callable[..., Any] | None = None,
277 metavar: str | None = None,
278 expose_value: bool = True,
279 is_eager: bool = False,
280 envvar: str | list[str] | None = None,
281 # Note that shell_complete is not fully supported and will be removed in future versions
282 # TODO: Remove shell_complete in a future version (after 0.16.0)
283 shell_complete: Callable[
284 [_click.Context, _click.Parameter, str],
285 list["CompletionItem"] | list[str],
286 ]
287 | None = None,
288 autocompletion: Callable[..., Any] | None = None,
289 default_factory: Callable[[], Any] | None = None,
290 # Custom type
291 parser: Callable[[str], Any] | None = None,
292 # TyperArgument
293 show_default: bool | str = True,
294 show_choices: bool = True,
295 show_envvar: bool = True,
296 help: str | None = None,
297 hidden: bool = False,
298 # Choice
299 case_sensitive: bool = True,
300 # Numbers
301 min: int | float | None = None,
302 max: int | float | None = None,
303 clamp: bool = False,
304 # DateTime
305 formats: list[str] | None = None,
306 # File
307 mode: str | None = None,
308 encoding: str | None = None,
309 errors: str | None = "strict",
310 lazy: bool | None = None,
311 atomic: bool = False,
312 # Path
313 exists: bool = False,
314 file_okay: bool = True,
315 dir_okay: bool = True,
316 writable: bool = False,
317 readable: bool = True,
318 resolve_path: bool = False,
319 allow_dash: bool = False,
320 path_type: None | type[str] | type[bytes] = None,
321 # Rich settings
322 rich_help_panel: str | None = None,
323 ):
324 self.default = default 1abcdefghij
325 self.param_decls = param_decls 1abcdefghij
326 self.callback = callback 1abcdefghij
327 self.metavar = metavar 1abcdefghij
328 self.expose_value = expose_value 1abcdefghij
329 self.is_eager = is_eager 1abcdefghij
330 self.envvar = envvar 1abcdefghij
331 self.shell_complete = shell_complete 1abcdefghij
332 self.autocompletion = autocompletion 1abcdefghij
333 self.default_factory = default_factory 1abcdefghij
334 # Custom type
335 self.parser = parser 1abcdefghij
336 # TyperArgument
337 self.show_default = show_default 1abcdefghij
338 self.show_choices = show_choices 1abcdefghij
339 self.show_envvar = show_envvar 1abcdefghij
340 self.help = help 1abcdefghij
341 self.hidden = hidden 1abcdefghij
342 # Choice
343 self.case_sensitive = case_sensitive 1abcdefghij
344 # Numbers
345 self.min = min 1abcdefghij
346 self.max = max 1abcdefghij
347 self.clamp = clamp 1abcdefghij
348 # DateTime
349 self.formats = formats 1abcdefghij
350 # File
351 self.mode = mode 1abcdefghij
352 self.encoding = encoding 1abcdefghij
353 self.errors = errors 1abcdefghij
354 self.lazy = lazy 1abcdefghij
355 self.atomic = atomic 1abcdefghij
356 # Path
357 self.exists = exists 1abcdefghij
358 self.file_okay = file_okay 1abcdefghij
359 self.dir_okay = dir_okay 1abcdefghij
360 self.writable = writable 1abcdefghij
361 self.readable = readable 1abcdefghij
362 self.resolve_path = resolve_path 1abcdefghij
363 self.allow_dash = allow_dash 1abcdefghij
364 self.path_type = path_type 1abcdefghij
365 # Rich settings
366 self.rich_help_panel = rich_help_panel 1abcdefghij
369class OptionInfo(ParameterInfo): 1abcdefghij
370 def __init__( 1abcdefghij
371 self,
372 *,
373 # ParameterInfo
374 default: Any | None = None,
375 param_decls: Sequence[str] | None = None,
376 callback: Callable[..., Any] | None = None,
377 metavar: str | None = None,
378 expose_value: bool = True,
379 is_eager: bool = False,
380 envvar: str | list[str] | None = None,
381 # Note that shell_complete is not fully supported and will be removed in future versions
382 # TODO: Remove shell_complete in a future version (after 0.16.0)
383 shell_complete: Callable[
384 [_click.Context, _click.Parameter, str],
385 list["CompletionItem"] | list[str],
386 ]
387 | None = None,
388 autocompletion: Callable[..., Any] | None = None,
389 default_factory: Callable[[], Any] | None = None,
390 # Custom type
391 parser: Callable[[str], Any] | None = None,
392 # Option
393 show_default: bool | str = True,
394 prompt: bool | str = False,
395 confirmation_prompt: bool = False,
396 prompt_required: bool = True,
397 hide_input: bool = False,
398 # TODO: remove is_flag and flag_value in a future release
399 is_flag: bool | None = None,
400 flag_value: Any | None = None,
401 count: bool = False,
402 allow_from_autoenv: bool = True,
403 help: str | None = None,
404 hidden: bool = False,
405 show_choices: bool = True,
406 show_envvar: bool = True,
407 # Choice
408 case_sensitive: bool = True,
409 # Numbers
410 min: int | float | None = None,
411 max: int | float | None = None,
412 clamp: bool = False,
413 # DateTime
414 formats: list[str] | None = None,
415 # File
416 mode: str | None = None,
417 encoding: str | None = None,
418 errors: str | None = "strict",
419 lazy: bool | None = None,
420 atomic: bool = False,
421 # Path
422 exists: bool = False,
423 file_okay: bool = True,
424 dir_okay: bool = True,
425 writable: bool = False,
426 readable: bool = True,
427 resolve_path: bool = False,
428 allow_dash: bool = False,
429 path_type: None | type[str] | type[bytes] = None,
430 # Rich settings
431 rich_help_panel: str | None = None,
432 ):
433 super().__init__( 1abcdefghij
434 default=default,
435 param_decls=param_decls,
436 callback=callback,
437 metavar=metavar,
438 expose_value=expose_value,
439 is_eager=is_eager,
440 envvar=envvar,
441 shell_complete=shell_complete,
442 autocompletion=autocompletion,
443 default_factory=default_factory,
444 # Custom type
445 parser=parser,
446 # TyperArgument
447 show_default=show_default,
448 show_choices=show_choices,
449 show_envvar=show_envvar,
450 help=help,
451 hidden=hidden,
452 # Choice
453 case_sensitive=case_sensitive,
454 # Numbers
455 min=min,
456 max=max,
457 clamp=clamp,
458 # DateTime
459 formats=formats,
460 # File
461 mode=mode,
462 encoding=encoding,
463 errors=errors,
464 lazy=lazy,
465 atomic=atomic,
466 # Path
467 exists=exists,
468 file_okay=file_okay,
469 dir_okay=dir_okay,
470 writable=writable,
471 readable=readable,
472 resolve_path=resolve_path,
473 allow_dash=allow_dash,
474 path_type=path_type,
475 # Rich settings
476 rich_help_panel=rich_help_panel,
477 )
478 if is_flag is not None or flag_value is not None: 1abcdefghij
479 import warnings 1abcdefghij
481 warnings.warn( 1abcdefghij
482 "The 'is_flag' and 'flag_value' parameters are not supported by Typer "
483 "and will be removed entirely in a future release.",
484 DeprecationWarning,
485 stacklevel=2,
486 )
487 self.prompt = prompt 1abcdefghij
488 self.confirmation_prompt = confirmation_prompt 1abcdefghij
489 self.prompt_required = prompt_required 1abcdefghij
490 self.hide_input = hide_input 1abcdefghij
491 self.count = count 1abcdefghij
492 self.allow_from_autoenv = allow_from_autoenv 1abcdefghij
495class ArgumentInfo(ParameterInfo): 1abcdefghij
496 def __init__( 1abcdefghij
497 self,
498 *,
499 # ParameterInfo
500 default: Any | None = None,
501 param_decls: Sequence[str] | None = None,
502 callback: Callable[..., Any] | None = None,
503 metavar: str | None = None,
504 expose_value: bool = True,
505 is_eager: bool = False,
506 envvar: str | list[str] | None = None,
507 # Note that shell_complete is not fully supported and will be removed in future versions
508 # TODO: Remove shell_complete in a future version (after 0.16.0)
509 shell_complete: Callable[
510 [_click.Context, _click.Parameter, str],
511 list["CompletionItem"] | list[str],
512 ]
513 | None = None,
514 autocompletion: Callable[..., Any] | None = None,
515 default_factory: Callable[[], Any] | None = None,
516 # Custom type
517 parser: Callable[[str], Any] | None = None,
518 # TyperArgument
519 show_default: bool | str = True,
520 show_choices: bool = True,
521 show_envvar: bool = True,
522 help: str | None = None,
523 hidden: bool = False,
524 # Choice
525 case_sensitive: bool = True,
526 # Numbers
527 min: int | float | None = None,
528 max: int | float | None = None,
529 clamp: bool = False,
530 # DateTime
531 formats: list[str] | None = None,
532 # File
533 mode: str | None = None,
534 encoding: str | None = None,
535 errors: str | None = "strict",
536 lazy: bool | None = None,
537 atomic: bool = False,
538 # Path
539 exists: bool = False,
540 file_okay: bool = True,
541 dir_okay: bool = True,
542 writable: bool = False,
543 readable: bool = True,
544 resolve_path: bool = False,
545 allow_dash: bool = False,
546 path_type: None | type[str] | type[bytes] = None,
547 # Rich settings
548 rich_help_panel: str | None = None,
549 ):
550 super().__init__( 1abcdefghij
551 default=default,
552 param_decls=param_decls,
553 callback=callback,
554 metavar=metavar,
555 expose_value=expose_value,
556 is_eager=is_eager,
557 envvar=envvar,
558 shell_complete=shell_complete,
559 autocompletion=autocompletion,
560 default_factory=default_factory,
561 # Custom type
562 parser=parser,
563 # TyperArgument
564 show_default=show_default,
565 show_choices=show_choices,
566 show_envvar=show_envvar,
567 help=help,
568 hidden=hidden,
569 # Choice
570 case_sensitive=case_sensitive,
571 # Numbers
572 min=min,
573 max=max,
574 clamp=clamp,
575 # DateTime
576 formats=formats,
577 # File
578 mode=mode,
579 encoding=encoding,
580 errors=errors,
581 lazy=lazy,
582 atomic=atomic,
583 # Path
584 exists=exists,
585 file_okay=file_okay,
586 dir_okay=dir_okay,
587 writable=writable,
588 readable=readable,
589 resolve_path=resolve_path,
590 allow_dash=allow_dash,
591 path_type=path_type,
592 # Rich settings
593 rich_help_panel=rich_help_panel,
594 )
597class ParamMeta: 1abcdefghij
598 empty = inspect.Parameter.empty 1abcdefghij
600 def __init__( 1abcdefghij
601 self,
602 *,
603 name: str,
604 default: Any = inspect.Parameter.empty,
605 annotation: Any = inspect.Parameter.empty,
606 ) -> None:
607 self.name = name 1abcdefghij
608 self.default = default 1abcdefghij
609 self.annotation = annotation 1abcdefghij
612class DeveloperExceptionConfig: 1abcdefghij
613 def __init__( 1abcdefghij
614 self,
615 *,
616 pretty_exceptions_enable: bool = True,
617 pretty_exceptions_show_locals: bool = True,
618 pretty_exceptions_short: bool = True,
619 ) -> None:
620 self.pretty_exceptions_enable = pretty_exceptions_enable 1abcdefghij
621 self.pretty_exceptions_show_locals = pretty_exceptions_show_locals 1abcdefghij
622 self.pretty_exceptions_short = pretty_exceptions_short 1abcdefghij