hexdoc.cli.utils

 118class Typer:
 119    """
 120    `Typer` main class, the main entrypoint to use Typer.
 121
 122    Read more in the
 123    [Typer docs for First Steps](https://typer.tiangolo.com/tutorial/typer-app/).
 124
 125    ## Example
 126
 127    ```python
 128    import typer
 129
 130    app = typer.Typer()
 131    ```
 132    """
 133
 134    def __init__(
 135        self,
 136        *,
 137        name: Annotated[
 138            Optional[str],
 139            Doc(
 140                """
 141                The name of this application.
 142                Mostly used to set the name for [subcommands](https://typer.tiangolo.com/tutorial/subcommands/), in which case it can be overridden by `add_typer(name=...)`.
 143
 144                **Example**
 145
 146                ```python
 147                import typer
 148
 149                app = typer.Typer(name="users")
 150                ```
 151                """
 152            ),
 153        ] = Default(None),
 154        cls: Annotated[
 155            Optional[type[TyperGroup]],
 156            Doc(
 157                """
 158                The class of this app. Mainly used when [using the Click library underneath](https://typer.tiangolo.com/tutorial/using-click/). Can usually be left at the default value `None`.
 159                Otherwise, should be a subtype of `TyperGroup`.
 160
 161                **Example**
 162
 163                ```python
 164                import typer
 165
 166                app = typer.Typer(cls=TyperGroup)
 167                ```
 168                """
 169            ),
 170        ] = Default(None),
 171        invoke_without_command: Annotated[
 172            bool,
 173            Doc(
 174                """
 175                By setting this to `True`, you can make sure a callback is executed even when no subcommand is provided.
 176
 177                **Example**
 178
 179                ```python
 180                import typer
 181
 182                app = typer.Typer(invoke_without_command=True)
 183                ```
 184                """
 185            ),
 186        ] = Default(False),
 187        no_args_is_help: Annotated[
 188            bool,
 189            Doc(
 190                """
 191                If this is set to `True`, running a command without any arguments will automatically show the help page.
 192
 193                **Example**
 194
 195                ```python
 196                import typer
 197
 198                app = typer.Typer(no_args_is_help=True)
 199                ```
 200                """
 201            ),
 202        ] = Default(False),
 203        subcommand_metavar: Annotated[
 204            Optional[str],
 205            Doc(
 206                """
 207                **Note**: you probably shouldn't use this parameter, it is inherited
 208                from Click and supported for compatibility.
 209
 210                ---
 211
 212                How to represent the subcommand argument in help.
 213                """
 214            ),
 215        ] = Default(None),
 216        chain: Annotated[
 217            bool,
 218            Doc(
 219                """
 220                **Note**: you probably shouldn't use this parameter, it is inherited
 221                from Click and supported for compatibility.
 222
 223                ---
 224
 225                Allow passing more than one subcommand argument.
 226                """
 227            ),
 228        ] = Default(False),
 229        result_callback: Annotated[
 230            Optional[Callable[..., Any]],
 231            Doc(
 232                """
 233                **Note**: you probably shouldn't use this parameter, it is inherited
 234                from Click and supported for compatibility.
 235
 236                ---
 237
 238                A function to call after the group's and subcommand's callbacks.
 239                """
 240            ),
 241        ] = Default(None),
 242        # Command
 243        context_settings: Annotated[
 244            Optional[dict[Any, Any]],
 245            Doc(
 246                """
 247                Pass configurations for the [context](https://typer.tiangolo.com/tutorial/commands/context/).
 248                Available configurations can be found in the docs for Click's `Context` [here](https://click.palletsprojects.com/en/stable/api/#context).
 249
 250                **Example**
 251
 252                ```python
 253                import typer
 254
 255                app = typer.Typer(context_settings={"help_option_names": ["-h", "--help"]})
 256                ```
 257                """
 258            ),
 259        ] = Default(None),
 260        callback: Annotated[
 261            Optional[Callable[..., Any]],
 262            Doc(
 263                """
 264                Add a callback to the main Typer app. Can be overridden with `@app.callback()`.
 265                See [the tutorial about callbacks](https://typer.tiangolo.com/tutorial/commands/callback/) for more details.
 266
 267                **Example**
 268
 269                ```python
 270                import typer
 271
 272                def callback():
 273                    print("Running a command")
 274
 275                app = typer.Typer(callback=callback)
 276                ```
 277                """
 278            ),
 279        ] = Default(None),
 280        help: Annotated[
 281            Optional[str],
 282            Doc(
 283                """
 284                Help text for the main Typer app.
 285                See [the tutorial about name and help](https://typer.tiangolo.com/tutorial/subcommands/name-and-help) for different ways of setting a command's help,
 286                and which one takes priority.
 287
 288                **Example**
 289
 290                ```python
 291                import typer
 292
 293                app = typer.Typer(help="Some help.")
 294                ```
 295                """
 296            ),
 297        ] = Default(None),
 298        epilog: Annotated[
 299            Optional[str],
 300            Doc(
 301                """
 302                Text that will be printed right after the help text.
 303
 304                **Example**
 305
 306                ```python
 307                import typer
 308
 309                app = typer.Typer(epilog="May the force be with you")
 310                ```
 311                """
 312            ),
 313        ] = Default(None),
 314        short_help: Annotated[
 315            Optional[str],
 316            Doc(
 317                """
 318                A shortened version of the help text that can be used e.g. in the help table listing subcommands.
 319                When not defined, the normal `help` text will be used instead.
 320
 321                **Example**
 322
 323                ```python
 324                import typer
 325
 326                app = typer.Typer(help="A lot of explanation about user management", short_help="user management")
 327                ```
 328                """
 329            ),
 330        ] = Default(None),
 331        options_metavar: Annotated[
 332            str,
 333            Doc(
 334                """
 335                In the example usage string of the help text for a command, the default placeholder for various arguments is `[OPTIONS]`.
 336                Set `options_metavar` to change this into a different string.
 337
 338                **Example**
 339
 340                ```python
 341                import typer
 342
 343                app = typer.Typer(options_metavar="[OPTS]")
 344                ```
 345                """
 346            ),
 347        ] = Default("[OPTIONS]"),
 348        add_help_option: Annotated[
 349            bool,
 350            Doc(
 351                """
 352                **Note**: you probably shouldn't use this parameter, it is inherited
 353                from Click and supported for compatibility.
 354
 355                ---
 356
 357                By default each command registers a `--help` option. This can be disabled by this parameter.
 358                """
 359            ),
 360        ] = Default(True),
 361        hidden: Annotated[
 362            bool,
 363            Doc(
 364                """
 365                Hide this command from help outputs. `False` by default.
 366
 367                **Example**
 368
 369                ```python
 370                import typer
 371
 372                app = typer.Typer(hidden=True)
 373                ```
 374                """
 375            ),
 376        ] = Default(False),
 377        deprecated: Annotated[
 378            bool,
 379            Doc(
 380                """
 381                Mark this command as being deprecated in the help text. `False` by default.
 382
 383                **Example**
 384
 385                ```python
 386                import typer
 387
 388                app = typer.Typer(deprecated=True)
 389                ```
 390                """
 391            ),
 392        ] = Default(False),
 393        add_completion: Annotated[
 394            bool,
 395            Doc(
 396                """
 397                Toggle whether or not to add the `--install-completion` and `--show-completion` options to the app.
 398                Set to `True` by default.
 399
 400                **Example**
 401
 402                ```python
 403                import typer
 404
 405                app = typer.Typer(add_completion=False)
 406                ```
 407                """
 408            ),
 409        ] = True,
 410        # Rich settings
 411        rich_markup_mode: Annotated[
 412            MarkupMode,
 413            Doc(
 414                """
 415                Enable markup text if you have Rich installed. This can be set to `"markdown"`, `"rich"`, or `None`.
 416                By default, `rich_markup_mode` is `None` if Rich is not installed, and `"rich"` if it is installed.
 417                See [the tutorial on help formatting](https://typer.tiangolo.com/tutorial/commands/help/#rich-markdown-and-markup) for more information.
 418
 419                **Example**
 420
 421                ```python
 422                import typer
 423
 424                app = typer.Typer(rich_markup_mode="rich")
 425                ```
 426                """
 427            ),
 428        ] = DEFAULT_MARKUP_MODE,
 429        rich_help_panel: Annotated[
 430            Union[str, None],
 431            Doc(
 432                """
 433                Set the panel name of the command when the help is printed with Rich.
 434
 435                **Example**
 436
 437                ```python
 438                import typer
 439
 440                app = typer.Typer(rich_help_panel="Utils and Configs")
 441                ```
 442                """
 443            ),
 444        ] = Default(None),
 445        suggest_commands: Annotated[
 446            bool,
 447            Doc(
 448                """
 449                As of version 0.20.0, Typer provides [support for mistyped command names](https://typer.tiangolo.com/tutorial/commands/help/#suggest-commands) by printing helpful suggestions.
 450                You can turn this setting off with `suggest_commands`:
 451
 452                **Example**
 453
 454                ```python
 455                import typer
 456
 457                app = typer.Typer(suggest_commands=False)
 458                ```
 459                """
 460            ),
 461        ] = True,
 462        pretty_exceptions_enable: Annotated[
 463            bool,
 464            Doc(
 465                """
 466                If you want to disable [pretty exceptions with Rich](https://typer.tiangolo.com/tutorial/exceptions/#exceptions-with-rich),
 467                you can set `pretty_exceptions_enable` to `False`. When doing so, you will see the usual standard exception trace.
 468
 469                **Example**
 470
 471                ```python
 472                import typer
 473
 474                app = typer.Typer(pretty_exceptions_enable=False)
 475                ```
 476                """
 477            ),
 478        ] = True,
 479        pretty_exceptions_show_locals: Annotated[
 480            bool,
 481            Doc(
 482                """
 483                If Rich is installed, [error messages](https://typer.tiangolo.com/tutorial/exceptions/#exceptions-and-errors)
 484                will be nicely printed.
 485
 486                If you set `pretty_exceptions_show_locals=True` it will also include the values of local variables for easy debugging.
 487
 488                However, if such a variable contains delicate information, you should consider leaving `pretty_exceptions_show_locals=False`
 489                (the default) to `False` to enhance security.
 490
 491                **Example**
 492
 493                ```python
 494                import typer
 495
 496                app = typer.Typer(pretty_exceptions_show_locals=True)
 497                ```
 498                """
 499            ),
 500        ] = False,
 501        pretty_exceptions_short: Annotated[
 502            bool,
 503            Doc(
 504                """
 505                By default, [pretty exceptions formatted with Rich](https://typer.tiangolo.com/tutorial/exceptions/#exceptions-with-rich) hide the long stack trace.
 506                If you want to show the full trace instead, you can set the parameter `pretty_exceptions_short` to `False`:
 507
 508                **Example**
 509
 510                ```python
 511                import typer
 512
 513                app = typer.Typer(pretty_exceptions_short=False)
 514                ```
 515                """
 516            ),
 517        ] = True,
 518    ):
 519        self._add_completion = add_completion
 520        self.rich_markup_mode: MarkupMode = rich_markup_mode
 521        self.rich_help_panel = rich_help_panel
 522        self.suggest_commands = suggest_commands
 523        self.pretty_exceptions_enable = pretty_exceptions_enable
 524        self.pretty_exceptions_show_locals = pretty_exceptions_show_locals
 525        self.pretty_exceptions_short = pretty_exceptions_short
 526        self.info = TyperInfo(
 527            name=name,
 528            cls=cls,
 529            invoke_without_command=invoke_without_command,
 530            no_args_is_help=no_args_is_help,
 531            subcommand_metavar=subcommand_metavar,
 532            chain=chain,
 533            result_callback=result_callback,
 534            context_settings=context_settings,
 535            callback=callback,
 536            help=help,
 537            epilog=epilog,
 538            short_help=short_help,
 539            options_metavar=options_metavar,
 540            add_help_option=add_help_option,
 541            hidden=hidden,
 542            deprecated=deprecated,
 543        )
 544        self.registered_groups: list[TyperInfo] = []
 545        self.registered_commands: list[CommandInfo] = []
 546        self.registered_callback: Optional[TyperInfo] = None
 547
 548    def callback(
 549        self,
 550        *,
 551        cls: Annotated[
 552            Optional[type[TyperGroup]],
 553            Doc(
 554                """
 555                The class of this app. Mainly used when [using the Click library underneath](https://typer.tiangolo.com/tutorial/using-click/). Can usually be left at the default value `None`.
 556                Otherwise, should be a subtype of `TyperGroup`.
 557                """
 558            ),
 559        ] = Default(None),
 560        invoke_without_command: Annotated[
 561            bool,
 562            Doc(
 563                """
 564                By setting this to `True`, you can make sure a callback is executed even when no subcommand is provided.
 565                """
 566            ),
 567        ] = Default(False),
 568        no_args_is_help: Annotated[
 569            bool,
 570            Doc(
 571                """
 572                If this is set to `True`, running a command without any arguments will automatically show the help page.
 573                """
 574            ),
 575        ] = Default(False),
 576        subcommand_metavar: Annotated[
 577            Optional[str],
 578            Doc(
 579                """
 580                **Note**: you probably shouldn't use this parameter, it is inherited
 581                from Click and supported for compatibility.
 582
 583                ---
 584
 585                How to represent the subcommand argument in help.
 586                """
 587            ),
 588        ] = Default(None),
 589        chain: Annotated[
 590            bool,
 591            Doc(
 592                """
 593                **Note**: you probably shouldn't use this parameter, it is inherited
 594                from Click and supported for compatibility.
 595
 596                ---
 597
 598                Allow passing more than one subcommand argument.
 599                """
 600            ),
 601        ] = Default(False),
 602        result_callback: Annotated[
 603            Optional[Callable[..., Any]],
 604            Doc(
 605                """
 606                **Note**: you probably shouldn't use this parameter, it is inherited
 607                from Click and supported for compatibility.
 608
 609                ---
 610
 611                A function to call after the group's and subcommand's callbacks.
 612                """
 613            ),
 614        ] = Default(None),
 615        # Command
 616        context_settings: Annotated[
 617            Optional[dict[Any, Any]],
 618            Doc(
 619                """
 620                Pass configurations for the [context](https://typer.tiangolo.com/tutorial/commands/context/).
 621                Available configurations can be found in the docs for Click's `Context` [here](https://click.palletsprojects.com/en/stable/api/#context).
 622                """
 623            ),
 624        ] = Default(None),
 625        help: Annotated[
 626            Optional[str],
 627            Doc(
 628                """
 629                Help text for the command.
 630                See [the tutorial about name and help](https://typer.tiangolo.com/tutorial/subcommands/name-and-help) for different ways of setting a command's help,
 631                and which one takes priority.
 632                """
 633            ),
 634        ] = Default(None),
 635        epilog: Annotated[
 636            Optional[str],
 637            Doc(
 638                """
 639                Text that will be printed right after the help text.
 640                """
 641            ),
 642        ] = Default(None),
 643        short_help: Annotated[
 644            Optional[str],
 645            Doc(
 646                """
 647                A shortened version of the help text that can be used e.g. in the help table listing subcommands.
 648                When not defined, the normal `help` text will be used instead.
 649                """
 650            ),
 651        ] = Default(None),
 652        options_metavar: Annotated[
 653            Optional[str],
 654            Doc(
 655                """
 656                In the example usage string of the help text for a command, the default placeholder for various arguments is `[OPTIONS]`.
 657                Set `options_metavar` to change this into a different string. When `None`, the default value will be used.
 658                """
 659            ),
 660        ] = Default(None),
 661        add_help_option: Annotated[
 662            bool,
 663            Doc(
 664                """
 665                **Note**: you probably shouldn't use this parameter, it is inherited
 666                from Click and supported for compatibility.
 667
 668                ---
 669
 670                By default each command registers a `--help` option. This can be disabled by this parameter.
 671                """
 672            ),
 673        ] = Default(True),
 674        hidden: Annotated[
 675            bool,
 676            Doc(
 677                """
 678                Hide this command from help outputs. `False` by default.
 679                """
 680            ),
 681        ] = Default(False),
 682        deprecated: Annotated[
 683            bool,
 684            Doc(
 685                """
 686                Mark this command as deprecated in the help text. `False` by default.
 687                """
 688            ),
 689        ] = Default(False),
 690        # Rich settings
 691        rich_help_panel: Annotated[
 692            Union[str, None],
 693            Doc(
 694                """
 695                Set the panel name of the command when the help is printed with Rich.
 696                """
 697            ),
 698        ] = Default(None),
 699    ) -> Callable[[CommandFunctionType], CommandFunctionType]:
 700        """
 701        Using the decorator `@app.callback`, you can declare the CLI parameters for the main CLI application.
 702
 703        Read more in the
 704        [Typer docs for Callbacks](https://typer.tiangolo.com/tutorial/commands/callback/).
 705
 706        ## Example
 707
 708        ```python
 709        import typer
 710
 711        app = typer.Typer()
 712        state = {"verbose": False}
 713
 714        @app.callback()
 715        def main(verbose: bool = False):
 716            if verbose:
 717                print("Will write verbose output")
 718                state["verbose"] = True
 719
 720        @app.command()
 721        def delete(username: str):
 722            # define subcommand
 723            ...
 724        ```
 725        """
 726
 727        def decorator(f: CommandFunctionType) -> CommandFunctionType:
 728            self.registered_callback = TyperInfo(
 729                cls=cls,
 730                invoke_without_command=invoke_without_command,
 731                no_args_is_help=no_args_is_help,
 732                subcommand_metavar=subcommand_metavar,
 733                chain=chain,
 734                result_callback=result_callback,
 735                context_settings=context_settings,
 736                callback=f,
 737                help=help,
 738                epilog=epilog,
 739                short_help=short_help,
 740                options_metavar=(
 741                    options_metavar or self._info_val_str("options_metavar")
 742                ),
 743                add_help_option=add_help_option,
 744                hidden=hidden,
 745                deprecated=deprecated,
 746                rich_help_panel=rich_help_panel,
 747            )
 748            return f
 749
 750        return decorator
 751
 752    def command(
 753        self,
 754        name: Annotated[
 755            Optional[str],
 756            Doc(
 757                """
 758                The name of this command.
 759                """
 760            ),
 761        ] = None,
 762        *,
 763        cls: Annotated[
 764            Optional[type[TyperCommand]],
 765            Doc(
 766                """
 767                The class of this command. Mainly used when [using the Click library underneath](https://typer.tiangolo.com/tutorial/using-click/). Can usually be left at the default value `None`.
 768                Otherwise, should be a subtype of `TyperCommand`.
 769                """
 770            ),
 771        ] = None,
 772        context_settings: Annotated[
 773            Optional[dict[Any, Any]],
 774            Doc(
 775                """
 776                Pass configurations for the [context](https://typer.tiangolo.com/tutorial/commands/context/).
 777                Available configurations can be found in the docs for Click's `Context` [here](https://click.palletsprojects.com/en/stable/api/#context).
 778                """
 779            ),
 780        ] = None,
 781        help: Annotated[
 782            Optional[str],
 783            Doc(
 784                """
 785                Help text for the command.
 786                See [the tutorial about name and help](https://typer.tiangolo.com/tutorial/subcommands/name-and-help) for different ways of setting a command's help,
 787                and which one takes priority.
 788                """
 789            ),
 790        ] = None,
 791        epilog: Annotated[
 792            Optional[str],
 793            Doc(
 794                """
 795                Text that will be printed right after the help text.
 796                """
 797            ),
 798        ] = None,
 799        short_help: Annotated[
 800            Optional[str],
 801            Doc(
 802                """
 803                A shortened version of the help text that can be used e.g. in the help table listing subcommands.
 804                When not defined, the normal `help` text will be used instead.
 805                """
 806            ),
 807        ] = None,
 808        options_metavar: Annotated[
 809            Optional[str],
 810            Doc(
 811                """
 812                In the example usage string of the help text for a command, the default placeholder for various arguments is `[OPTIONS]`.
 813                Set `options_metavar` to change this into a different string. When `None`, the default value will be used.
 814                """
 815            ),
 816        ] = Default(None),
 817        add_help_option: Annotated[
 818            bool,
 819            Doc(
 820                """
 821                **Note**: you probably shouldn't use this parameter, it is inherited
 822                from Click and supported for compatibility.
 823
 824                ---
 825
 826                By default each command registers a `--help` option. This can be disabled by this parameter.
 827                """
 828            ),
 829        ] = True,
 830        no_args_is_help: Annotated[
 831            bool,
 832            Doc(
 833                """
 834                If this is set to `True`, running a command without any arguments will automatically show the help page.
 835                """
 836            ),
 837        ] = False,
 838        hidden: Annotated[
 839            bool,
 840            Doc(
 841                """
 842                Hide this command from help outputs. `False` by default.
 843                """
 844            ),
 845        ] = False,
 846        deprecated: Annotated[
 847            bool,
 848            Doc(
 849                """
 850                Mark this command as deprecated in the help outputs. `False` by default.
 851                """
 852            ),
 853        ] = False,
 854        # Rich settings
 855        rich_help_panel: Annotated[
 856            Union[str, None],
 857            Doc(
 858                """
 859                Set the panel name of the command when the help is printed with Rich.
 860                """
 861            ),
 862        ] = Default(None),
 863    ) -> Callable[[CommandFunctionType], CommandFunctionType]:
 864        """
 865        Using the decorator `@app.command`, you can define a subcommand of the previously defined Typer app.
 866
 867        Read more in the
 868        [Typer docs for Commands](https://typer.tiangolo.com/tutorial/commands/).
 869
 870        ## Example
 871
 872        ```python
 873        import typer
 874
 875        app = typer.Typer()
 876
 877        @app.command()
 878        def create():
 879            print("Creating user: Hiro Hamada")
 880
 881        @app.command()
 882        def delete():
 883            print("Deleting user: Hiro Hamada")
 884        ```
 885        """
 886        if cls is None:
 887            cls = TyperCommand
 888
 889        def decorator(f: CommandFunctionType) -> CommandFunctionType:
 890            self.registered_commands.append(
 891                CommandInfo(
 892                    name=name,
 893                    cls=cls,
 894                    context_settings=context_settings,
 895                    callback=f,
 896                    help=help,
 897                    epilog=epilog,
 898                    short_help=short_help,
 899                    options_metavar=(
 900                        options_metavar or self._info_val_str("options_metavar")
 901                    ),
 902                    add_help_option=add_help_option,
 903                    no_args_is_help=no_args_is_help,
 904                    hidden=hidden,
 905                    deprecated=deprecated,
 906                    # Rich settings
 907                    rich_help_panel=rich_help_panel,
 908                )
 909            )
 910            return f
 911
 912        return decorator
 913
 914    def add_typer(
 915        self,
 916        typer_instance: "Typer",
 917        *,
 918        name: Annotated[
 919            Optional[str],
 920            Doc(
 921                """
 922                The name of this subcommand.
 923                See [the tutorial about name and help](https://typer.tiangolo.com/tutorial/subcommands/name-and-help) for different ways of setting a command's name,
 924                and which one takes priority.
 925                """
 926            ),
 927        ] = Default(None),
 928        cls: Annotated[
 929            Optional[type[TyperGroup]],
 930            Doc(
 931                """
 932                The class of this subcommand. Mainly used when [using the Click library underneath](https://typer.tiangolo.com/tutorial/using-click/). Can usually be left at the default value `None`.
 933                Otherwise, should be a subtype of `TyperGroup`.
 934                """
 935            ),
 936        ] = Default(None),
 937        invoke_without_command: Annotated[
 938            bool,
 939            Doc(
 940                """
 941                By setting this to `True`, you can make sure a callback is executed even when no subcommand is provided.
 942                """
 943            ),
 944        ] = Default(False),
 945        no_args_is_help: Annotated[
 946            bool,
 947            Doc(
 948                """
 949                If this is set to `True`, running a command without any arguments will automatically show the help page.
 950                """
 951            ),
 952        ] = Default(False),
 953        subcommand_metavar: Annotated[
 954            Optional[str],
 955            Doc(
 956                """
 957                **Note**: you probably shouldn't use this parameter, it is inherited
 958                from Click and supported for compatibility.
 959
 960                ---
 961
 962                How to represent the subcommand argument in help.
 963                """
 964            ),
 965        ] = Default(None),
 966        chain: Annotated[
 967            bool,
 968            Doc(
 969                """
 970                **Note**: you probably shouldn't use this parameter, it is inherited
 971                from Click and supported for compatibility.
 972
 973                ---
 974
 975                Allow passing more than one subcommand argument.
 976                """
 977            ),
 978        ] = Default(False),
 979        result_callback: Annotated[
 980            Optional[Callable[..., Any]],
 981            Doc(
 982                """
 983                **Note**: you probably shouldn't use this parameter, it is inherited
 984                from Click and supported for compatibility.
 985
 986                ---
 987
 988                A function to call after the group's and subcommand's callbacks.
 989                """
 990            ),
 991        ] = Default(None),
 992        # Command
 993        context_settings: Annotated[
 994            Optional[dict[Any, Any]],
 995            Doc(
 996                """
 997                Pass configurations for the [context](https://typer.tiangolo.com/tutorial/commands/context/).
 998                Available configurations can be found in the docs for Click's `Context` [here](https://click.palletsprojects.com/en/stable/api/#context).
 999                """
1000            ),
1001        ] = Default(None),
1002        callback: Annotated[
1003            Optional[Callable[..., Any]],
1004            Doc(
1005                """
1006                Add a callback to this app.
1007                See [the tutorial about callbacks](https://typer.tiangolo.com/tutorial/commands/callback/) for more details.
1008                """
1009            ),
1010        ] = Default(None),
1011        help: Annotated[
1012            Optional[str],
1013            Doc(
1014                """
1015                Help text for the subcommand.
1016                See [the tutorial about name and help](https://typer.tiangolo.com/tutorial/subcommands/name-and-help) for different ways of setting a command's help,
1017                and which one takes priority.
1018                """
1019            ),
1020        ] = Default(None),
1021        epilog: Annotated[
1022            Optional[str],
1023            Doc(
1024                """
1025                Text that will be printed right after the help text.
1026                """
1027            ),
1028        ] = Default(None),
1029        short_help: Annotated[
1030            Optional[str],
1031            Doc(
1032                """
1033                A shortened version of the help text that can be used e.g. in the help table listing subcommands.
1034                When not defined, the normal `help` text will be used instead.
1035                """
1036            ),
1037        ] = Default(None),
1038        options_metavar: Annotated[
1039            Optional[str],
1040            Doc(
1041                """
1042                In the example usage string of the help text for a command, the default placeholder for various arguments is `[OPTIONS]`.
1043                Set `options_metavar` to change this into a different string. When `None`, the default value will be used.
1044                """
1045            ),
1046        ] = Default(None),
1047        add_help_option: Annotated[
1048            bool,
1049            Doc(
1050                """
1051                **Note**: you probably shouldn't use this parameter, it is inherited
1052                from Click and supported for compatibility.
1053
1054                ---
1055
1056                By default each command registers a `--help` option. This can be disabled by this parameter.
1057                """
1058            ),
1059        ] = Default(True),
1060        hidden: Annotated[
1061            bool,
1062            Doc(
1063                """
1064                Hide this command from help outputs. `False` by default.
1065                """
1066            ),
1067        ] = Default(False),
1068        deprecated: Annotated[
1069            bool,
1070            Doc(
1071                """
1072                Mark this command as deprecated in the help outputs. `False` by default.
1073                """
1074            ),
1075        ] = False,
1076        # Rich settings
1077        rich_help_panel: Annotated[
1078            Union[str, None],
1079            Doc(
1080                """
1081                Set the panel name of the command when the help is printed with Rich.
1082                """
1083            ),
1084        ] = Default(None),
1085    ) -> None:
1086        """
1087        Add subcommands to the main app using `app.add_typer()`.
1088        Subcommands may be defined in separate modules, ensuring clean separation of code by functionality.
1089
1090        Read more in the
1091        [Typer docs for SubCommands](https://typer.tiangolo.com/tutorial/subcommands/add-typer/).
1092
1093        ## Example
1094
1095        ```python
1096        import typer
1097
1098        from .add import app as add_app
1099        from .delete import app as delete_app
1100
1101        app = typer.Typer()
1102
1103        app.add_typer(add_app)
1104        app.add_typer(delete_app)
1105        ```
1106        """
1107        self.registered_groups.append(
1108            TyperInfo(
1109                typer_instance,
1110                name=name,
1111                cls=cls,
1112                invoke_without_command=invoke_without_command,
1113                no_args_is_help=no_args_is_help,
1114                subcommand_metavar=subcommand_metavar,
1115                chain=chain,
1116                result_callback=result_callback,
1117                context_settings=context_settings,
1118                callback=callback,
1119                help=help,
1120                epilog=epilog,
1121                short_help=short_help,
1122                options_metavar=(
1123                    options_metavar or self._info_val_str("options_metavar")
1124                ),
1125                add_help_option=add_help_option,
1126                hidden=hidden,
1127                deprecated=deprecated,
1128                rich_help_panel=rich_help_panel,
1129            )
1130        )
1131
1132    def __call__(self, *args: Any, **kwargs: Any) -> Any:
1133        if sys.excepthook != except_hook:
1134            sys.excepthook = except_hook
1135        try:
1136            return get_command(self)(*args, **kwargs)
1137        except Exception as e:
1138            # Set a custom attribute to tell the hook to show nice exceptions for user
1139            # code. An alternative/first implementation was a custom exception with
1140            # raise custom_exc from e
1141            # but that means the last error shown is the custom exception, not the
1142            # actual error. This trick improves developer experience by showing the
1143            # actual error last.
1144            setattr(
1145                e,
1146                _typer_developer_exception_attr_name,
1147                DeveloperExceptionConfig(
1148                    pretty_exceptions_enable=self.pretty_exceptions_enable,
1149                    pretty_exceptions_show_locals=self.pretty_exceptions_show_locals,
1150                    pretty_exceptions_short=self.pretty_exceptions_short,
1151                ),
1152            )
1153            raise e
1154
1155    def _info_val_str(self, name: str) -> str:
1156        val = getattr(self.info, name)
1157        val_str = val.value if isinstance(val, DefaultPlaceholder) else val
1158        assert isinstance(val_str, str)
1159        return val_str

117def init_context(
118    *,
119    book_id: ResourceLocation,
120    book_data: dict[str, Any],
121    pm: PluginManager,
122    loader: ModResourceLoader,
123    i18n: I18n,
124    all_metadata: dict[str, HexdocMetadata],
125):
126    props = loader.props
127
128    context = dict[str, Any]()
129
130    for item in [
131        props,
132        pm,
133        loader,
134        i18n,
135        TextureContext(
136            textures=load_metadata_textures(all_metadata),
137            allowed_missing_textures=props.textures.missing,
138        ),
139        FormattingContext(
140            book_id=book_id,
141            macros=DEFAULT_MACROS | book_data.get("macros", {}) | props.macros,
142        ),
143        BookContext(
144            modid=props.modid,
145            book_id=book_id,
146            spoilered_advancements=Tag.SPOILERED_ADVANCEMENTS.load(
147                loader
148            ).value_ids_set,
149            all_metadata=all_metadata,
150            flags=pm.load_flags(),
151        ),
152    ]:
153        item.add_to_context(context)
154
155    for item in pm.update_context(context):
156        item.add_to_context(context)
157
158    return context

50def load_common_data(
51    props_file: Path,
52    branch: str,
53    *,
54    book: bool = False,
55) -> tuple[Properties, PluginManager, BookPlugin[Any], ModPlugin]:
56    props = Properties.load(props_file)
57    pm = PluginManager(branch, props)
58
59    book_plugin = pm.book_plugin(props.book_type)
60    mod_plugin = pm.mod_plugin(props.modid, book=book)
61
62    header = get_header(props, pm, mod_plugin)
63    logger.info(f"Loading hexdoc.\n{indent(header, '  ')}")
64
65    minecraft_version = MinecraftVersion.MINECRAFT_VERSION = pm.minecraft_version()
66    if minecraft_version is None:
67        logger.warning(
68            "No plugins implement minecraft_version. All versions may be used."
69        )
70
71    return props, pm, book_plugin, mod_plugin

 74def render_textures_and_export_metadata(
 75    loader: ModResourceLoader,
 76    asset_loader: HexdocAssetLoader,
 77):
 78    all_metadata = loader.load_metadata(model_type=HexdocMetadata)
 79
 80    all_lookups = load_metadata_textures(all_metadata)
 81    image_textures = {
 82        id: texture
 83        for texture_type in [PNGTexture, AnimatedTexture]
 84        for id, texture in texture_type.get_lookup(all_lookups).items()
 85    }
 86
 87    internal_lookups = TextureLookups[Texture](dict)
 88    if loader.props.textures.enabled:
 89        logger.info(f"Loading and rendering textures to {asset_loader.render_dir}.")
 90        for id, texture in asset_loader.load_and_render_internal_textures(
 91            image_textures
 92        ):
 93            texture.insert_texture(internal_lookups, id)
 94
 95    # this mod's metadata
 96    metadata = HexdocMetadata(
 97        book_url=asset_loader.site_url / loader.props.default_lang,
 98        asset_url=loader.props.env.asset_url,
 99        textures=internal_lookups,
100    )
101
102    loader.export(
103        metadata.path(loader.props.modid),
104        metadata.model_dump_json(
105            by_alias=True,
106            warnings=False,
107            exclude_defaults=True,
108            round_trip=True,
109        ),
110        cache=True,
111    )
112
113    return all_metadata | {loader.props.modid: metadata}