ヘルプ付きCLI引数
最初のステップのセクションでは、関数のドキュメント文字列に追加することで、CLIアプリ/コマンドのヘルプを追加する方法を説明しました。
これが最後の例の見た目です
import typer
def main(name: str, lastname: str = "", formal: bool = 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)
typer.Argument()の使い方を理解したので、CLI引数に特化したドキュメントを追加するためにそれを使ってみましょう。
CLI引数のhelpテキストを追加する¶
helpパラメータを使用すると、CLI引数のヘルプテキストを追加できます
import typer
from typing_extensions import Annotated
def main(name: Annotated[str, typer.Argument(help="The name of the user to greet")]):
print(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
ヒント
可能であれば、Annotatedバージョンを使用することを推奨します。
import typer
def main(name: str = typer.Argument(..., help="The name of the user to greet")):
print(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
そして、それは自動--helpオプションで使用されます
$ python main.py --help
// Check the section with Arguments below 🚀
Usage: main.py [OPTIONS] NAME
Arguments:
NAME The name of the user to greet [required]
Options:
--help Show this message and exit.
ヘルプテキストとドキュメント文字列を組み合わせる¶
もちろん、そのhelpをドキュメント文字列と組み合わせることもできます
import typer
from typing_extensions import Annotated
def main(name: Annotated[str, typer.Argument(help="The name of the user to greet")]):
"""
Say hi to NAME very gently, like Dirk.
"""
print(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
ヒント
可能であれば、Annotatedバージョンを使用することを推奨します。
import typer
def main(name: str = typer.Argument(..., help="The name of the user to greet")):
"""
Say hi to NAME very gently, like Dirk.
"""
print(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
そして、--helpオプションはすべての情報を組み合わせます
$ python main.py --help
// Notice that we have the help text from the docstring and also the Arguments 📝
Usage: main.py [OPTIONS] NAME
Say hi to NAME very gently, like Dirk.
Arguments:
NAME The name of the user to greet [required]
Options:
--help Show this message and exit.
デフォルト値付きヘルプ¶
"World"のようなデフォルト値を持つCLI引数がある場合
import typer
from typing_extensions import Annotated
def main(name: Annotated[str, typer.Argument(help="Who to greet")] = "World"):
"""
Say hi to NAME very gently, like Dirk.
"""
print(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
ヒント
可能であれば、Annotatedバージョンを使用することを推奨します。
import typer
def main(name: str = typer.Argument("World", help="Who to greet")):
"""
Say hi to NAME very gently, like Dirk.
"""
print(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
ヘルプテキストにそのデフォルト値が表示されます
$ python main.py --help
// Notice the [default: World] 🔍
Usage: main.py [OPTIONS] [NAME]
Say hi to NAME very gently, like Dirk.
Arguments:
[NAME] Who to greet [default: World]
Options:
--help Show this message and exit.
しかし、show_default=Falseを使用すると、それを無効にすることができます
import typer
from typing_extensions import Annotated
def main(
name: Annotated[
str, typer.Argument(help="Who to greet", show_default=False)
] = "World",
):
"""
Say hi to NAME very gently, like Dirk.
"""
print(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
ヒント
可能であれば、Annotatedバージョンを使用することを推奨します。
import typer
def main(name: str = typer.Argument("World", help="Who to greet", show_default=False)):
"""
Say hi to NAME very gently, like Dirk.
"""
print(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
そして、デフォルト値は表示されません
$ python main.py --help
// Notice the there's no [default: World] now 🔥
Usage: main.py [OPTIONS] [NAME]
Say hi to NAME very gently, like Dirk.
Arguments:
[NAME] Who to greet
Options:
--help Show this message and exit.
技術詳細
Clickアプリケーションでは、デフォルト値はデフォルトで非表示になっています。🙈
Typerでは、これらのデフォルト値はデフォルトで表示されます。👀
カスタムデフォルト文字列¶
同じshow_defaultを使用して（boolの代わりに）カスタム文字列を渡して、ヘルプテキストに表示されるデフォルト値をカスタマイズできます
import typer
from typing_extensions import Annotated
def main(
name: Annotated[
str,
typer.Argument(
help="Who to greet", show_default="Deadpoolio the amazing's name"
),
] = "Wade Wilson",
):
print(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
ヒント
可能であれば、Annotatedバージョンを使用することを推奨します。
import typer
def main(
name: str = typer.Argument(
"Wade Wilson", help="Who to greet", show_default="Deadpoolio the amazing's name"
),
):
print(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
そして、それはヘルプテキストで使用されます
$ python main.py --help
Usage: main.py [OPTIONS] [NAME]
Arguments:
[NAME] Who to greet [default: (Deadpoolio the amazing's name)]
Options:
--help Show this message and exit.
// See it shows "(Deadpoolio the amazing's name)" instead of the actual default of "Wade Wilson"
カスタムヘルプ名（metavar）¶
生成されたヘルプテキストで使用されるテキストをカスタマイズして、CLI引数を表すこともできます。
デフォルトでは、宣言したのと同じ名前で、大文字で表示されます。
したがって、次のように宣言した場合
name: str
次のように表示されます
NAME
しかし、typer.Argument()のmetavarパラメータを使用してカスタマイズできます。
たとえば、デフォルトのNAMEを望まず、小文字のusernameを使用し、✨絵文字✨をどこにでも表示したいとします
import typer
from typing_extensions import Annotated
def main(name: Annotated[str, typer.Argument(metavar="✨username✨")] = "World"):
print(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
ヒント
可能であれば、Annotatedバージョンを使用することを推奨します。
import typer
def main(name: str = typer.Argument("World", metavar="✨username✨")):
print(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
これで、生成されたヘルプテキストはNAMEの代わりに✨username✨になります
$ python main.py --help
Usage: main.py [OPTIONS] ✨username✨
Arguments:
✨username✨ [default: World]
Options:
--help Show this message and exit.
CLI引数ヘルプパネル¶
--helpオプションを使用する場合、異なるパネルにCLI引数のヘルプ情報を表示したい場合があります。
印刷と色のドキュメントで説明されているようにRichをインストールしている場合は、rich_help_panelパラメータを、このCLI引数を表示するパネルの名前に設定できます
import typer
from typing_extensions import Annotated
def main(
name: Annotated[str, typer.Argument(help="Who to greet")],
lastname: Annotated[
str, typer.Argument(help="The last name", rich_help_panel="Secondary Arguments")
] = "",
age: Annotated[
str,
typer.Argument(help="The user's age", rich_help_panel="Secondary Arguments"),
] = "",
):
"""
Say hi to NAME very gently, like Dirk.
"""
print(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
ヒント
可能であれば、Annotatedバージョンを使用することを推奨します。
import typer
def main(
name: str = typer.Argument(..., help="Who to greet"),
lastname: str = typer.Argument(
"", help="The last name", rich_help_panel="Secondary Arguments"
),
age: str = typer.Argument(
"", help="The user's age", rich_help_panel="Secondary Arguments"
),
):
"""
Say hi to NAME very gently, like Dirk.
"""
print(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
次に、--helpオプションを確認すると、カスタムrich_help_panelを持たないCLI引数に対して、「Arguments」という名前のデフォルトのパネルが表示されます。
そして、rich_help_panelパラメータにカスタムパネルが設定されているCLI引数の他のパネルが表示されます
$ python main.py --help
<b> </b><font color="#F4BF75"><b>Usage: </b></font><b>main.py [OPTIONS] NAME [LASTNAME] [AGE] </b>
<b> </b>
Say hi to NAME very gently, like Dirk.
<font color="#A5A5A1">╭─ Arguments ───────────────────────────────────────────────────────╮</font>
<font color="#A5A5A1">│ </font><font color="#F92672">*</font> name <font color="#F4BF75"><b>TEXT</b></font> Who to greet [default: None] <font color="#A6194C">[required]</font> │
<font color="#A5A5A1">╰───────────────────────────────────────────────────────────────────╯</font>
<font color="#A5A5A1">╭─ Secondary Arguments ─────────────────────────────────────────────╮</font>
<font color="#A5A5A1">│ lastname </font><font color="#A37F4E"><b>[LASTNAME]</b></font> The last name │
<font color="#A5A5A1">│ age </font><font color="#A37F4E"><b>[AGE] </b></font> The user's age │
<font color="#A5A5A1">╰───────────────────────────────────────────────────────────────────╯</font>
<font color="#A5A5A1">╭─ Options ─────────────────────────────────────────────────────────╮</font>
<font color="#A5A5A1">│ </font><font color="#A1EFE4"><b>--help</b></font> Show this message and exit. │
<font color="#A5A5A1">╰───────────────────────────────────────────────────────────────────╯</font>
この例では、「Secondary Arguments」という名前のカスタムCLI引数パネルがあります。
Richを使ったスタイル付きヘルプ¶
今後のセクションでは、コマンド - コマンドヘルプについて読むときに、CLI引数のhelpでカスタムマークアップを使用する方法を説明します。
急いでいる場合はそこにジャンプできますが、そうでない場合は、ここに読み進めてチュートリアルに従う方が良いでしょう。
ヘルプテキストからCLI引数を非表示にする¶
必要に応じて、ヘルプテキストのArgumentsセクションにCLI引数を表示しないようにすることができます。
通常はこれを行わないと思いますが、可能です
import typer
from typing_extensions import Annotated
def main(name: Annotated[str, typer.Argument(hidden=True)] = "World"):
"""
Say hi to NAME very gently, like Dirk.
"""
print(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
ヒント
可能であれば、Annotatedバージョンを使用することを推奨します。
import typer
def main(name: str = typer.Argument("World", hidden=True)):
"""
Say hi to NAME very gently, like Dirk.
"""
print(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
確認してください
$ python main.py --help
// Notice there's no Arguments section at all 🔥
Usage: main.py [OPTIONS] [NAME]
Say hi to NAME very gently, like Dirk.
Options:
--help Show this message and exit.
情報
CLI引数は、Usageを含む最初の行には引き続き表示されることに注意してください。
ただし、Argumentsセクションの下のメインヘルプテキストには表示されません。
ClickにおけるCLI引数のヘルプテキスト¶
Click自体はCLI引数のヘルプを追加することをサポートしておらず、上記の例の「Arguments:」セクションのようにヘルプを生成しません。
CLI引数でhelpをサポートしないことは、Clickにおける意図的な設計上の決定です。
これは、最も必要なものにのみ引数を使用し、名前で参照してコマンドヘルプテキストにそれらをドキュメント化するというUnixツールの一般的な慣例に従うためです。
したがって、Clickアプリケーションでは、ドキュメント文字列に手動でCLI引数のすべてのドキュメントを記述することが期待されています。
それにもかかわらず、TyperはCLI引数のhelpをサポートしています。✨ 🤷♂
Typerはその慣例に従わず、代わりにhelpをサポートして、CLIプログラムの一貫したフォーマットで一貫したヘルプテキストを簡単に作成できるようにします。🎨
これは、非常に少ないコードで、✨デフォルトで✨素晴らしいCLIプログラムを作成するのにも役立ちます。
TyperアプリでClickの慣例を維持したい場合は、上記のようにhiddenパラメータを使用することで実現できます。
技術詳細
CLI引数でhelpをサポートするために、TyperはClickの内部クラスの独自のサブクラスで多くの内部作業を行っています。