ヘルプ付きCLIオプション

既に、helpパラメータを使用してCLI引数のヘルプテキストを追加する方法を確認しました。

今度は、CLIオプションについても同様に行いましょう。

Python 3.7+Python 3.7+ 非アノテーション

import typer
from typing_extensions import Annotated


def main(
    name: str,
    lastname: Annotated[str, typer.Option(help="Last name of person to greet.")] = "",
    formal: Annotated[bool, typer.Option(help="Say hi formally.")] = False,
):
    """
    Say hi to NAME, optionally with a --lastname.

    If --formal is used, say hi very formally.
    """
    if formal:
        print(f"Good day Ms. {name} {lastname}.")
    else:
        print(f"Hello {name} {lastname}")


if __name__ == "__main__":
    typer.run(main)

ヒント

可能であれば、Annotatedバージョンを使用することをお勧めします。

import typer


def main(
    name: str,
    lastname: str = typer.Option("", help="Last name of person to greet."),
    formal: bool = typer.Option(False, help="Say hi formally."),
):
    """
    Say hi to NAME, optionally with a --lastname.

    If --formal is used, say hi very formally.
    """
    if formal:
        print(f"Good day Ms. {name} {lastname}.")
    else:
        print(f"Hello {name} {lastname}")


if __name__ == "__main__":
    typer.run(main)

typer.Argument()と同様に、typer.Option()をAnnotatedの中に配置できます。

その後、helpキーワードパラメータを渡すことができます。

lastname: Annotated[str, typer.Option(help="this option does this and that")] = ""

…これにより、そのCLIオプションのヘルプを作成します。

typer.Argument()と同様に、**Typer**は関数パラメータのデフォルト値を使用する従来の方法もサポートしています。

lastname: str = typer.Option(default="", help="this option does this and that")

上記の例をmain.pyファイルにコピーします。

テストします。

$ python main.py --help

Usage: main.py [OPTIONS] NAME

  Say hi to NAME, optionally with a --lastname.

  If --formal is used, say hi very formally.

Arguments:
  NAME  [required]

Options:
  --lastname TEXT         Last name of person to greet. [default: ]
  --formal / --no-formal  Say hi formally.  [default: False]
  --help                  Show this message and exit.

// Now you have a help text for the --lastname and --formal CLI options 🎉

CLIオプションヘルプパネル

CLI引数と同様に、--helpオプションで表示されるように、いくつかのCLIオプションのヘルプを異なるパネルに配置できます。

出力と色のドキュメントで説明されているように、Richをインストール済みの場合、各CLIオプションに使用するパネル名をrich_help_panelパラメータに設定できます。

Python 3.7+Python 3.7+ 非アノテーション

import typer
from typing_extensions import Annotated


def main(
    name: str,
    lastname: Annotated[str, typer.Option(help="Last name of person to greet.")] = "",
    formal: Annotated[
        bool,
        typer.Option(
            help="Say hi formally.", rich_help_panel="Customization and Utils"
        ),
    ] = False,
    debug: Annotated[
        bool,
        typer.Option(
            help="Enable debugging.", rich_help_panel="Customization and Utils"
        ),
    ] = False,
):
    """
    Say hi to NAME, optionally with a --lastname.

    If --formal is used, say hi very formally.
    """
    if formal:
        print(f"Good day Ms. {name} {lastname}.")
    else:
        print(f"Hello {name} {lastname}")


if __name__ == "__main__":
    typer.run(main)

ヒント

可能であれば、Annotatedバージョンを使用することをお勧めします。

import typer


def main(
    name: str,
    lastname: str = typer.Option("", help="Last name of person to greet."),
    formal: bool = typer.Option(
        False, help="Say hi formally.", rich_help_panel="Customization and Utils"
    ),
    debug: bool = typer.Option(
        False, help="Enable debugging.", rich_help_panel="Customization and Utils"
    ),
):
    """
    Say hi to NAME, optionally with a --lastname.

    If --formal is used, say hi very formally.
    """
    if formal:
        print(f"Good day Ms. {name} {lastname}.")
    else:
        print(f"Hello {name} {lastname}")


if __name__ == "__main__":
    typer.run(main)

--helpオプションを確認すると、カスタムrich_help_panelを持たないCLIオプションには「Options」という名前のデフォルトパネルが表示されます。

そして、その下に、rich_help_panelパラメータにカスタムパネルが設定されているCLIオプションの他のパネルが表示されます。

$ python main.py --help

<b> </b><font color="#F4BF75"><b>Usage: </b></font><b>main.py [OPTIONS] NAME                                </b>
<b>                                                                     </b>
 Say hi to NAME, optionally with a <font color="#A1EFE4"><b>--lastname</b></font>.
 If <font color="#6B9F98"><b>--formal</b></font><font color="#A5A5A1"> is used, say hi very formally.                          </font>

<font color="#A5A5A1">╭─ Arguments ───────────────────────────────────────────────────────╮</font>
<font color="#A5A5A1">│ </font><font color="#F92672">*</font>    name      <font color="#F4BF75"><b>TEXT</b></font>  [default: None] <font color="#A6194C">[required]</font>                   │
<font color="#A5A5A1">╰───────────────────────────────────────────────────────────────────╯</font>
<font color="#A5A5A1">╭─ Options ─────────────────────────────────────────────────────────╮</font>
<font color="#A5A5A1">│ </font><font color="#A1EFE4"><b>--lastname</b></font>                  <font color="#F4BF75"><b>TEXT</b></font>  Last name of person to greet.   │
<font color="#A5A5A1">│ </font><font color="#A1EFE4"><b>--help</b></font>                      <font color="#F4BF75"><b>    </b></font>  Show this message and exit.     │
<font color="#A5A5A1">╰───────────────────────────────────────────────────────────────────╯</font>
<font color="#A5A5A1">╭─ Customization and Utils ─────────────────────────────────────────╮</font>
<font color="#A5A5A1">│ </font><font color="#A1EFE4"><b>--formal</b></font>    <font color="#AE81FF"><b>--no-formal</b></font>      Say hi formally.                     │
<font color="#A5A5A1">│                              [default: no-formal]                 │</font>
<font color="#A5A5A1">│ </font><font color="#A1EFE4"><b>--debug</b></font>     <font color="#AE81FF"><b>--no-debug</b></font>       Enable debugging.                    │
<font color="#A5A5A1">│                              [default: no-debug]                  │</font>
<font color="#A5A5A1">╰───────────────────────────────────────────────────────────────────╯</font>

ここでは、「Customization and Utils」という名前のカスタムCLIオプションパネルがあります。

Richを使ったスタイル付きヘルプ

コマンド - コマンドヘルプについて説明している箇所で、CLIオプションのhelpにカスタムマークアップを使用する方法について説明します。

急いでいる場合は、そこにジャンプできますが、そうでない場合は、ここで読み進めてチュートリアルに従う方が良いでしょう。

ヘルプからのデフォルト値の非表示

show_default=Falseを使用して、ヘルプテキストにデフォルト値を表示しないようにTyperに指示できます。

Python 3.7+Python 3.7+ 非アノテーション

import typer
from typing_extensions import Annotated


def main(fullname: Annotated[str, typer.Option(show_default=False)] = "Wade Wilson"):
    print(f"Hello {fullname}")


if __name__ == "__main__":
    typer.run(main)

ヒント

可能であれば、Annotatedバージョンを使用することをお勧めします。

import typer


def main(fullname: str = typer.Option("Wade Wilson", show_default=False)):
    print(f"Hello {fullname}")


if __name__ == "__main__":
    typer.run(main)

そして、ヘルプテキストにはデフォルト値が表示されなくなります。

$ python main.py

Hello Wade Wilson

// Show the help
$ python main.py --help

Usage: main.py [OPTIONS]

Options:
  --fullname TEXT
  --help                Show this message and exit.

// Notice there's no [default: Wade Wilson] 🔥

技術的な詳細

Clickアプリケーションでは、デフォルト値はデフォルトで非表示になっています。🙈

**Typer**では、これらのデフォルト値はデフォルトで表示されます。👀

カスタムデフォルト文字列

同じshow_defaultを使用して、カスタム文字列（ブール値ではなく）を渡し、ヘルプテキストに表示されるデフォルト値をカスタマイズできます。

Python 3.7+Python 3.7+ 非アノテーション

import typer
from typing_extensions import Annotated


def main(
    fullname: Annotated[
        str, typer.Option(show_default="Deadpoolio the amazing's name")
    ] = "Wade Wilson",
):
    print(f"Hello {fullname}")


if __name__ == "__main__":
    typer.run(main)

ヒント

可能であれば、Annotatedバージョンを使用することをお勧めします。

import typer


def main(
    fullname: str = typer.Option(
        "Wade Wilson", show_default="Deadpoolio the amazing's name"
    ),
):
    print(f"Hello {fullname}")


if __name__ == "__main__":
    typer.run(main)

そして、それはヘルプテキストで使用されます。

$ python main.py

Hello Wade Wilson

// Show the help
$ python main.py --help

Usage: main.py [OPTIONS]

Options:
  --fullname TEXT       [default: (Deadpoolio the amazing's name)]
  --help                Show this message and exit.

// Notice how it shows "(Deadpoolio the amazing's name)" instead of the actual default of "Wade Wilson"