typer

Typer の知識

Python 関数に型注釈を付けて、Typer でコマンドラインアプリケーションを構築します。Typer は型注釈を、ヘルプテキストを自動生成する検証済みのコマンドラインパラメーターに変換します。

Typer のバージョン： !python -c "import typer; print(typer.__version__)" 2>/dev/null || echo "not found in PATH"

対象範囲

共通ルール（アーキテクチャ、型付け、テスト、コマンドラインのルール）については、python-engineering:standards-for-python-development を参照してください。

対象：Typer を使ったコマンドラインアプリケーションの構築、コマンドライン引数やオプションの定義、サブコマンドの構成、コマンドラインアプリのテスト、プロンプト、列挙型、プログレスバー、オートコンプリートなどの Typer 機能の使用についてユーザーから尋ねられた場合に有効化します。

対象範囲：

• typer.Typer() と typer.run() によるアプリの作成
• コマンドライン引数（typer.Argument()）とオプション（typer.Option()）
• パラメーターの型 — 列挙型、パス、数値、日付、UUID、カスタム型
• app.add_typer() によるサブコマンドの構成
• typer.testing.CliRunner によるテスト
• 出力、色、プログレスバー、コールバック、オートコンプリート

対象外：

• Typer が公開する範囲を超える Click の内部仕様
• typer.echo / typer.style を超える Rich ライブラリ
• FastAPI やその他の Web フレームワーク

ワークフロー

flowchart TD
    Start([Task received]) --> Q1{Task type?}
    Q1 -->|Create app or add commands| AppCmd[Load reference — app-and-commands.md]
    Q1 -->|Define arguments or options| Params[Load reference — parameters.md]
    Q1 -->|Use enum, path, date, UUID| Types[Load reference — parameter-types.md]
    Q1 -->|Add subcommands or sub-apps| Sub[Load reference — subcommands.md]
    Q1 -->|Write tests| Test[Load reference — testing.md]
    Q1 -->|Callbacks, output, progress, packaging| Adv[Load reference — advanced-patterns.md]

リファレンスファイル

アプリとコマンド

Typer アプリの作成、@app.command() によるコマンドの登録、複数コマンドを持つアプリの設定、コマンド名とヘルプテキストの制御に関する基本的なパターンです。 新しいアプリの作成、コマンドの追加、アプリレベルの動作設定を行うときに読み込みます。

../python3-cli/references/typer-app-and-commands.md

パラメーター

コマンドライン引数とコマンドラインオプションの完全なリファレンスです — typer.Argument()、typer.Option()、デフォルト値、必須か任意か、ヘルプテキスト、プロンプト、パスワード入力、オプション名、環境変数との紐付け、複数の値、bool フラグ、バージョンオプションを扱います。 コマンドラインパラメーターを定義するときや、入力の受け取り方を制御するときに読み込みます。

../python3-cli/references/typer-parameters.md

パラメーターの型

Typer が理解する型注釈です — str、int、float、bool、enum.Enum、Literal、pathlib.Path、ファイルオブジェクト、datetime、UUID、カスタムの Click ParamType サブクラスを扱います。 パラメーター値を選択肢に制限するとき、パスを検証するとき、日付を解析するとき、カスタム型を実装するときに読み込みます。

../python3-cli/references/typer-parameter-types.md

サブコマンド

app.add_typer() を使って複数の typer.Typer() インスタンスを組み合わせ、入れ子になったコマンド階層を作成します。単一ファイルおよび複数ファイルのパターン、名前、ヘルプテキスト、コールバックのオーバーライドを扱います。 サブアプリの追加、コマンドグループの作成、git のような複数階層のコマンドツリーの構築時に読み込みます。

../python3-cli/references/typer-subcommands.md

テスト

pytest と typer.testing.CliRunner を使って Typer アプリをテストします。テストでのアプリの呼び出し、終了コードと出力の確認、プロンプト入力のシミュレーション、関数単体のテストを扱います。 Typer のコマンドラインアプリのテストを書くときに読み込みます。

../python3-cli/references/typer-testing.md

高度なパターン

コンテキスト（typer.Context）、優先コールバック、typer.echo / typer.secho / typer.style、プログレスバー、typer.Exit / typer.Abort、typer.confirm、オートコンプリートの設定、pyproject.toml によるパッケージ化、typer.launch を扱います。 バージョンフラグ、色付き出力、進捗表示、シェル補完を実装するときや、配布可能なツールとしてコマンドラインアプリをパッケージ化するときに読み込みます。

../python3-cli/references/typer-advanced-patterns.md

クイックリファレンス

import typer
from typing import Annotated

app = typer.Typer()


@app.command()
def main(
    name: str,  # required argument
    count: Annotated[int, typer.Option()] = 1,  # optional option
    formal: bool = False,  # --formal / --no-formal
):
    """Greet NAME."""
    for _ in range(count):
        greeting = f"Good day, {name}." if formal else f"Hello {name}"
        typer.echo(greeting)


if __name__ == "__main__":
    app()

$ python main.py Alice --count 2 --formal
Good day, Alice.
Good day, Alice.