CLIしたい（typer）

$ pip3 install typer[all]

# パッケージ/cli.py
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を使うと、サブコマンド付きのCLIをすぐに作ることができます。 上記のサンプルは、公式ドキュメントのAn example with two subcommands - Typerにあるコードです。 とりあえずこのサンプルコードをcli.pyのようなファイルにコピペして動かしてみるだけで、使い方がわかると思います。

これまで、CLIを作るときの引数／オプション解析は、定番のPython標準argparseパッケージを使っていましたが、サブコマンドを作るのはちょっと大変な印象でした。 （やってみようと思って調べたことはありますが実際に作ったことはない・・・） Typerは、引数とオプション、コマンドの説明も、いつもの関数を作る作業の延長ででき、非常に簡単だと感じました。

コマンドしたい（typer.Argument / typer.Option）

import typer
from typing_extensions import Annotated

def vth(
    """
    コマンドの説明
    """
    ch Annotated[int, typer.Argument(help="チャンネル番号")],
    vth: Annotated[int, typer.Argument(help="スレッショルド値")],
    max_retry: Annotated[int, typer.Option(help="リトライ数")] = 3,
    load_from: Annotated[str, typer.Option(help="設定ファイル名")] = "daq.toml"
    ):
    pass

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

コマンドとして実行したい関数名をtyper.runに渡します。 関数のdocstringがコマンドの説明になります。

typer.Argumentで引数を設定できます。 typer.Optionでオプション引数を設定できます。

typing_extensions.Annotatedで引数の説明を追加できます。 追加方法などは、ドキュメントを参照してください。

ヒント

typer.Argument / typer.Optionと デフォルト値のあり / なしを考えると 以下の表のような引数名のパターンが考えられます。

	デフォルト値なし	デフォルト値あり
typer.Argument	CLI arguments	optional CLI arguments
typer.Option	required CLI options	CLI options

通常は、 CLI arguments（必須の位置引数）、 CLI options（オプション引数） のみのコマンドを設計するとよいと思います。

ただし、 optional CLI arguments（位置引数なのにオプション）、 required CLI options（オプション引数なのに必須） も、名前がちょっとおかしい気がしますが、定義できるようになっています。

サブコマンドしたい（@app.command）

import typer

app = typer.Typer()

@app.command()
def vth(
    """
    コマンドの説明
    """
    ch Annotated[int, typer.Argument(help="チャンネル番号")],
    vth: Annotated[int, typer.argument(help="スレッショルド値")],
    max_retry: Annotated[int, typer.argument(help="リトライ数")] = 3,
    load_from: Annotated[str, typer.argument(help="設定ファイル名")] = "daq.toml"
    ):
    pass

if __name__ == "__main__":
    app()

@app.commandデコレーターでサブコマンドを定義できます。

注釈

appの部分は任意のオブジェクト名を使用できます。 上記のサンプルではapp = typer.Typer()を作成しているため、デコレーターは@app.commandになります。

出力に色をつけたい（from rich import print）

import typer
from rich import print

...（省略）...

richパッケージのprintを使うと、出力を色付けできます。 色付けの詳細や、その他の表示形式はドキュメントを参照してください。

中断／終了したい（typer.Exit）

@app.command()
def コマンド名(引数):
    if 引数がおかしい条件:
        logger.error(f"値が正しくないです : {引数}")
        typer.Exit()

Typerを使うと、引数のバリデーションを柔軟に書くことができます。 引数の値が正しくない場合に終了する場合、typer.Exitが使えます。 わざわざimport sysしてsys.exitする必要がないので便利です。

PoetryでCLIしたい

# pyproject.toml

[tool.poetry.scripts]
CLI名 = "パッケージ.cli:app"

Poetryを使って自作CLIを作成する場合は、pyproject.tomlの[tool.poetry.scripts]セクションに記述します。 詳しくは公式ドキュメントのBuilding a package - Typerを参照してください。