脱 argparse！ Typer + Rich を使った型安全でモダンな CLI 開発 / Modern, Type-Safe CLI Development with Typer and Rich — Moving Beyond argparse

Transcript

1. 株式会社 PKSHA Technology 中村 光伴 2025年10⽉22⽇ 『Pythonの多様性 深掘りLT Night 』 @Findy TECH BATON 脱 argparse！ Typer + Rich を使った 型安全でモダンな CLI 開発 © PKSHA Technology Inc. 1
2. © PKSHA Technology Inc. ⾃⼰紹介 • 2024年に新卒で PKSHA Technology に⼊社 • いわゆる Web フルスタックエンジニア • よく使う：Python / TypeScript / AWS • ハンドルネームの Arumakan は Nakamura の逆順⽂字列 • We’re hiring !! 2 ソフトウエアエンジニア 中村 光伴 なかむら こうすけ X: @Arumakan_ei1727
3. © PKSHA Technology Inc. OSS 開発でなくとも CLI を書く機会は多い • 開発⽤の補助ツール • PoC • データ処理 • AWS Batch などのジョブ / Docker エントリポイント 3 コマンドライン引数でパラメータを注⼊できるようにしたい
4. © PKSHA Technology Inc. argparse のつらみ • 型推論が効かない • バリデーションロジックを ⼿続き的に書く必要がある • サブコマンドの定義が⼤変 • シェルのタブ補完スクリプトは ⾃前で書く必要がある 4 Any 型に推論されてしまう
5. © PKSHA Technology Inc. 1分でできる Typer クイックスタート uv init → uv add typer → 下記を main.py に保存して uv run python main.py Bob --times 3 5 ※わかりやすさのため、 1 <= times <= 5 のバリデーションは⼀旦⼊れていません
6. © PKSHA Technology Inc. 実⾏結果 6 正常系： --times に⾮整数を渡した場合：
7. © PKSHA Technology Inc. typo したら正しいオプション名をサジェストしてくれる 7
8. © PKSHA Technology Inc. Typer の基本 FastAPI と同様の書き味 (FastAPI の作者と同じ @tiangolo ⽒が作ったもの) ちなみに CLI 構築ライブラリの Click を裏で使っている 8 typing.Literal にも対応 (⻑らく enum を使う必要があったが 1ヶ⽉前のリリースで対応された)
9. © PKSHA Technology Inc. 前述の例の --help の出⼒ 9 前述の例ではデフォルト値付きの引数が Option になる https://typer.tiangolo.com/tutorial/options/required/#required-cli-options
10. © PKSHA Technology Inc. typer.Argument と typer.Option 10
11. © PKSHA Technology Inc. ファイルの存在判定や環境変数からの読み取りもできる 11 ディレクトリは拒否 ファイルの存在を要求 環境変数からも読み取り
12. © PKSHA Technology Inc. サブコマンドは関数を複数定義してデコレートするだけ app = typer.Typer() → @app.command() でデコレート 関数名がサブコマンド名になる (@app.command() の name 引数で設定可) 12 ※デコレートが2つ以上ある場合にサブコマンドとして扱われる [^1] [^1]: https://typer.tiangolo.com/tutorial/commands/one-or-multiple/
13. © PKSHA Technology Inc. コマンドラインのパース以外にも CLI のための便利機能がいろいろ 13 [^2] : Rich がインストールされている場合に限る。 typer.run() は内部で app() (つまり Typer.__call__) を呼び出しているだけ。 https://github.com/fastapi/typer/blob/3dcb16b2693bbd8e968fe6e5f4c7c4b47f1d2ba8/typer/main.py#L1068-L1071 やりたいこと 操作 yes/no の確認 typer.confirm() ファイルパスと “-” (stdin) の統⼀的な open typer.open_file() プログレスバーの表⽰ typer.progressbar() スタックトレースのリッチな表⽰ typer.run() または app() で自動で有効化 [^2]
14. © PKSHA Technology Inc. スタックトレースのリッチな表⽰ 例外発⽣時に整形されたスタックトレースを表 ⽰してくれる 各スタックフレームのローカル変数を表⽰して くれてデバッグが捗る！ typer.Typer(pretty_exceptions_enalbe=False) で無効化できる Rich の機能を使っているため、Rich がインストールされて いない場合はリッチな表⽰にならない [^3] 14 [^3]: https://github.com/fastapi/typer/blob/3dcb16b2693bbd8e968fe6e5 f4c7c4b47f1d2ba8/typer/main.py#L75-L81
15. © PKSHA Technology Inc. Typer と Rich の関係 Typer のコアは typer-slim というライブラリ pip install typer を実⾏すると typer-slim, rich, shellingham, typer コマンドが⼊る ※shellingham はカレントシェルの検出をするパッケージ 15 インストールコマンド typer-slim (Typerのコア) rich, shellingham typer コマンド pip install typer ✅ ✅ ✅ pip install typer-slim ✅ pip install ‘typer-slim[standard]’ ✅ ✅ 出典: https://typer.tiangolo.com/#typer-slim
16. © PKSHA Technology Inc. Rich の便利な機能 • rich.traceback.install() • rich.logging.RichHandler • rich.print() • rich.inspect() • …etc. たくさんあるので詳細は Rich のドキュメントへ 16
17. © PKSHA Technology Inc. CLI 開発中でもシェルのタブ補完を効かせたい！ • python main.py --show-completion / --install-completion で補完シェルスクリプトを⽣成 / インストールできる typer コマンドで実⾏すれば解決する 17 しかしこれはビルドしてインストールされた状態で使われる想定 ⼀般的にはコマンドラインの $0 で補完スクリプトが決まる ▶ python main.py のように実⾏する限り python の補完しか出てこない！
18. © PKSHA Technology Inc. typer コマンドの補完を効かせる⽅法 python main.py [ARGS]--. は typer main.py run [ARGS]--. でも実⾏できる ⼿順 1. typer コマンドへの PATH を通す ◦ mise use pip:typer や ./.venv/bin/activate や uv tool install typer など 2. typer --install-completion 3. ご使⽤のシェルで補完を有効化する ◦ zsh の例： autoload -Uz compinit -& compinit 4. typer main.py run -- でタブを押すと補完が効く 18 ※ mise や direnv で⾃動化できる mise.toml なら [env] セクションで _.python.venv = { path='.venv', create=true } .envrc なら layout python
19. © PKSHA Technology Inc. 19 EOF 快適に CLI を開発しよう！