help 付き CLI 引数¶
First Steps セクションでは、関数の docstring に書くことで、CLI アプリやコマンドの help を追加する方法を見ました。
その最後の例は次のようなものでした。
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 引数 に help テキストを追加できます。
from typing import Annotated
import typer
app = typer.Typer()
@app.command()
def main(name: Annotated[str, typer.Argument(help="The name of the user to greet")]):
print(f"Hello {name}")
if __name__ == "__main__":
app()
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
import typer
app = typer.Typer()
@app.command()
def main(name: str = typer.Argument(..., help="The name of the user to greet")):
print(f"Hello {name}")
if __name__ == "__main__":
app()
すると、自動生成される --help オプションで使われます。
$ python main.py --help
// 下の Arguments セクションを見てください 🚀
Usage: main.py [OPTIONS] NAME
Arguments:
NAME The name of the user to greet [required]
Options:
--help Show this message and exit.
help テキストと docstring を組み合わせる¶
もちろん、この help は docstring と組み合わせることもできます。
from typing import Annotated
import typer
app = typer.Typer()
@app.command()
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__":
app()
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
import typer
app = typer.Typer()
@app.command()
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__":
app()
--help オプションには、すべての情報がまとめて表示されます。
$ python main.py --help
// docstring の help テキストと 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.
デフォルト値の help¶
"World" のように、CLI 引数 にデフォルト値がある場合:
from typing import Annotated
import typer
app = typer.Typer()
@app.command()
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__":
app()
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
import typer
app = typer.Typer()
@app.command()
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__":
app()
そのデフォルト値が help テキストに表示されます。
$ python main.py --help
// [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 を使えば、これを無効にできます。
from typing import Annotated
import typer
app = typer.Typer()
@app.command()
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__":
app()
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
import typer
app = typer.Typer()
@app.command()
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__":
app()
すると、デフォルト値は表示されません。
$ python main.py --help
// 今は [default: World] がないことに注目してください 🔥
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.
カスタムデフォルト文字列¶
同じ show_default で bool の代わりに独自の文字列を渡すと、help テキストに表示するデフォルト値をカスタマイズできます。
from typing import Annotated
import typer
app = typer.Typer()
@app.command()
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__":
app()
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
import typer
app = typer.Typer()
@app.command()
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__":
app()
すると、その文字列が help テキストで使われます。
$ 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.
// 実際のデフォルト値 "Wade Wilson" ではなく "(Deadpoolio the amazing's name)" が表示されています
カスタム help 名（metavar）¶
生成される help テキストで CLI 引数 を表す表示名もカスタマイズできます。
デフォルトでは、宣言した名前と同じものが大文字で使われます。
つまり、次のように宣言すると:
name: str
次のように表示されます。
NAME
これを変更したい場合は、typer.Argument() の metavar パラメータを使います。
たとえば、デフォルトの NAME ではなく、小文字の username を使いたいとします。しかも、どこにでも ✨ emojis ✨ を入れたい場合:
from typing import Annotated
import typer
app = typer.Typer()
@app.command()
def main(name: Annotated[str, typer.Argument(metavar="✨username✨")] = "World"):
print(f"Hello {name}")
if __name__ == "__main__":
app()
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
import typer
app = typer.Typer()
@app.command()
def main(name: str = typer.Argument("World", metavar="✨username✨")):
print(f"Hello {name}")
if __name__ == "__main__":
app()
生成される help テキストでは、NAME の代わりに ✨username✨ が表示されます。
$ python main.py --help
Usage: main.py [OPTIONS] [✨username✨]
Arguments:
[✨username✨] [default: World]
Options:
--help Show this message and exit.
CLI 引数 の help パネル¶
--help オプションを使うときに、CLI 引数 の help 情報を別々のパネルに分けて表示したい場合があります。
Printing and Colors のドキュメントで説明したように Rich をインストールしていれば、rich_help_panel パラメータに表示先パネル名を指定できます。
from typing import Annotated
import typer
app = typer.Typer()
@app.command()
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__":
app()
🤓 Other versions and variants
Tip
Prefer to use the Annotated version if possible.
import typer
app = typer.Typer()
@app.command()
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__":
app()
--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 引数 パネルを使っています。