Coverage for typer / _click / core.py: 100%

1import enum 7 ctx1aecfbdg

2import inspect 7 ctx1aecfbdg

3import os 7 ctx1aecfbdg

4from abc import ABC, abstractmethod 7 ctx1aecfbdg

5from collections.abc import ( 7 ctx1aecfbdg

6 Callable, 

7 Generator, 

8 Iterator, 

9 Mapping, 

10 MutableMapping, 

11 Sequence, 

12) 

13from contextlib import AbstractContextManager, ExitStack, contextmanager 7 ctx1aecfbdg

14from types import TracebackType 7 ctx1aecfbdg

15from typing import ( 7 ctx1aecfbdg

16 TYPE_CHECKING, 

17 Any, 

18 Literal, 

19 NoReturn, 

20 TypeVar, 

21 Union, 

22 cast, 

23 overload, 

24) 

25 

26from ..exceptions import Abort, Exit 7 ctx1aecfbdg

27from . import types 7 ctx1aecfbdg

28from .exceptions import BadParameter, MissingParameter, NoArgsIsHelpError, UsageError 7 ctx1aecfbdg

29from .formatting import HelpFormatter 7 ctx1aecfbdg

30from .globals import pop_context, push_context 7 ctx1aecfbdg

31from .parser import _OptionParser 7 ctx1aecfbdg

32from .termui import style 7 ctx1aecfbdg

33from .utils import _escape_control_characters, echo, make_default_short_help 7 ctx1aecfbdg

34 

35if TYPE_CHECKING: 7 ctx1aecfbdg

36 from ..core import TyperOption 

37 from .shell_completion import CompletionItem 

38 

39F = TypeVar("F", bound="Callable[..., Any]") 7 ctx1aecfbdg

40V = TypeVar("V") 7 ctx1aecfbdg

41 

42 

43def _complete_visible_commands( 7 ctx1aecfbdg

44 ctx: "Context", incomplete: str 

45) -> Iterator[tuple[str, "Command"]]: 

46 """List all the subcommands of a group that start with the 

47 incomplete value and aren't hidden. 

48 """ 

49 # avoid circular imports 

50 from ..core import TyperGroup 7 ctx1aecfbdg

51 

52 multi = cast(TyperGroup, ctx.command) 7 ctx1aecfbdg

53 

54 for name in multi.list_commands(ctx): 7 ctx1aecfbdg

55 if name.startswith(incomplete): 7 ctx1aecfbdg

56 command = multi.get_command(ctx, name) 7 ctx1aecfbdg

57 

58 if command is not None and not command.hidden: 7 ctx1aecfbdg

59 yield name, command 7 ctx1aecfbdg

60 

61 

62@contextmanager 7 ctx1aecfbdg

63def augment_usage_errors( 7 ctx1aecfbdg

64 ctx: "Context", param: Union["Parameter", None] = None 

65) -> Generator[None]: 

66 """Context manager that attaches extra information to exceptions.""" 

67 try: 7 ctx1aecfbdg

68 yield 7 ctx1aecfbdg

69 except BadParameter as e: 7 ctx1aecfbdg

70 if e.ctx is None: 7 ctx1aecfbdg

71 e.ctx = ctx 7 ctx1aecfbdg

72 if param is not None and e.param is None: 7 ctx1aecfbdg

73 e.param = param 7 ctx1aecfbdg

74 raise 7 ctx1aecfbdg

75 except UsageError as e: # pragma: no cover 7 ctx1aecfbdg

76 if e.ctx is None: 

77 e.ctx = ctx 

78 raise 

79 

80 

81def iter_params_for_processing( 7 ctx1aecfbdg

82 invocation_order: Sequence["Parameter"], 

83 declaration_order: Sequence["Parameter"], 

84) -> list["Parameter"]: 

85 """Returns all declared parameters in the order they should be processed. 

86 

87 The declared parameters are re-shuffled depending on the order in which 

88 they were invoked, as well as the eagerness of each parameters. 

89 

90 The invocation order takes precedence over the declaration order. I.e. the 

91 order in which the user provided them to the CLI is respected. 

92 

93 This behavior and its effect on callback evaluation is detailed at: 

94 https://click.palletsprojects.com/en/stable/advanced/#callback-evaluation-order 

95 """ 

96 

97 def sort_key(item: Parameter) -> tuple[bool, float]: 7 ctx1aecfbdg

98 try: 7 ctx1aecfbdg

99 idx: float = invocation_order.index(item) 7 ctx1aecfbdg

100 except ValueError: 7 ctx1aecfbdg

101 idx = float("inf") 7 ctx1aecfbdg

102 

103 return not item.is_eager, idx 7 ctx1aecfbdg

104 

105 return sorted(declaration_order, key=sort_key) 7 ctx1aecfbdg

106 

107 

108class ParameterSource(enum.Enum): 7 ctx1aecfbdg

109 """This is an `Enum` that indicates the source of a 

110 parameter's value. 

111 """ 

112 

113 COMMANDLINE = enum.auto() 7 ctx1aecfbdg

114 """The value was provided by the command line args.""" 7 ctx1aecfbdg

115 ENVIRONMENT = enum.auto() 7 ctx1aecfbdg

116 """The value was provided with an environment variable.""" 7 ctx1aecfbdg

117 DEFAULT = enum.auto() 7 ctx1aecfbdg

118 """Used the default specified by the parameter.""" 7 ctx1aecfbdg

119 DEFAULT_MAP = enum.auto() 7 ctx1aecfbdg

120 """Used a default provided by `Context.default_map`.""" 7 ctx1aecfbdg

121 PROMPT = enum.auto() 7 ctx1aecfbdg

122 """Used a prompt to confirm a default or provide a value.""" 7 ctx1aecfbdg

123 

124 

125class Context: 7 ctx1aecfbdg

126 """The context is a special internal object that holds state relevant 

127 for the script execution at every single level. It's normally invisible 

128 to commands unless they opt-in to getting access to it. 

129 

130 The context is useful as it can pass internal objects around and can 

131 control special execution features such as reading data from 

132 environment variables. 

133 

134 A context can be used as context manager in which case it will call 

135 `close` on teardown. 

136 """ 

137 

138 formatter_class: type[HelpFormatter] = HelpFormatter 7 ctx1aecfbdg

139 

140 def __init__( 7 ctx1aecfbdg

141 self, 

142 command: "Command", 

143 parent: Union["Context", None] = None, 

144 info_name: str | None = None, 

145 obj: Any | None = None, 

146 auto_envvar_prefix: str | None = None, 

147 default_map: MutableMapping[str, Any] | None = None, 

148 terminal_width: int | None = None, 

149 max_content_width: int | None = None, 

150 resilient_parsing: bool = False, 

151 allow_extra_args: bool | None = None, 

152 allow_interspersed_args: bool | None = None, 

153 ignore_unknown_options: bool | None = None, 

154 help_option_names: list[str] | None = None, 

155 token_normalize_func: Callable[[str], str] | None = None, 

156 color: bool | None = None, 

157 show_default: bool | None = None, 

158 ) -> None: 

159 self.parent = parent 7 ctx1aecfbdg

160 self.command = command 7 ctx1aecfbdg

161 self.info_name = info_name 7 ctx1aecfbdg

162 # Map of parameter names to their parsed values. 

163 self.params: dict[str, Any] = {} 7 ctx1aecfbdg

164 # the leftover arguments. 

165 self.args: list[str] = [] 7 ctx1aecfbdg

166 # protected arguments. used to implement nested parsing. 

167 self._protected_args: list[str] = [] 7 ctx1aecfbdg

168 # the collected prefixes of the command's options. 

169 self._opt_prefixes: set[str] = set(parent._opt_prefixes) if parent else set() 7 ctx1aecfbdg

170 

171 if obj is None and parent is not None: 7 ctx1aecfbdg

172 obj = parent.obj 7 ctx1aecfbdg

173 

174 self.obj: Any = obj 7 ctx1aecfbdg

175 self._meta: dict[str, Any] = getattr(parent, "meta", {}) 7 ctx1aecfbdg

176 

177 # A dictionary (-like object) with defaults for parameters. 

178 if ( 

179 default_map is None 

180 and info_name is not None 

181 and parent is not None 

182 and parent.default_map is not None 

183 ): 

184 default_map = parent.default_map.get(info_name) 7 ctx1aecfbdg

185 

186 self.default_map: MutableMapping[str, Any] | None = default_map 7 ctx1aecfbdg

187 

188 # This flag indicates if a subcommand is going to be executed. 

189 self.invoked_subcommand: str | None = None 7 ctx1aecfbdg

190 

191 if terminal_width is None and parent is not None: 7 ctx1aecfbdg

192 terminal_width = parent.terminal_width 7 ctx1aecfbdg

193 

194 # The width of the terminal (None is autodetection). 

195 self.terminal_width: int | None = terminal_width 7 ctx1aecfbdg

196 

197 if max_content_width is None and parent is not None: 7 ctx1aecfbdg

198 max_content_width = parent.max_content_width 7 ctx1aecfbdg

199 

200 self.max_content_width: int | None = max_content_width 7 ctx1aecfbdg

201 

202 if allow_extra_args is None: 7 ctx1aecfbdg

203 allow_extra_args = command.allow_extra_args 7 ctx1aecfbdg

204 

205 self.allow_extra_args = allow_extra_args 7 ctx1aecfbdg

206 

207 if allow_interspersed_args is None: 7 ctx1aecfbdg

208 allow_interspersed_args = command.allow_interspersed_args 7 ctx1aecfbdg

209 

210 self.allow_interspersed_args: bool = allow_interspersed_args 7 ctx1aecfbdg

211 

212 if ignore_unknown_options is None: 7 ctx1aecfbdg

213 ignore_unknown_options = command.ignore_unknown_options 7 ctx1aecfbdg

214 

215 self.ignore_unknown_options: bool = ignore_unknown_options 7 ctx1aecfbdg

216 

217 if help_option_names is None: 7 ctx1aecfbdg

218 if parent is not None: 7 ctx1aecfbdg

219 help_option_names = parent.help_option_names 7 ctx1aecfbdg

220 else: 

221 help_option_names = ["--help"] 7 ctx1aecfbdg

222 

223 self.help_option_names: list[str] = help_option_names 7 ctx1aecfbdg

224 

225 if token_normalize_func is None and parent is not None: 7 ctx1aecfbdg

226 token_normalize_func = parent.token_normalize_func 7 ctx1aecfbdg

227 

228 # An optional normalization function for tokens. (options, choices, commands etc.) 

229 self.token_normalize_func: Callable[[str], str] | None = token_normalize_func 7 ctx1aecfbdg

230 

231 # Indicates if resilient parsing is enabled. 

232 self.resilient_parsing: bool = resilient_parsing 7 ctx1aecfbdg

233 

234 # If there is no envvar prefix yet, but the parent has one and 

235 # the command on this level has a name, we can expand the envvar 

236 # prefix automatically. 

237 if auto_envvar_prefix is None: 7 ctx1aecfbdg

238 if ( 

239 parent is not None 

240 and parent.auto_envvar_prefix is not None 

241 and self.info_name is not None 

242 ): 

243 auto_envvar_prefix = ( 7 ctx1aecfbdg

244 f"{parent.auto_envvar_prefix}_{self.info_name.upper()}" 

245 ) 

246 else: 

247 auto_envvar_prefix = auto_envvar_prefix.upper() 7 ctx1aecfbdg

248 

249 if auto_envvar_prefix is not None: 7 ctx1aecfbdg

250 auto_envvar_prefix = auto_envvar_prefix.replace("-", "_") 7 ctx1aecfbdg

251 

252 self.auto_envvar_prefix: str | None = auto_envvar_prefix 7 ctx1aecfbdg

253 

254 if color is None and parent is not None: 7 ctx1aecfbdg

255 color = parent.color 7 ctx1aecfbdg

256 

257 # Controls if styling output is wanted or not. 

258 self.color: bool | None = color 7 ctx1aecfbdg

259 

260 if show_default is None and parent is not None: 7 ctx1aecfbdg

261 show_default = parent.show_default 7 ctx1aecfbdg

262 

263 # Show option default values when formatting help text. 

264 self.show_default: bool | None = show_default 7 ctx1aecfbdg

265 

266 self._close_callbacks: list[Callable[[], Any]] = [] 7 ctx1aecfbdg

267 self._depth = 0 7 ctx1aecfbdg

268 self._parameter_source: dict[str, ParameterSource] = {} 7 ctx1aecfbdg

269 self._exit_stack = ExitStack() 7 ctx1aecfbdg

270 

271 def __enter__(self) -> "Context": 7 ctx1aecfbdg

272 self._depth += 1 7 ctx1aecfbdg

273 push_context(self) 7 ctx1aecfbdg

274 return self 7 ctx1aecfbdg

275 

276 def __exit__( 7 ctx1aecfbdg

277 self, 

278 exc_type: type[BaseException] | None, 

279 exc_value: BaseException | None, 

280 tb: TracebackType | None, 

281 ) -> bool | None: 

282 self._depth -= 1 7 ctx1aecfbdg

283 exit_result: bool | None = None 7 ctx1aecfbdg

284 if self._depth == 0: 7 ctx1aecfbdg

285 exit_result = self._close_with_exception_info(exc_type, exc_value, tb) 7 ctx1aecfbdg

286 pop_context() 7 ctx1aecfbdg

287 

288 return exit_result 7 ctx1aecfbdg

289 

290 @contextmanager 7 ctx1aecfbdg

291 def scope(self, cleanup: bool = True) -> Generator["Context"]: 7 ctx1aecfbdg

292 """This helper method can be used with the context object to promote 

293 it to the current thread local (see `get_current_context`). 

294 The default behavior of this is to invoke the cleanup functions which 

295 can be disabled by setting `cleanup` to `False`. The cleanup 

296 functions are typically used for things such as closing file handles. 

297 

298 If the cleanup is intended the context object can also be directly 

299 used as a context manager. 

300 """ 

301 if not cleanup: 7 ctx1aecfbdg

302 self._depth += 1 7 ctx1aecfbdg

303 try: 7 ctx1aecfbdg

304 with self as rv: 7 ctx1aecfbdg

305 yield rv 7 ctx1aecfbdg

306 finally: 

307 if not cleanup: 7 ctx1aecfbdg

308 self._depth -= 1 7 ctx1aecfbdg

309 

310 @property 7 ctx1aecfbdg

311 def meta(self) -> dict[str, Any]: 7 ctx1aecfbdg

312 """This is a dictionary which is shared with all the contexts 

313 that are nested. It exists so that click utilities can store some 

314 state here if they need to. It is however the responsibility of 

315 that code to manage this dictionary well. 

316 

317 The keys are supposed to be unique dotted strings. For instance 

318 module paths are a good choice for it. What is stored in there is 

319 irrelevant for the operation of click. However what is important is 

320 that code that places data here adheres to the general semantics of 

321 the system. 

322 """ 

323 return self._meta 7 ctx1aecfbdg

324 

325 def make_formatter(self) -> HelpFormatter: 7 ctx1aecfbdg

326 """Creates the HelpFormatter for the help and 

327 usage output. 

328 """ 

329 return self.formatter_class( 7 ctx1aecfbdg

330 width=self.terminal_width, max_width=self.max_content_width 

331 ) 

332 

333 def with_resource(self, context_manager: AbstractContextManager[V]) -> V: 7 ctx1aecfbdg

334 """Register a resource as if it were used in a ``with`` 

335 statement. The resource will be cleaned up when the context is 

336 popped. 

337 

338 Uses `contextlib.ExitStack.enter_context`. It calls the 

339 resource's ``__enter__()`` method and returns the result. When 

340 the context is popped, it closes the stack, which calls the 

341 resource's ``__exit__()`` method. 

342 

343 To register a cleanup function for something that isn't a 

344 context manager, use `call_on_close`. Or use something 

345 from `contextlib` to turn it into a context manager first. 

346 """ 

347 return self._exit_stack.enter_context(context_manager) 7 ctx1aecfbdg

348 

349 def call_on_close(self, f: Callable[..., Any]) -> Callable[..., Any]: 7 ctx1aecfbdg

350 """Register a function to be called when the context tears down. 

351 

352 This can be used to close resources opened during the script 

353 execution. Resources that support Python's context manager 

354 protocol which would be used in a ``with`` statement should be 

355 registered with `with_resource` instead. 

356 """ 

357 return self._exit_stack.callback(f) 7 ctx1aecfbdg

358 

359 def close(self) -> None: 7 ctx1aecfbdg

360 """Invoke all close callbacks registered with `call_on_close`, 

361 and exit all context managers entered with `with_resource`. 

362 """ 

363 self._close_with_exception_info(None, None, None) 7 ctx1aecfbdg

364 

365 def _close_with_exception_info( 7 ctx1aecfbdg

366 self, 

367 exc_type: type[BaseException] | None, 

368 exc_value: BaseException | None, 

369 tb: TracebackType | None, 

370 ) -> bool | None: 

371 """Unwind the exit stack by calling its `__exit__` providing the exception 

372 information to allow for exception handling by the various resources registered 

373 using `with_resource` 

374 """ 

375 exit_result = self._exit_stack.__exit__(exc_type, exc_value, tb) 7 ctx1aecfbdg

376 # In case the context is reused, create a new exit stack. 

377 self._exit_stack = ExitStack() 7 ctx1aecfbdg

378 

379 return exit_result 7 ctx1aecfbdg

380 

381 @property 7 ctx1aecfbdg

382 def command_path(self) -> str: 7 ctx1aecfbdg

383 """The computed command path. This is used for the ``usage`` 

384 information on the help page. It's automatically created by 

385 combining the info names of the chain of contexts to the root. 

386 """ 

387 rv = "" 7 ctx1aecfbdg

388 if self.info_name is not None: 7 ctx1aecfbdg

389 rv = self.info_name 7 ctx1aecfbdg

390 if self.parent is not None: 7 ctx1aecfbdg

391 parent_command_path = [self.parent.command_path] 7 ctx1aecfbdg

392 

393 if isinstance(self.parent.command, Command): 7 ctx1aecfbdg

394 for param in self.parent.command.get_params(self): 7 ctx1aecfbdg

395 parent_command_path.extend(param.get_usage_pieces(self)) 7 ctx1aecfbdg

396 

397 rv = f"{' '.join(parent_command_path)} {rv}" 7 ctx1aecfbdg

398 return rv.lstrip() 7 ctx1aecfbdg

399 

400 def find_root(self) -> "Context": 7 ctx1aecfbdg

401 """Finds the outermost context.""" 

402 node = self 7 ctx1aecfbdg

403 while node.parent is not None: 7 ctx1aecfbdg

404 node = node.parent 7 ctx1aecfbdg

405 return node 7 ctx1aecfbdg

406 

407 def find_object(self, object_type: type[V]) -> V | None: 7 ctx1aecfbdg

408 """Finds the closest object of a given type.""" 

409 node: Context | None = self 7 ctx1aecfbdg

410 

411 while node is not None: 7 ctx1aecfbdg

412 if isinstance(node.obj, object_type): 7 ctx1aecfbdg

413 return node.obj 7 ctx1aecfbdg

414 

415 node = node.parent 7 ctx1aecfbdg

416 

417 return None 7 ctx1aecfbdg

418 

419 def ensure_object(self, object_type: type[V]) -> V: 7 ctx1aecfbdg

420 """Like `find_object` but sets the innermost object to a 

421 new instance of `object_type` if it does not exist. 

422 """ 

423 rv = self.find_object(object_type) 7 ctx1aecfbdg

424 if rv is None: 7 ctx1aecfbdg

425 self.obj = rv = object_type() 7 ctx1aecfbdg

426 return rv 7 ctx1aecfbdg

427 

428 @overload 7 ctx1aecfbdg

429 def lookup_default(self, name: str, call: Literal[True] = True) -> Any | None: ... 7 ctx1aecfbdg

430 

431 @overload 7 ctx1aecfbdg

432 def lookup_default( 7 ctx1aecfbdg

433 self, name: str, call: Literal[False] = ... 4 ctx1acbd

434 ) -> Any | Callable[[], Any] | None: ... 4 ctx1acbd

435 

436 def lookup_default(self, name: str, call: bool = True) -> Any | None: 7 ctx1aecfbdg

437 """Get the default for a parameter from `default_map`.""" 

438 if self.default_map is not None: 7 ctx1aecfbdg

439 value = self.default_map.get(name) 7 ctx1aecfbdg

440 

441 if call and callable(value): 7 ctx1aecfbdg

442 return value() 7 ctx1aecfbdg

443 

444 return value 7 ctx1aecfbdg

445 

446 return None 7 ctx1aecfbdg

447 

448 def fail(self, message: str) -> NoReturn: 7 ctx1aecfbdg

449 """Aborts the execution of the program with a specific error 

450 message. 

451 """ 

452 raise UsageError(message, self) 7 ctx1aecfbdg

453 

454 def abort(self) -> NoReturn: 7 ctx1aecfbdg

455 """Aborts the script.""" 

456 raise Abort() 7 ctx1aecfbdg

457 

458 def exit(self, code: int = 0) -> NoReturn: 7 ctx1aecfbdg

459 """Exits the application with a given exit code.""" 

460 self.close() 7 ctx1aecfbdg

461 raise Exit(code) 7 ctx1aecfbdg

462 

463 def get_usage(self) -> str: 7 ctx1aecfbdg

464 """Helper method to get formatted usage string for the current 

465 context and command. 

466 """ 

467 return self.command.get_usage(self) 7 ctx1aecfbdg

468 

469 def get_help(self) -> str: 7 ctx1aecfbdg

470 """Helper method to get formatted help page for the current 

471 context and command. 

472 """ 

473 return self.command.get_help(self) 7 ctx1aecfbdg

474 

475 def invoke(self, callback: Callable[..., V], /, *args: Any, **kwargs: Any) -> V: 7 ctx1aecfbdg

476 """Invokes a command callback in exactly the way it expects. There 

477 are two ways to invoke this method: 

478 

479 1. the first argument can be a callback and all other arguments and 

480 keyword arguments are forwarded directly to the function. 

481 2. the first argument is a click command object. In that case all 

482 arguments are forwarded as well but proper click parameters 

483 (options and click arguments) must be keyword arguments and Click 

484 will fill in defaults. 

485 """ 

486 ctx = self 7 ctx1aecfbdg

487 

488 with augment_usage_errors(self): 7 ctx1aecfbdg

489 with ctx: 7 ctx1aecfbdg

490 return callback(*args, **kwargs) 7 ctx1aecfbdg

491 

492 def set_parameter_source(self, name: str, source: ParameterSource) -> None: 7 ctx1aecfbdg

493 """Set the source of a parameter. This indicates the location 

494 from which the value of the parameter was obtained. 

495 """ 

496 self._parameter_source[name] = source 7 ctx1aecfbdg

497 

498 def get_parameter_source(self, name: str) -> ParameterSource | None: 7 ctx1aecfbdg

499 """Get the source of a parameter. This indicates the location 

500 from which the value of the parameter was obtained. 

501 

502 This can be useful for determining when a user specified a value 

503 on the command line that is the same as the default value. It 

504 will be `ParameterSource.DEFAULT` only if the 

505 value was actually taken from the default. 

506 """ 

507 return self._parameter_source.get(name) 7 ctx1aecfbdg

508 

509 

510class Command(ABC): 7 ctx1aecfbdg

511 """Commands are the basic building block of command line interfaces in 

512 Click. A basic command handles command line parsing and might dispatch 

513 more parsing to commands nested below it. 

514 """ 

515 

516 context_class: type[Context] = Context 7 ctx1aecfbdg

517 allow_extra_args = False 7 ctx1aecfbdg

518 allow_interspersed_args = True 7 ctx1aecfbdg

519 ignore_unknown_options = False 7 ctx1aecfbdg

520 

521 def __init__( 7 ctx1aecfbdg

522 self, 

523 name: str | None, 

524 context_settings: MutableMapping[str, Any] | None = None, 

525 callback: Callable[..., Any] | None = None, 

526 params: list["Parameter"] | None = None, 

527 help: str | None = None, 

528 epilog: str | None = None, 

529 short_help: str | None = None, 

530 options_metavar: str | None = "[OPTIONS]", 

531 add_help_option: bool = True, 

532 no_args_is_help: bool = False, 

533 hidden: bool = False, 

534 deprecated: bool | str = False, 

535 ) -> None: 

536 self.name = name 7 ctx1aecfbdg

537 

538 if context_settings is None: 7 ctx1aecfbdg

539 context_settings = {} 7 ctx1aecfbdg

540 

541 self.context_settings: MutableMapping[str, Any] = context_settings 7 ctx1aecfbdg

542 

543 self.callback = callback 7 ctx1aecfbdg

544 self.params: list[Parameter] = params or [] 7 ctx1aecfbdg

545 self.help = help 7 ctx1aecfbdg

546 self.epilog = epilog 7 ctx1aecfbdg

547 self.options_metavar = options_metavar 7 ctx1aecfbdg

548 self.short_help = short_help 7 ctx1aecfbdg

549 self.add_help_option = add_help_option 7 ctx1aecfbdg

550 self._help_option: TyperOption | None = None 7 ctx1aecfbdg

551 self.no_args_is_help = no_args_is_help 7 ctx1aecfbdg

552 self.hidden = hidden 7 ctx1aecfbdg

553 self.deprecated = deprecated 7 ctx1aecfbdg

554 

555 def __repr__(self) -> str: 7 ctx1aecfbdg

556 return f"<{self.__class__.__name__} {self.name}>" 7 ctx1aecfbdg

557 

558 def get_usage(self, ctx: Context) -> str: 7 ctx1aecfbdg

559 """Formats the usage line into a string and returns it.""" 

560 formatter = ctx.make_formatter() 7 ctx1aecfbdg

561 self.format_usage(ctx, formatter) 7 ctx1aecfbdg

562 return formatter.getvalue().rstrip("\n") 7 ctx1aecfbdg

563 

564 def get_params(self, ctx: Context) -> list["Parameter"]: 7 ctx1aecfbdg

565 params = self.params 7 ctx1aecfbdg

566 help_option = self.get_help_option(ctx) 7 ctx1aecfbdg

567 

568 if help_option is not None: 7 ctx1aecfbdg

569 params = [*params, help_option] 7 ctx1aecfbdg

570 

571 return params 7 ctx1aecfbdg

572 

573 def format_usage(self, ctx: Context, formatter: HelpFormatter) -> None: 7 ctx1aecfbdg

574 """Writes the usage line into the formatter.""" 

575 pieces = self.collect_usage_pieces(ctx) 7 ctx1aecfbdg

576 formatter.write_usage(ctx.command_path, " ".join(pieces)) 7 ctx1aecfbdg

577 

578 def collect_usage_pieces(self, ctx: Context) -> list[str]: 7 ctx1aecfbdg

579 """Returns all the pieces that go into the usage line and returns 

580 it as a list of strings. 

581 """ 

582 rv = [self.options_metavar] if self.options_metavar else [] 7 ctx1aecfbdg

583 

584 for param in self.get_params(ctx): 7 ctx1aecfbdg

585 rv.extend(param.get_usage_pieces(ctx)) 7 ctx1aecfbdg

586 

587 return rv 7 ctx1aecfbdg

588 

589 def get_help_option_names(self, ctx: Context) -> list[str]: 7 ctx1aecfbdg

590 """Returns the names for the help option.""" 

591 all_names = set(ctx.help_option_names) 7 ctx1aecfbdg

592 for param in self.params: 7 ctx1aecfbdg

593 all_names.difference_update(param.opts) 7 ctx1aecfbdg

594 all_names.difference_update(param.secondary_opts) 7 ctx1aecfbdg

595 return list(all_names) 7 ctx1aecfbdg

596 

597 def get_help_option(self, ctx: Context) -> Union["TyperOption", None]: 7 ctx1aecfbdg

598 """Returns the help option object.""" 

599 help_option_names = self.get_help_option_names(ctx) 7 ctx1aecfbdg

600 

601 if not help_option_names or not self.add_help_option: 7 ctx1aecfbdg

602 return None 7 ctx1aecfbdg

603 

604 # Cache the help option object in private _help_option attribute to 

605 # avoid creating it multiple times. Not doing this will break the 

606 # callback ordering by iter_params_for_processing(), which relies on 

607 # object comparison. 

608 if self._help_option is None: 7 ctx1aecfbdg

609 # Avoid circular import. 

610 from .decorators import help_option 7 ctx1aecfbdg

611 

612 # Apply help_option decorator and pop resulting option 

613 help_option(help_option_names)(self) 7 ctx1aecfbdg

614 self._help_option = cast("TyperOption", self.params.pop()) 7 ctx1aecfbdg

615 

616 return self._help_option 7 ctx1aecfbdg

617 

618 def make_parser(self, ctx: Context) -> _OptionParser: 7 ctx1aecfbdg

619 """Creates the underlying option parser for this command.""" 

620 parser = _OptionParser(ctx) 7 ctx1aecfbdg

621 for param in self.get_params(ctx): 7 ctx1aecfbdg

622 param.add_to_parser(parser, ctx) 7 ctx1aecfbdg

623 return parser 7 ctx1aecfbdg

624 

625 def get_help(self, ctx: Context) -> str: 7 ctx1aecfbdg

626 """Formats the help into a string and returns it.""" 

627 formatter = ctx.make_formatter() 7 ctx1aecfbdg

628 self.format_help(ctx, formatter) 7 ctx1aecfbdg

629 return formatter.getvalue().rstrip("\n") 7 ctx1aecfbdg

630 

631 def get_short_help_str(self, limit: int = 45) -> str: 7 ctx1aecfbdg

632 """Gets short help for the command or makes it by shortening the 

633 long help string. 

634 """ 

635 if self.short_help: 7 ctx1aecfbdg

636 text = inspect.cleandoc(self.short_help) 7 ctx1aecfbdg

637 elif self.help: 7 ctx1aecfbdg

638 text = make_default_short_help(self.help, limit) 7 ctx1aecfbdg

639 else: 

640 text = "" 7 ctx1aecfbdg

641 

642 if self.deprecated: 7 ctx1aecfbdg

643 deprecated_message = ( 7 ctx1aecfbdg

644 f"(DEPRECATED: {self.deprecated})" 

645 if isinstance(self.deprecated, str) 

646 else "(DEPRECATED)" 

647 ) 

648 text = f"{text} {deprecated_message}" 7 ctx1aecfbdg

649 

650 return text.strip() 7 ctx1aecfbdg

651 

652 def format_help(self, ctx: Context, formatter: HelpFormatter) -> None: 7 ctx1aecfbdg

653 """Writes the help into the formatter if it exists.""" 

654 self.format_usage(ctx, formatter) 7 ctx1aecfbdg

655 self.format_help_text(ctx, formatter) 7 ctx1aecfbdg

656 self.format_options(ctx, formatter) 7 ctx1aecfbdg

657 self.format_epilog(ctx, formatter) 7 ctx1aecfbdg

658 

659 def format_help_text(self, ctx: Context, formatter: HelpFormatter) -> None: 7 ctx1aecfbdg

660 """Writes the help text to the formatter if it exists.""" 

661 if self.help is not None: 7 ctx1aecfbdg

662 # truncate the help text to the first form feed 

663 text = inspect.cleandoc(self.help).partition("\f")[0] 7 ctx1aecfbdg

664 else: 

665 text = "" 7 ctx1aecfbdg

666 

667 if self.deprecated: 7 ctx1aecfbdg

668 deprecated_message = ( 7 ctx1aecfbdg

669 f"(DEPRECATED: {self.deprecated})" 

670 if isinstance(self.deprecated, str) 

671 else "(DEPRECATED)" 

672 ) 

673 text = f"{text} {deprecated_message}" 7 ctx1aecfbdg

674 

675 if text: 7 ctx1aecfbdg

676 formatter.write_paragraph() 7 ctx1aecfbdg

677 

678 with formatter.indentation(): 7 ctx1aecfbdg

679 formatter.write_text(text) 7 ctx1aecfbdg

680 

681 @abstractmethod 7 ctx1aecfbdg

682 def format_options(self, ctx: Context, formatter: HelpFormatter) -> None: 7 ctx1aecfbdg

683 pass # pragma: no cover 

684 

685 def format_epilog(self, ctx: Context, formatter: HelpFormatter) -> None: 7 ctx1aecfbdg

686 """Writes the epilog into the formatter if it exists.""" 

687 if self.epilog: 7 ctx1aecfbdg

688 epilog = inspect.cleandoc(self.epilog) 7 ctx1aecfbdg

689 formatter.write_paragraph() 7 ctx1aecfbdg

690 

691 with formatter.indentation(): 7 ctx1aecfbdg

692 formatter.write_text(epilog) 7 ctx1aecfbdg

693 

694 def make_context( 7 ctx1aecfbdg

695 self, 

696 info_name: str | None, 

697 args: list[str], 

698 parent: Context | None = None, 

699 **extra: Any, 

700 ) -> Context: 

701 """This function when given an info name and arguments will kick 

702 off the parsing and create a new `Context`. It does not 

703 invoke the actual command callback though. 

704 

705 To quickly customize the context class used without overriding 

706 this method, set the `context_class` attribute. 

707 """ 

708 for key, value in self.context_settings.items(): 7 ctx1aecfbdg

709 if key not in extra: 7 ctx1aecfbdg

710 extra[key] = value 7 ctx1aecfbdg

711 

712 ctx = self.context_class(self, info_name=info_name, parent=parent, **extra) 7 ctx1aecfbdg

713 

714 with ctx.scope(cleanup=False): 7 ctx1aecfbdg

715 self.parse_args(ctx, args) 7 ctx1aecfbdg

716 return ctx 7 ctx1aecfbdg

717 

718 def parse_args(self, ctx: Context, args: list[str]) -> list[str]: 7 ctx1aecfbdg

719 if not args and self.no_args_is_help and not ctx.resilient_parsing: 7 ctx1aecfbdg

720 raise NoArgsIsHelpError(ctx) # pragma: no cover 

721 

722 parser = self.make_parser(ctx) 7 ctx1aecfbdg

723 opts, args, param_order = parser.parse_args(args=args) 7 ctx1aecfbdg

724 

725 for param in iter_params_for_processing(param_order, self.get_params(ctx)): 7 ctx1aecfbdg

726 _, args = param.handle_parse_result(ctx, opts, args) 7 ctx1aecfbdg

727 

728 if args and not ctx.allow_extra_args and not ctx.resilient_parsing: 7 ctx1aecfbdg

729 extra_args = " ".join(_escape_control_characters(str(arg)) for arg in args) 7 ctx1aecfbdg

730 ctx.fail(f"Got unexpected extra argument(s) ({extra_args})") 7 ctx1aecfbdg

731 

732 ctx.args = args 7 ctx1aecfbdg

733 ctx._opt_prefixes.update(parser._opt_prefixes) 7 ctx1aecfbdg

734 return args 7 ctx1aecfbdg

735 

736 def invoke(self, ctx: Context) -> Any: 7 ctx1aecfbdg

737 """Given a context, this invokes the attached callback (if it exists) 

738 in the right way. 

739 """ 

740 if self.deprecated: 7 ctx1aecfbdg

741 extra_message = ( 7 ctx1aecfbdg

742 f" {self.deprecated}" if isinstance(self.deprecated, str) else "" 

743 ) 

744 message = f"DeprecationWarning: The command {self.name!r} is deprecated.{extra_message}" 7 ctx1aecfbdg

745 echo(style(message, fg="red"), err=True) 7 ctx1aecfbdg

746 

747 if self.callback is not None: 7 ctx1aecfbdg