typer.cli

  1import importlib.util
  2import re
  3import sys
  4from pathlib import Path
  5from typing import Any, List, Optional
  6
  7import click
  8import typer
  9import typer.core
 10from click import Command, Group, Option
 11
 12from . import __version__
 13
 14try:
 15    import rich
 16
 17    has_rich = True
 18    from . import rich_utils
 19
 20except ImportError:  # pragma: no cover
 21    has_rich = False
 22    rich = None  # type: ignore
 23
 24default_app_names = ("app", "cli", "main")
 25default_func_names = ("main", "cli", "app")
 26
 27app = typer.Typer()
 28utils_app = typer.Typer(help="Extra utility commands for Typer apps.")
 29app.add_typer(utils_app, name="utils")
 30
 31
 32class State:
 33    def __init__(self) -> None:
 34        self.app: Optional[str] = None
 35        self.func: Optional[str] = None
 36        self.file: Optional[Path] = None
 37        self.module: Optional[str] = None
 38
 39
 40state = State()
 41
 42
 43def maybe_update_state(ctx: click.Context) -> None:
 44    path_or_module = ctx.params.get("path_or_module")
 45    if path_or_module:
 46        file_path = Path(path_or_module)
 47        if file_path.exists() and file_path.is_file():
 48            state.file = file_path
 49        else:
 50            if not re.fullmatch(r"[a-zA-Z_]\w*(\.[a-zA-Z_]\w*)*", path_or_module):
 51                typer.echo(
 52                    f"Not a valid file or Python module: {path_or_module}", err=True
 53                )
 54                sys.exit(1)
 55            state.module = path_or_module
 56    app_name = ctx.params.get("app")
 57    if app_name:
 58        state.app = app_name
 59    func_name = ctx.params.get("func")
 60    if func_name:
 61        state.func = func_name
 62
 63
 64class TyperCLIGroup(typer.core.TyperGroup):
 65    def list_commands(self, ctx: click.Context) -> List[str]:
 66        self.maybe_add_run(ctx)
 67        return super().list_commands(ctx)
 68
 69    def get_command(self, ctx: click.Context, name: str) -> Optional[Command]:
 70        self.maybe_add_run(ctx)
 71        return super().get_command(ctx, name)
 72
 73    def invoke(self, ctx: click.Context) -> Any:
 74        self.maybe_add_run(ctx)
 75        return super().invoke(ctx)
 76
 77    def maybe_add_run(self, ctx: click.Context) -> None:
 78        maybe_update_state(ctx)
 79        maybe_add_run_to_cli(self)
 80
 81
 82def get_typer_from_module(module: Any) -> Optional[typer.Typer]:
 83    # Try to get defined app
 84    if state.app:
 85        obj = getattr(module, state.app, None)
 86        if not isinstance(obj, typer.Typer):
 87            typer.echo(f"Not a Typer object: --app {state.app}", err=True)
 88            sys.exit(1)
 89        return obj
 90    # Try to get defined function
 91    if state.func:
 92        func_obj = getattr(module, state.func, None)
 93        if not callable(func_obj):
 94            typer.echo(f"Not a function: --func {state.func}", err=True)
 95            sys.exit(1)
 96        sub_app = typer.Typer()
 97        sub_app.command()(func_obj)
 98        return sub_app
 99    # Iterate and get a default object to use as CLI
100    local_names = dir(module)
101    local_names_set = set(local_names)
102    # Try to get a default Typer app
103    for name in default_app_names:
104        if name in local_names_set:
105            obj = getattr(module, name, None)
106            if isinstance(obj, typer.Typer):
107                return obj
108    # Try to get any Typer app
109    for name in local_names_set - set(default_app_names):
110        obj = getattr(module, name)
111        if isinstance(obj, typer.Typer):
112            return obj
113    # Try to get a default function
114    for func_name in default_func_names:
115        func_obj = getattr(module, func_name, None)
116        if callable(func_obj):
117            sub_app = typer.Typer()
118            sub_app.command()(func_obj)
119            return sub_app
120    # Try to get any func app
121    for func_name in local_names_set - set(default_func_names):
122        func_obj = getattr(module, func_name)
123        if callable(func_obj):
124            sub_app = typer.Typer()
125            sub_app.command()(func_obj)
126            return sub_app
127    return None
128
129
130def get_typer_from_state() -> Optional[typer.Typer]:
131    spec = None
132    if state.file:
133        module_name = state.file.name
134        spec = importlib.util.spec_from_file_location(module_name, str(state.file))
135    elif state.module:
136        spec = importlib.util.find_spec(state.module)
137    if spec is None:
138        if state.file:
139            typer.echo(f"Could not import as Python file: {state.file}", err=True)
140        else:
141            typer.echo(f"Could not import as Python module: {state.module}", err=True)
142        sys.exit(1)
143    module = importlib.util.module_from_spec(spec)
144    spec.loader.exec_module(module)  # type: ignore
145    obj = get_typer_from_module(module)
146    return obj
147
148
149def maybe_add_run_to_cli(cli: click.Group) -> None:
150    if "run" not in cli.commands:
151        if state.file or state.module:
152            obj = get_typer_from_state()
153            if obj:
154                obj._add_completion = False
155                click_obj = typer.main.get_command(obj)
156                click_obj.name = "run"
157                if not click_obj.help:
158                    click_obj.help = "Run the provided Typer app."
159                cli.add_command(click_obj)
160
161
162def print_version(ctx: click.Context, param: Option, value: bool) -> None:
163    if not value or ctx.resilient_parsing:
164        return
165    typer.echo(f"Typer version: {__version__}")
166    raise typer.Exit()
167
168
169@app.callback(cls=TyperCLIGroup, no_args_is_help=True)
170def callback(
171    ctx: typer.Context,
172    *,
173    path_or_module: str = typer.Argument(None),
174    app: str = typer.Option(None, help="The typer app object/variable to use."),
175    func: str = typer.Option(None, help="The function to convert to Typer."),
176    version: bool = typer.Option(
177        False,
178        "--version",
179        help="Print version and exit.",
180        callback=print_version,
181    ),
182) -> None:
183    """
184    Run Typer scripts with completion, without having to create a package.
185
186    You probably want to install completion for the typer command:
187
188    $ typer --install-completion
189
190    https://typer.tiangolo.com/
191    """
192    maybe_update_state(ctx)
193
194
195def get_docs_for_click(
196    *,
197    obj: Command,
198    ctx: typer.Context,
199    indent: int = 0,
200    name: str = "",
201    call_prefix: str = "",
202    title: Optional[str] = None,
203) -> str:
204    docs = "#" * (1 + indent)
205    command_name = name or obj.name
206    if call_prefix:
207        command_name = f"{call_prefix} {command_name}"
208    if not title:
209        title = f"`{command_name}`" if command_name else "CLI"
210    docs += f" {title}\n\n"
211    if obj.help:
212        docs += f"{_parse_html(obj.help)}\n\n"
213    usage_pieces = obj.collect_usage_pieces(ctx)
214    if usage_pieces:
215        docs += "**Usage**:\n\n"
216        docs += "```console\n"
217        docs += "$ "
218        if command_name:
219            docs += f"{command_name} "
220        docs += f"{' '.join(usage_pieces)}\n"
221        docs += "```\n\n"
222    args = []
223    opts = []
224    for param in obj.get_params(ctx):
225        rv = param.get_help_record(ctx)
226        if rv is not None:
227            if param.param_type_name == "argument":
228                args.append(rv)
229            elif param.param_type_name == "option":
230                opts.append(rv)
231    if args:
232        docs += "**Arguments**:\n\n"
233        for arg_name, arg_help in args:
234            docs += f"* `{arg_name}`"
235            if arg_help:
236                docs += f": {_parse_html(arg_help)}"
237            docs += "\n"
238        docs += "\n"
239    if opts:
240        docs += "**Options**:\n\n"
241        for opt_name, opt_help in opts:
242            docs += f"* `{opt_name}`"
243            if opt_help:
244                docs += f": {_parse_html(opt_help)}"
245            docs += "\n"
246        docs += "\n"
247    if obj.epilog:
248        docs += f"{obj.epilog}\n\n"
249    if isinstance(obj, Group):
250        group = obj
251        commands = group.list_commands(ctx)
252        if commands:
253            docs += "**Commands**:\n\n"
254            for command in commands:
255                command_obj = group.get_command(ctx, command)
256                assert command_obj
257                docs += f"* `{command_obj.name}`"
258                command_help = command_obj.get_short_help_str()
259                if command_help:
260                    docs += f": {_parse_html(command_help)}"
261                docs += "\n"
262            docs += "\n"
263        for command in commands:
264            command_obj = group.get_command(ctx, command)
265            assert command_obj
266            use_prefix = ""
267            if command_name:
268                use_prefix += f"{command_name}"
269            docs += get_docs_for_click(
270                obj=command_obj, ctx=ctx, indent=indent + 1, call_prefix=use_prefix
271            )
272    return docs
273
274
275def _parse_html(input_text: str) -> str:
276    if not has_rich:  # pragma: no cover
277        return input_text
278    return rich_utils.rich_to_html(input_text)
279
280
281@utils_app.command()
282def docs(
283    ctx: typer.Context,
284    name: str = typer.Option("", help="The name of the CLI program to use in docs."),
285    output: Optional[Path] = typer.Option(
286        None,
287        help="An output file to write docs to, like README.md.",
288        file_okay=True,
289        dir_okay=False,
290    ),
291    title: Optional[str] = typer.Option(
292        None,
293        help="The title for the documentation page. If not provided, the name of "
294        "the program is used.",
295    ),
296) -> None:
297    """
298    Generate Markdown docs for a Typer app.
299    """
300    typer_obj = get_typer_from_state()
301    if not typer_obj:
302        typer.echo("No Typer app found", err=True)
303        raise typer.Abort()
304    click_obj = typer.main.get_command(typer_obj)
305    docs = get_docs_for_click(obj=click_obj, ctx=ctx, name=name, title=title)
306    clean_docs = f"{docs.strip()}\n"
307    if output:
308        output.write_text(clean_docs)
309        typer.echo(f"Docs saved to: {output}")
310    else:
311        typer.echo(clean_docs)
312
313
314def main() -> Any:
315    return app()