Coverage for typer / cli.py: 100%

223 statements  

« prev     ^ index     » next       coverage.py v7.13.1, created at 2026-11-18 11:12 +0000

1import importlib.util 1abcdefghij

2import re 1abcdefghij

3import sys 1abcdefghij

4from pathlib import Path 1abcdefghij

5from typing import Any 1abcdefghij

6 

7import typer 1abcdefghij

8import typer.core 1abcdefghij

9 

10from . import __version__, _click 1abcdefghij

11from ._click import Command 1abcdefghij

12from .core import HAS_RICH, MARKUP_MODE_KEY, TyperGroup, TyperOption 1abcdefghij

13 

14default_app_names = ("app", "cli", "main") 1abcdefghij

15default_func_names = ("main", "cli", "app") 1abcdefghij

16 

17app = typer.Typer() 1abcdefghij

18utils_app = typer.Typer(help="Extra utility commands for Typer apps.") 1abcdefghij

19app.add_typer(utils_app, name="utils") 1abcdefghij

20 

21 

22class State: 1abcdefghij

23 def __init__(self) -> None: 1abcdefghij

24 self.app: str | None = None 1abcdefghij

25 self.func: str | None = None 1abcdefghij

26 self.file: Path | None = None 1abcdefghij

27 self.module: str | None = None 1abcdefghij

28 

29 

30state = State() 1abcdefghij

31 

32 

33def maybe_update_state(ctx: _click.Context) -> None: 1abcdefghij

34 path_or_module = ctx.params.get("path_or_module") 1abcdefghij

35 if path_or_module: 1abcdefghij

36 file_path = Path(path_or_module) 1abcdefghij

37 if file_path.exists() and file_path.is_file(): 1abcdefghij

38 state.file = file_path 1abcdefghij

39 else: 

40 if not re.fullmatch(r"[a-zA-Z_]\w*(\.[a-zA-Z_]\w*)*", path_or_module): 1abcdefghij

41 typer.echo( 1abcdefghij

42 f"Not a valid file or Python module: {path_or_module}", err=True 

43 ) 

44 sys.exit(1) 1abcdefghij

45 state.module = path_or_module 1abcdefghij

46 app_name = ctx.params.get("app") 1abcdefghij

47 if app_name: 1abcdefghij

48 state.app = app_name 1abcdefghij

49 func_name = ctx.params.get("func") 1abcdefghij

50 if func_name: 1abcdefghij

51 state.func = func_name 1abcdefghij

52 

53 

54class TyperCLIGroup(typer.core.TyperGroup): 1abcdefghij

55 def list_commands(self, ctx: _click.Context) -> list[str]: 1abcdefghij

56 self.maybe_add_run(ctx) 1abcdefghij

57 return super().list_commands(ctx) 1abcdefghij

58 

59 def get_command(self, ctx: _click.Context, name: str) -> Command | None: # ty: ignore[invalid-method-override] 1abcdefghij

60 self.maybe_add_run(ctx) 1abcdefghij

61 return super().get_command(ctx, name) 1abcdefghij

62 

63 def invoke(self, ctx: _click.Context) -> Any: 1abcdefghij

64 self.maybe_add_run(ctx) 1abcdefghij

65 return super().invoke(ctx) 1abcdefghij

66 

67 def maybe_add_run(self, ctx: _click.Context) -> None: 1abcdefghij

68 maybe_update_state(ctx) 1abcdefghij

69 maybe_add_run_to_cli(self) 1abcdefghij

70 

71 

72def get_typer_from_module(module: Any) -> typer.Typer | None: 1abcdefghij

73 # Try to get defined app 

74 if state.app: 1abcdefghij

75 obj = getattr(module, state.app, None) 1abcdefghij

76 if not isinstance(obj, typer.Typer): 1abcdefghij

77 typer.echo(f"Not a Typer object: --app {state.app}", err=True) 1abcdefghij

78 sys.exit(1) 1abcdefghij

79 return obj 1abcdefghij

80 # Try to get defined function 

81 if state.func: 1abcdefghij

82 func_obj = getattr(module, state.func, None) 1abcdefghij

83 if not callable(func_obj): 1abcdefghij

84 typer.echo(f"Not a function: --func {state.func}", err=True) 1abcdefghij

85 raise typer.Exit(1) 1abcdefghij

86 sub_app = typer.Typer() 1abcdefghij

87 sub_app.command()(func_obj) 1abcdefghij

88 return sub_app 1abcdefghij

89 # Iterate and get a default object to use as CLI 

90 local_names = dir(module) 1abcdefghij

91 local_names_set = set(local_names) 1abcdefghij

92 # Try to get a default Typer app 

93 for name in default_app_names: 1abcdefghij

94 if name in local_names_set: 1abcdefghij

95 obj = getattr(module, name, None) 1abcdefghij

96 if isinstance(obj, typer.Typer): 1abcdefghij

97 return obj 1abcdefghij

98 # Try to get any Typer app 

99 for name in local_names_set - set(default_app_names): 1abcdefghij

100 obj = getattr(module, name) 1abcdefghij

101 if isinstance(obj, typer.Typer): 1abcdefghij

102 return obj 1abcdefghij

103 # Try to get a default function 

104 for func_name in default_func_names: 1abcdefghij

105 func_obj = getattr(module, func_name, None) 1abcdefghij

106 if callable(func_obj): 1abcdefghij

107 sub_app = typer.Typer() 1abcdefghij

108 sub_app.command()(func_obj) 1abcdefghij

109 return sub_app 1abcdefghij

110 # Try to get any func app 

111 for func_name in local_names_set - set(default_func_names): 1abcdefghij

112 func_obj = getattr(module, func_name) 1abcdefghij

113 if callable(func_obj): 1abcdefghij

114 sub_app = typer.Typer() 1abcdefghij

115 sub_app.command()(func_obj) 1abcdefghij

116 return sub_app 1abcdefghij

117 return None 1abcdefghij

118 

119 

120def get_typer_from_state() -> typer.Typer | None: 1abcdefghij

121 spec = None 1abcdefghij

122 if state.file: 1abcdefghij

123 module_name = state.file.name 1abcdefghij

124 spec = importlib.util.spec_from_file_location(module_name, str(state.file)) 1abcdefghij

125 elif state.module: 1abcdefghij

126 spec = importlib.util.find_spec(state.module) 1abcdefghij

127 if spec is None: 1abcdefghij

128 if state.file: 1abcdefghij

129 typer.echo(f"Could not import as Python file: {state.file}", err=True) 1abcdefghij

130 else: 

131 typer.echo(f"Could not import as Python module: {state.module}", err=True) 1abcdefghij

132 sys.exit(1) 1abcdefghij

133 assert spec is not None 1abcdefghij

134 module = importlib.util.module_from_spec(spec) 1abcdefghij

135 spec.loader.exec_module(module) # type: ignore 1abcdefghij

136 obj = get_typer_from_module(module) 1abcdefghij

137 return obj 1abcdefghij

138 

139 

140def maybe_add_run_to_cli(cli: TyperGroup) -> None: 1abcdefghij

141 if "run" not in cli.commands: 1abcdefghij

142 if state.file or state.module: 1abcdefghij

143 obj = get_typer_from_state() 1abcdefghij

144 if obj: 1abcdefghij

145 obj._add_completion = False 1abcdefghij

146 click_obj = typer.main.get_command(obj) 1abcdefghij

147 click_obj.name = "run" 1abcdefghij

148 if not click_obj.help: 1abcdefghij

149 click_obj.help = "Run the provided Typer app." 1abcdefghij

150 cli.add_command(click_obj) 1abcdefghij

151 

152 

153def print_version(ctx: _click.Context, param: TyperOption, value: bool) -> None: 1abcdefghij

154 if not value or ctx.resilient_parsing: 1abcdefghij

155 return 1abcdefghij

156 typer.echo(f"Typer version: {__version__}") 1abcdefghij

157 raise typer.Exit() 1abcdefghij

158 

159 

160@app.callback(cls=TyperCLIGroup, no_args_is_help=True) 1abcdefghij

161def callback( 1abcdefghij

162 ctx: typer.Context, 

163 *, 

164 path_or_module: str = typer.Argument(None, metavar="PATH_OR_MODULE"), 

165 app: str = typer.Option(None, help="The typer app object/variable to use."), 

166 func: str = typer.Option(None, help="The function to convert to Typer."), 

167 version: bool = typer.Option( 

168 False, 

169 "--version", 

170 help="Print version and exit.", 

171 callback=print_version, 

172 ), 

173) -> None: 

174 """ 

175 Run Typer scripts with completion, without having to create a package. 

176 

177 You probably want to install completion for the typer command: 

178 

179 $ typer --install-completion 

180 

181 https://typer.tiangolo.com/ 

182 """ 

183 maybe_update_state(ctx) 1abcdefghij

184 

185 

186def get_docs_for_click( 1abcdefghij

187 *, 

188 obj: Command, 

189 ctx: typer.Context, 

190 indent: int = 0, 

191 name: str = "", 

192 call_prefix: str = "", 

193 title: str | None = None, 

194) -> str: 

195 docs = "#" * (1 + indent) 1abcdefghij

196 command_name = name or obj.name 1abcdefghij

197 if call_prefix: 1abcdefghij

198 command_name = f"{call_prefix} {command_name}" 1abcdefghij

199 if not title: 1abcdefghij

200 title = f"`{command_name}`" if command_name else "CLI" 1abcdefghij

201 docs += f" {title}\n\n" 1abcdefghij

202 rich_markup_mode = None 1abcdefghij

203 if hasattr(ctx, "obj") and isinstance(ctx.obj, dict): 1abcdefghij

204 rich_markup_mode = ctx.obj.get(MARKUP_MODE_KEY, None) 1abcdefghij

205 to_parse: bool = bool(HAS_RICH and (rich_markup_mode == "rich")) 1abcdefghij

206 if obj.help: 1abcdefghij

207 docs += f"{_parse_html(to_parse, obj.help)}\n\n" 1abcdefghij

208 usage_pieces = obj.collect_usage_pieces(ctx) 1abcdefghij

209 if usage_pieces: 1abcdefghij

210 docs += "**Usage**:\n\n" 1abcdefghij

211 docs += "```console\n" 1abcdefghij

212 docs += "$ " 1abcdefghij

213 if command_name: 1abcdefghij

214 docs += f"{command_name} " 1abcdefghij

215 docs += f"{' '.join(usage_pieces)}\n" 1abcdefghij

216 docs += "```\n\n" 1abcdefghij

217 args = [] 1abcdefghij

218 opts = [] 1abcdefghij

219 for param in obj.get_params(ctx): 1abcdefghij

220 rv = param.get_help_record(ctx) 1abcdefghij

221 if rv is not None: 1abcdefghij

222 if param.param_type_name == "argument": 1abcdefghij

223 args.append(rv) 1abcdefghij

224 elif param.param_type_name == "option": 1abcdefghij

225 opts.append(rv) 1abcdefghij

226 if args: 1abcdefghij

227 docs += "**Arguments**:\n\n" 1abcdefghij

228 for arg_name, arg_help in args: 1abcdefghij

229 docs += f"* `{arg_name}`" 1abcdefghij

230 if arg_help: 1abcdefghij

231 docs += f": {_parse_html(to_parse, arg_help)}" 1abcdefghij

232 docs += "\n" 1abcdefghij

233 docs += "\n" 1abcdefghij

234 if opts: 1abcdefghij

235 docs += "**Options**:\n\n" 1abcdefghij

236 for opt_name, opt_help in opts: 1abcdefghij

237 docs += f"* `{opt_name}`" 1abcdefghij

238 if opt_help: 1abcdefghij

239 docs += f": {_parse_html(to_parse, opt_help)}" 1abcdefghij

240 docs += "\n" 1abcdefghij

241 docs += "\n" 1abcdefghij

242 if obj.epilog: 1abcdefghij

243 docs += f"{obj.epilog}\n\n" 1abcdefghij

244 if isinstance(obj, TyperGroup): 1abcdefghij

245 group = obj 1abcdefghij

246 commands = group.list_commands(ctx) 1abcdefghij

247 if commands: 1abcdefghij

248 docs += "**Commands**:\n\n" 1abcdefghij

249 for command in commands: 1abcdefghij

250 command_obj = group.get_command(ctx, command) 1abcdefghij

251 assert command_obj 1abcdefghij

252 docs += f"* `{command_obj.name}`" 1abcdefghij

253 command_help = command_obj.get_short_help_str() 1abcdefghij

254 if command_help: 1abcdefghij

255 docs += f": {_parse_html(to_parse, command_help)}" 1abcdefghij

256 docs += "\n" 1abcdefghij

257 docs += "\n" 1abcdefghij

258 for command in commands: 1abcdefghij

259 command_obj = group.get_command(ctx, command) 1abcdefghij

260 assert command_obj 1abcdefghij

261 use_prefix = "" 1abcdefghij

262 if command_name: 1abcdefghij

263 use_prefix += f"{command_name}" 1abcdefghij

264 docs += get_docs_for_click( 1abcdefghij

265 obj=command_obj, ctx=ctx, indent=indent + 1, call_prefix=use_prefix 

266 ) 

267 return docs 1abcdefghij

268 

269 

270def _parse_html(to_parse: bool, input_text: str) -> str: 1abcdefghij

271 if not to_parse: 1abcdefghij

272 return input_text 1abcdefghij

273 from . import rich_utils 1abcdefghij

274 

275 return rich_utils.rich_to_html(input_text) 1abcdefghij

276 

277 

278@utils_app.command() 1abcdefghij

279def docs( 1abcdefghij

280 ctx: typer.Context, 

281 name: str = typer.Option("", help="The name of the CLI program to use in docs."), 

282 output: Path | None = typer.Option( 

283 None, 

284 help="An output file to write docs to, like README.md.", 

285 file_okay=True, 

286 dir_okay=False, 

287 ), 

288 title: str | None = typer.Option( 

289 None, 

290 help="The title for the documentation page. If not provided, the name of " 

291 "the program is used.", 

292 ), 

293) -> None: 

294 """ 

295 Generate Markdown docs for a Typer app. 

296 """ 

297 typer_obj = get_typer_from_state() 1abcdefghij

298 if not typer_obj: 1abcdefghij

299 typer.echo("No Typer app found", err=True) 1abcdefghij

300 raise typer.Abort() 1abcdefghij

301 if hasattr(typer_obj, "rich_markup_mode"): 1abcdefghij

302 if not hasattr(ctx, "obj") or ctx.obj is None: 1abcdefghij

303 ctx.ensure_object(dict) 1abcdefghij

304 if isinstance(ctx.obj, dict): 1abcdefghij

305 ctx.obj[MARKUP_MODE_KEY] = typer_obj.rich_markup_mode 1abcdefghij

306 click_obj = typer.main.get_command(typer_obj) 1abcdefghij

307 docs = get_docs_for_click(obj=click_obj, ctx=ctx, name=name, title=title) 1abcdefghij

308 clean_docs = f"{docs.strip()}\n" 1abcdefghij

309 if output: 1abcdefghij

310 output.write_text(clean_docs) 1abcdefghij

311 typer.echo(f"Docs saved to: {output}") 1abcdefghij

312 else: 

313 typer.echo(clean_docs) 1abcdefghij

314 

315 

316def main() -> Any: 1abcdefghij

317 return app() 1abcdefghij