Coverage for typer / cli.py: 100%
223 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 importlib.util 1abcdefghij
2import re 1abcdefghij
3import sys 1abcdefghij
4from pathlib import Path 1abcdefghij
5from typing import Any 1abcdefghij
7import typer 1abcdefghij
8import typer.core 1abcdefghij
10from . import __version__, _click 1abcdefghij
11from ._click import Command 1abcdefghij
12from .core import HAS_RICH, MARKUP_MODE_KEY, TyperGroup, TyperOption 1abcdefghij
14default_app_names = ("app", "cli", "main") 1abcdefghij
15default_func_names = ("main", "cli", "app") 1abcdefghij
17app = typer.Typer() 1abcdefghij
18utils_app = typer.Typer(help="Extra utility commands for Typer apps.") 1abcdefghij
19app.add_typer(utils_app, name="utils") 1abcdefghij
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
30state = State() 1abcdefghij
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
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
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
63 def invoke(self, ctx: _click.Context) -> Any: 1abcdefghij
64 self.maybe_add_run(ctx) 1abcdefghij
65 return super().invoke(ctx) 1abcdefghij
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
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
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
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
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
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.
177 You probably want to install completion for the typer command:
179 $ typer --install-completion
181 https://typer.tiangolo.com/
182 """
183 maybe_update_state(ctx) 1abcdefghij
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
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
275 return rich_utils.rich_to_html(input_text) 1abcdefghij
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
316def main() -> Any: 1abcdefghij
317 return app() 1abcdefghij