Typer
Typer、素晴らしい CLI を構築しましょう。コーディングが簡単。Python の型ヒントに基づいています。
ドキュメント: https://typer.dokyumento.jp
ソースコード: https://github.com/tiangolo/typer
Typer は、ユーザーが使用を楽しみ、開発者が作成を楽しむ、CLIアプリケーションを構築するためのライブラリです。Python の型ヒントに基づいています。
また、スクリプトを CLI アプリケーションに自動的に変換して実行するためのコマンドラインツールでもあります。
主な機能は次のとおりです。
- 直感的な記述: 優れたエディターサポート。補完があらゆる場所にあります。デバッグ時間の短縮。使いやすく、学習しやすいように設計されています。ドキュメントを読む時間の短縮。
- 使いやすい: エンドユーザーにとって使いやすいです。自動ヘルプと、すべてのシェルでの自動補完。
- 短い: コードの重複を最小限に抑えます。各パラメータ宣言からの複数の機能。バグの減少。
- 単純なスタート: 最も単純な例では、アプリにわずか 2 行のコードを追加します: 1 つの import、1 つの関数呼び出し。
- 大規模に成長: 必要に応じて複雑さを増し、オプションと引数を使用して、コマンドとサブコマンドのグループの任意の複雑なツリーを作成できます。
- スクリプトの実行: Typer には、スクリプトを実行するために使用できる
typerコマンド/プログラムが含まれており、内部で Typer を使用していない場合でも、それらを自動的に CLI に変換します。
CLI の FastAPI¶
Typer は FastAPI の小さな兄弟で、CLI の FastAPI です。
インストール¶
$ pip install typer
---> 100%
Successfully installed typer rich shellingham
例¶
絶対的な最小限¶
main.pyファイルを次のように作成します。
def main(name: str):
print(f"Hello {name}")
このスクリプトは、内部で Typer を使用していません。しかし、typer コマンドを使用して、CLI アプリケーションとして実行できます。
実行¶
typer コマンドを使用してアプリケーションを実行します。
// Run your application
$ typer main.py run
// You get a nice error, you are missing NAME
Usage: typer [PATH_OR_MODULE] run [OPTIONS] NAME
Try 'typer [PATH_OR_MODULE] run --help' for help.
╭─ Error ───────────────────────────────────────────╮
│ Missing argument 'NAME'. │
╰───────────────────────────────────────────────────╯
// You get a --help for free
$ typer main.py run --help
Usage: typer [PATH_OR_MODULE] run [OPTIONS] NAME
Run the provided Typer app.
╭─ Arguments ───────────────────────────────────────╮
│ * name TEXT [default: None] [required] |
╰───────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────╮
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────╯
// Now pass the NAME argument
$ typer main.py run Camila
Hello Camila
// It works! 🎉
これは、内部で Typer を使用しない最もシンプルなユースケースですが、簡単なスクリプトにはすでに非常に役立ちます。
注: 自動補完は、Python パッケージを作成して --install-completion で実行した場合、または typer コマンドを使用した場合に機能します。
コードで Typer を使用する¶
次に、自分のコードで Typer を使い始めましょう。main.py を次のように更新します。
import typer
def main(name: str):
print(f"Hello {name}")
if __name__ == "__main__":
typer.run(main)
これで Python で直接実行できます。
// Run your application
$ python main.py
// You get a nice error, you are missing NAME
Usage: main.py [OPTIONS] NAME
Try 'main.py --help' for help.
╭─ Error ───────────────────────────────────────────╮
│ Missing argument 'NAME'. │
╰───────────────────────────────────────────────────╯
// You get a --help for free
$ python main.py --help
Usage: main.py [OPTIONS] NAME
╭─ Arguments ───────────────────────────────────────╮
│ * name TEXT [default: None] [required] |
╰───────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────╮
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────╯
// Now pass the NAME argument
$ python main.py Camila
Hello Camila
// It works! 🎉
注: 同じスクリプトを typer コマンドで呼び出すこともできますが、必須ではありません。
例のアップグレード¶
これは、可能な限り最も簡単な例でした。
次に、もう少し複雑な例を見てみましょう。
2つのサブコマンドの例¶
ファイル main.py を変更します。
typer.Typer() アプリを作成し、パラメータを使用して2つのサブコマンドを作成します。
import typer
app = typer.Typer()
@app.command()
def hello(name: str):
print(f"Hello {name}")
@app.command()
def goodbye(name: str, formal: bool = False):
if formal:
print(f"Goodbye Ms. {name}. Have a good day.")
else:
print(f"Bye {name}!")
if __name__ == "__main__":
app()
そして、それは次のようになります。
- 明示的に
typer.Typerアプリを作成します。- 前の
typer.runは、実際には暗黙的に作成します。
- 前の
@app.command()で2つのサブコマンドを追加します。- （
typer.runの代わりに）関数であるかのようにapp()自体を実行します。
アップグレードされた例を実行¶
新しいヘルプを確認します。
$ python main.py --help
Usage: main.py [OPTIONS] COMMAND [ARGS]...
╭─ Options ─────────────────────────────────────────╮
│ --install-completion Install completion │
│ for the current │
│ shell. │
│ --show-completion Show completion for │
│ the current shell, │
│ to copy it or │
│ customize the │
│ installation. │
│ --help Show this message │
│ and exit. │
╰───────────────────────────────────────────────────╯
╭─ Commands ────────────────────────────────────────╮
│ goodbye │
│ hello │
╰───────────────────────────────────────────────────╯
// When you create a package you get ✨ auto-completion ✨ for free, installed with --install-completion
// You have 2 subcommands (the 2 functions): goodbye and hello
次に、hello コマンドのヘルプを確認します。
$ python main.py hello --help
Usage: main.py hello [OPTIONS] NAME
╭─ Arguments ───────────────────────────────────────╮
│ * name TEXT [default: None] [required] │
╰───────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────╮
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────╯
そして、goodbye コマンドのヘルプを確認します。
$ python main.py goodbye --help
Usage: main.py goodbye [OPTIONS] NAME
╭─ Arguments ───────────────────────────────────────╮
│ * name TEXT [default: None] [required] │
╰───────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────╮
│ --formal --no-formal [default: no-formal] │
│ --help Show this message │
│ and exit. │
╰───────────────────────────────────────────────────╯
// Automatic --formal and --no-formal for the bool option 🎉
これで、新しいコマンドラインアプリケーションを試すことができます。
// Use it with the hello command
$ python main.py hello Camila
Hello Camila
// And with the goodbye command
$ python main.py goodbye Camila
Bye Camila!
// And with --formal
$ python main.py goodbye --formal Camila
Goodbye Ms. Camila. Have a good day.
まとめ¶
要約すると、パラメータの型（CLI 引数 と CLI オプション）を関数パラメータとして 一度 宣言します。
標準的な現代の Python 型でそれを行います。
特定のライブラリの新しい構文、メソッド、クラスなどを学習する必要はありません。
標準の Python のみです。
たとえば、int の場合は
total: int
または、bool フラグの場合は
force: bool
同様に、ファイル、パス、enum（選択肢）などにも当てはまります。また、サブコマンドのグループを作成し、メタデータを追加し、追加の検証などを行うツールもあります。
手に入れるもの: あらゆる場所で 補完 と 型チェック を含む、優れたエディターサポート。
ユーザーが手に入れるもの: パッケージをインストールしたとき、または typer コマンドを使用するときに、自動 --help、ターミナル（Bash、Zsh、Fish、PowerShell）での 自動補完。
より多くの機能を含むより完全な例については、チュートリアル - ユーザーガイドを参照してください。
依存関係¶
Typer は巨人の肩に乗っています。内部の必須の依存関係は、Click だけです。
デフォルトでは、追加の標準依存関係も付属しています。
rich: きれいにフォーマットされたエラーを自動的に表示します。shellingham: 補完をインストールするときに現在のシェルを自動的に検出します。shellinghamを使用すると、--install-completionを使用するだけで済みます。shellinghamを使用しない場合は、補完をインストールするシェルの名前を渡す必要があります。例：--install-completion bash。
typer-slim¶
追加の標準オプションの依存関係が不要な場合は、代わりに typer-slim をインストールしてください。
次のようにインストールする場合
pip install typer
...には、次と同じコードと依存関係が含まれます
pip install "typer-slim[standard]"
standard の追加の依存関係は、rich と shellingham です。
注: typer コマンドは、typer パッケージにのみ含まれています。
ライセンス¶
このプロジェクトは、MIT ライセンスの条項に基づいてライセンスされています。