PythonのTyperライブラリ徹底解説：モダンなCLI開発の新常識 🚀

はじめに：Typerとは何か？

Typerは、Pythonでコマンドラインインターフェース（CLI）アプリケーションを構築するためのモダンなライブラリです。FastAPIの作者であるTiago Montes氏によって開発され、2020年4月に初めてリリースされました。Typerは、Python 3.6以降で導入された型ヒント (Type Hints) を最大限に活用することで、非常に少ないコード量で、直感的かつ堅牢なCLIアプリケーションを作成できることを目指しています。😊

従来のCLIライブラリ（例えばPython標準の `argparse` や、デコレータベースの `Click`）と比較して、TyperはよりPythonicな書き方で、開発者の体験（Developer Experience, DX）を大幅に向上させることを特徴としています。特に、コードの可読性、エディタの補完機能との親和性、そして自動生成されるヘルプメッセージの質において優れています。

Typerは内部的に強力なCLIライブラリであるClickを基盤として利用しています。これにより、Clickの持つ豊富な機能や安定性を継承しつつ、型ヒントによるシンプルさとモダンなPython開発スタイルを融合させています。

Typerの主な特徴 ✨

• 型ヒントベースの設計: 関数の引数に型ヒントを記述するだけで、CLIの引数やオプションを定義できます。これにより、新たな構文を覚える必要がなく、標準的なPythonの知識で開発を進められます。
• 優れた開発者体験: 型ヒントのおかげで、VSCodeやPyCharmなどのエディタによる強力なコード補完や型チェックの恩恵を受けられます。デバッグ時間を短縮し、コードの品質を高めることができます。
• 自動ヘルプ生成: 関数や引数の型ヒント、docstringから、自動的に分かりやすいヘルプメッセージ（`–help`）が生成されます。特別な記述を追加する必要はほとんどありません。
• 自動補完機能: Bash, Zsh, Fish, PowerShellなど、主要なシェルに対応したコマンドライン補完機能を簡単に導入できます。ユーザーは `TAB` キーを押すだけで、利用可能なコマンドやオプションを補完できます。
• シンプルさと拡張性: 最小限のコード（インポート1行、関数呼び出し1行）で基本的なCLIアプリを作成でき、必要に応じてサブコマンド、コールバック、バリデーションなど、複雑な機能を追加していくことが可能です。
• Clickのパワー: 内部でClickを利用しているため、Clickが持つ強力な機能（コンテキスト管理、プログレスバー連携など）を活用できます。
• リッチな出力（オプション）: デフォルトでRichライブラリと連携し、整形されたエラーメッセージや美しい出力を提供します（`rich` がインストールされている場合）。

インストール

Typerはpipを使って簡単にインストールできます。すべての機能（リッチな出力やシェル補完の自動検出など）を利用したい場合は `[all]` を指定するのがおすすめです。

pip install "typer[all]"

最小限の依存関係でインストールしたい場合は、以下のようにします。この場合、Richやshellingham（シェル自動検出用）は含まれません。

pip install typer

TyperはPython 3.6以降が必要です。型ヒントを積極的に利用するためです。

基本的な使い方：最初のTyperアプリ

Typerを使った最もシンプルな例を見てみましょう。これは、名前を受け取って挨拶を表示するCLIです。

import typer

def main(name: str):
    """
    名前を受け取って挨拶を表示します。
    """
    print(f"Hello {name} 👋")

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

これを `main.py` として保存し、ターミナルから実行します。

python main.py --name Alice
# 出力: Hello Alice 👋

python main.py "Bob"
# 出力: Hello Bob 👋

注目すべきは、`main` 関数の引数 `name: str` です。この型ヒントだけで、Typerは `name` という名前の必須の文字列引数（デフォルトではコマンドラインオプション `–name` としても、位置引数としても解釈される傾向があります。より厳密には `typer.Argument` や `typer.Option` で指定します。）を認識します。

さらに、`–help` オプションも自動で生成されます。

python main.py --help

出力例:

Usage: main.py [OPTIONS] NAME

  名前を受け取って挨拶を表示します。

Arguments:
  NAME  [required]

Options:
  --install-completion [bash|zsh|fish|powershell|pwsh]
                                  Install completion for the current shell.
  --show-completion [bash|zsh|fish|powershell|pwsh]
                                  Show completion for the current shell, to
                                  copy it or customize the installation.
  --help                          Show this message and exit.

関数のdocstringが説明文として使われ、引数 `name` が `Arguments` としてリストアップされているのがわかります。デフォルトで補完用のオプション (`–install-completion`, `–show-completion`) も追加されます（これらは `typer.Typer(add_completion=False)` で無効化できます）。

主要な概念：引数とオプション

Typerでは、CLIの引数 (Arguments) とオプション (Options) を関数のパラメータと型ヒントで定義します。

• 引数 (Argument): 通常、コマンドの後ろに順番に指定される値です。例: `cp source.txt destination.txt` の `source.txt` と `destination.txt`。
• オプション (Option): 通常、`–` や `-` から始まる名前付きのパラメータです。例: `ls –all -l` の `–all` と `-l`。

デフォルトでは、関数のパラメータは引数として解釈される傾向があります。オプションを明示的に定義するには、パラメータのデフォルト値として `typer.Option()` を使用します。必須の引数を定義するには、デフォルト値なしの型ヒント、または `typer.Argument(…)` を使用します。

例：引数とオプションの定義

import typer
from typing import Optional # Python 3.9以前では from typing_extensions import Annotated
# Python 3.9以降では typing.Annotated を推奨
# from typing import Annotated # Python 3.9+

app = typer.Typer()

@app.command()
def main(
    name: str = typer.Argument(..., help="挨拶する相手の名前"), # 必須の引数 (Ellipsis (...) は必須を示す)
    lastname: Optional[str] = typer.Argument(None, help="相手の姓 (オプション)"), # オプションの引数
    age: int = typer.Option(20, help="年齢", min=0, max=120), # オプション (デフォルト値あり)
    city: Optional[str] = typer.Option(None, "--city", "-c", help="都市名"), # オプション (短い形式 -c も定義)
    formal: bool = typer.Option(False, "--formal", help="丁寧な挨拶にするか"), # フラグオプション
):
    """
    引数とオプションを使って挨拶をカスタマイズします。
    """
    message = f"Hello {name}"
    if lastname:
        message += f" {lastname}"
    if formal:
        message = f"Good day, {message}."
    else:
        message += "."

    print(message)
    print(f"You are {age} years old.")
    if city:
        print(f"Living in {city}.")

if __name__ == "__main__":
    app() # typer.Typer() インスタンスを呼び出す

この例でのポイント：

• `typer.Typer()`: 複数のコマンドを持つアプリケーションを作成する場合、まず `Typer` インスタンスを作成します。
• `@app.command()`: 関数をCLIコマンドとして登録するためのデコレータです。
• `typer.Argument(…)`: 必須の引数を定義します。`…` (Ellipsis) は必須であることを示す慣用的な方法です（デフォルト値が `…` であるため）。`help` で説明を追加できます。
• `Optional[str] = typer.Argument(None, …)`: オプション（省略可能）の引数を定義します。デフォルト値を `None` にします。
• `typer.Option(default_value, …)`: オプションを定義します。デフォルト値を指定すると、省略可能なオプションになります。`help` で説明、`min`/`max` で数値の範囲制限などが可能です。
• `typer.Option(None, “–option-name”, “-o”, …)`: オプションの名前（`–city`）と短い形式（`-c`）を明示的に指定できます。
• `bool = typer.Option(False, “–flag-name”, …)`: `bool` 型でデフォルト値を持つオプションは、フラグとして機能します。`–formal` が指定されれば `True` に、されなければ `False` (デフォルト値) になります。Typerは自動的に `–no-formal` のような逆のフラグも（通常は）生成します（`typer.Option` で明示的に指定した場合は挙動が変わることがあります）。
• `app()`: `typer.Typer` インスタンスを呼び出してアプリケーションを実行します。
• Annotated (推奨): Python 3.9以降では、`typing.Annotated` (またはPython 3.8以前では `typing_extensions.Annotated`) を使用して、型ヒントとメタデータ (Typerの `Argument` や `Option`) を組み合わせる方法が推奨されています。これにより、コードがよりクリーンになります。

  from typing import Annotated # Python 3.9+ (or typing_extensions for older)
  import typer
  
  # 例:
  # name: Annotated[str, typer.Argument(help="Your name")]
  # age: Annotated[int, typer.Option(min=0)] = 20

実行例

# 必須引数のみ
python main.py Alice

# 出力:
# Hello Alice.
# You are 20 years old.

# 引数とオプションを指定
python main.py Bob Smith --age 30 --city London --formal

# 出力:
# Good day, Hello Bob Smith.
# You are 30 years old.
# Living in London.

# ヘルプ表示
python main.py --help

# 出力 (抜粋):
# Usage: main.py [OPTIONS] NAME [LASTNAME]
#
#   引数とオプションを使って挨拶をカスタマイズします。
#
# Arguments:
#   NAME        挨拶する相手の名前  [required]
#   [LASTNAME]  相手の姓 (オプション)
#
# Options:
#   --age INTEGER RANGE     年齢  [default: 20]
#   --city TEXT, -c TEXT    都市名
#   --formal / --no-formal  丁寧な挨拶にするか  [default: no-formal]
#   --install-completion [bash|zsh|fish|powershell|pwsh]
#                           Install completion for the current shell.
#   --show-completion [bash|zsh|fish|powershell|pwsh]
#                           Show completion for the current shell, to copy it or
#                           customize the installation.
#   --help                  Show this message and exit.

高度な機能 🛠️

サブコマンド

複雑なCLIツールでは、`git commit` や `git push` のように、複数のサブコマンドを持つことがよくあります。Typerでは、`@app.command()` デコレータを複数使用するだけで、簡単にサブコマンドを実装できます。

import typer

app = typer.Typer()
users_app = typer.Typer() # サブコマンド用の別のTyperインスタンス
items_app = typer.Typer() # さらに別のTyperインスタンス

app.add_typer(users_app, name="users", help="ユーザー関連の操作")
app.add_typer(items_app, name="items", help="アイテム関連の操作")

@users_app.command("create")
def users_create(username: str):
    """新しいユーザーを作成します。"""
    print(f"Creating user: {username}")

@users_app.command("delete")
def users_delete(username: str, force: bool = typer.Option(False, "--force", "-f")):
    """ユーザーを削除します。"""
    if force:
        print(f"Force deleting user: {username}")
    else:
        print(f"Deleting user: {username}")

@items_app.command("create")
def items_create(item_name: str, price: float = typer.Option(..., help="アイテムの価格")):
    """新しいアイテムを作成します。"""
    print(f"Creating item: {item_name} with price: {price}")

@items_app.command("list")
def items_list():
    """アイテム一覧を表示します。"""
    print("Listing items...")

if __name__ == "__main__":
    app()

この例では:

• `users_app` と `items_app` という別の `Typer` インスタンスを作成しています。
• `app.add_typer()` を使って、これらのインスタンスをメインの `app` にサブコマンドグループとして追加しています (`name` でサブコマンド名を指定)。
• 各サブコマンドグループ内で、通常通り `@*.command()` を使って具体的なコマンドを定義します。

実行例:

# ヘルプ表示 (トップレベル)
python main.py --help
# Usage: main.py [OPTIONS] COMMAND [ARGS]...
# Options: ...
# Commands:
#  items  アイテム関連の操作
#  users  ユーザー関連の操作

# usersサブコマンドのヘルプ
python main.py users --help
# Usage: main.py users [OPTIONS] COMMAND [ARGS]...
# Options: ...
# Commands:
#  create  新しいユーザーを作成します。
#  delete  ユーザーを削除します。

# itemsサブコマンドのヘルプ
python main.py items --help
# Usage: main.py items [OPTIONS] COMMAND [ARGS]...
# Options: ...
# Commands:
#  create  新しいアイテムを作成します。
#  list    アイテム一覧を表示します。

# コマンドの実行
python main.py users create Alice
# Output: Creating user: Alice

python main.py items create "Laptop" --price 1500.0
# Output: Creating item: Laptop with price: 1500.0

自動補完 (Autocompletion)

Typerの大きな利点の一つが、強力な自動補完機能です。ユーザーがシェルで `TAB` キーを押すと、利用可能なコマンド、サブコマンド、オプション、さらにはオプションの値まで補完候補として表示できます。

補完のインストール:

作成したCLIツールをPythonパッケージとしてインストールした後、ユーザーは以下のコマンドを実行することで、使用しているシェル（Bash, Zsh, Fish, PowerShellなど）に補完設定をインストールできます。

your-cli-tool --install-completion

`shellingham` ライブラリがインストールされていれば、シェルは自動検出されます。インストールされていない場合は、`your-cli-tool –install-completion bash` のようにシェル名を指定する必要があります。

インストールせずに補完スクリプトを確認・カスタマイズしたい場合は、`–show-completion` を使います。

your-cli-tool --show-completion

オプション値のカスタム補完:

特定のオプションに対して、利用可能な値を補完させることも可能です。これには、補完用の関数を定義し、`typer.Option` の `autocompletion` 引数に渡します。

import typer
from typing import List, Optional

app = typer.Typer()

def complete_name(incomplete: str) -> List[str]:
    """名前に 'a' が含まれる候補を返す補完関数"""
    names = ["Alice", "Bob", "Charlie", "Diana", "Albert"]
    for name in names:
        if name.lower().startswith(incomplete.lower()) and "a" in name.lower():
            yield name

@app.command()
def main(
    name: Optional[str] = typer.Option(None, help="名前", autocompletion=complete_name)
):
    if name:
        print(f"Selected name: {name}")
    else:
        print("No name selected.")

if __name__ == "__main__":
    app()

この例では、`–name` オプションの値を入力中に `TAB` を押すと、`complete_name` 関数が実行され、’a’ を含む名前の候補が表示されます。

その他の便利な機能

• プロンプトによる入力: `typer.Option(…, prompt=True)` や `typer.Argument(…, prompt=True)` を使うと、ユーザーに値の入力を対話的に求めることができます。パスワード入力用に `hide_input=True` も指定できます (`typer.Option(…, prompt=True, hide_input=True)`)。
• コールバック関数: オプションやコマンドが処理される前後に特定の関数（コールバック）を実行できます。バージョン情報を表示する `–version` オプションの実装などによく使われます。
• 値の検証: `typer.Option` や `typer.Argument` で `min`, `max` を使った数値範囲の検証や、`choices` を使った選択肢の制限（enumなど）が可能です。より複雑な検証はコールバック関数内で行うこともできます。
• コンテキストの利用: コマンド間で状態を共有したり、高度な制御を行うために `typer.Context` オブジェクトを利用できます。
• プログレスバー: `rich` ライブラリと組み合わせることで、簡単にプログレスバーを表示できます。
• テスト: `typer.testing.CliRunner` を使うことで、pytestなどを用いたCLIアプリケーションのテストが容易になります。
• 終了コード: `raise typer.Exit(code=0)` で正常終了、`raise typer.Exit(code=1)` などでエラー終了を明示的に示すことができます。

Typer vs Argparse vs Click 🤔

PythonでCLIを開発する際の主要なライブラリを比較してみましょう。

Typerの利点まとめ:

• モダンなPythonとの親和性: 型ヒントを最大限に活用し、現代的なPython開発スタイルにマッチします。
• コード量の削減: 同じ機能を実現するための記述量が `argparse` や `Click` よりも少なくなる傾向があります。
• 開発効率の向上: 強力なエディタサポートにより、コーディング、デバッグ、リファクタリングが容易になります。
• ユーザーフレンドリーなCLI: 高品質なヘルプと強力な自動補完機能により、エンドユーザーにとっても使いやすいCLIを提供します。

`argparse` は標準ライブラリであるため手軽ですが、記述が冗長になりがちです。`Click` は非常に強力で広く使われていますが、デコレータを多用するスタイルが Typer の型ヒントベースのアプローチとは異なります。Typer は Click の良さを継承しつつ、型ヒントによってさらなるシンプルさと開発者体験の向上を実現していると言えるでしょう。