pydantic-settingsで環境変数からもオプション引数を指定できるCLIを作る〜サブコマンド篇〜

はじめに

pydantic-settingsでCLIの素振りの続き、今回はサブコマンドまわりを触ります。

pydantic-settingsでCLIが作れる！

パースライブラリPydanticを設定にも適用するpydantic-settings。
なんと設定だけでなく、CLIアプリケーションも作れちゃいます！

pydantic-settingsで作るCLIのよさは、オプション引数を環境変数からも指定できること。
標準ライブラリのargparseでこれを実現するのはいささか骨が折れそうなのですが、pydantic-settingsではデフォルトでサポートされているんです！
argparseすきすきの民の私ですが、これは乗り換えを決意するのに十分すぎる理由でした（なので素振りをしています）

前回の素振りより、オプション引数・位置引数の扱いが分かっています。
pydantic_settings.BaseSettingsを継承したクラスにて

オプション引数：string: str = Field(validation_alias=AliasChoices("s", "string"))
- -sや--stringで指定できる
- 環境変数SやSTRINGでも指定できる（素晴らしすぎる！！👏）
- デフォルト値を持たせることも可能（Field("デフォルト値", validation_alias=...)）
位置引数：string: CliPositionalArg[str]
- 位置引数は環境変数からは指定できません（位置で指定しましょう）
- 位置引数にデフォルト値は持たせられない模様¹

サブコマンド

Rustのclapで素振りしたのと同様なCLIを今回作りました²。

% uv run --quiet cli.py position エミリー 5
エミリーエミリーエミリーエミリーエミリー
% OPTION_S=エミリー uv run --quiet cli.py option --num 5
エミリーエミリーエミリーエミリーエミリー

動作環境

uv 0.4.27 (Homebrew 2024-10-25)
Python 3.13.0
pydantic-settings 2.7.0
- Pydantic 2.10.4

ドキュメント「Subcommands and Positional Arguments」より
https://docs.pydantic.dev/latest/concepts/pydantic_settings/#subcommands-and-positional-arguments

サブコマンドに使うのはCliSubCommand（によるアノテーション）

class Settings(BaseSettings):
    position: CliSubCommand[Position]
    option: CliSubCommand[Option]

サブコマンドの実体は
- PydanticのBaseModelを継承したクラス
- または、pydantic.dataclasses.dataclassでデコレートしたクラス
- （IMO：サブコマンドにはBaseSettingsは継承しないんですね！）
BaseSettingsを継承したクラス（コマンドの大元）では、CliApp.get_subcommand()を使う
- デフォルトでは、サブコマンドのインスタンスのcli_cmd()メソッドを呼び出す
- https://docs.pydantic.dev/latest/api/pydantic_settings/#pydantic_settings.CliApp.run_subcommand
設定のとき³と同様に、環境変数は「BaseSettings継承クラスの属性名」+「区切り文字」+「サブコマンドのエイリアス」でした
- 区切り文字はenv_nested_delimiterでアンダースコアを指定
- 列挙すると、OPTION_S・OPTION_STRING・OPTION_N・OPTION_NUM
（前回記事より）CliApp.run(Settings)でSettingsインスタンスのcli_cmd()メソッドを呼び出してます

サブコマンドもできた〜！🙌

なお、Noteに制約の記述が

it does not allow for multiple subparsers with each subparser having its own set of subcommands.

直面したわけではないのでピンときてはいないのですが、argparseみたいにサブコマンド・サブサブコマンドとネストさせられないってことですかね？
BaseSettingsを継承したクラスをCliSubCommandアノテーションできないようですし。
argparseでは使うことがあったのでちょっと痛いかもしれないですが、サブサブコマンドが必要になったときに考えようかと思います（サブコマンドだけに合わせて、コマンドの設計を見直すことになりそう）

終わりに

pydantic-settingsで作るCLIで、サブコマンドの作り方を完全に理解しました！
clapの素振りでも書きましたが、位置引数・オプション引数・サブコマンドを押さえたので、argparseで書いているCLIの8割くらいは、pydantic-settingsでも書けそうです（※馬鹿の山感）。

Pydanticですから書いてて型がバチバチ当たりますし、環境変数からオプションを指定できるのは広く使われるCLIは備えている印象のある便利機能で、pydantic-settingsは推したいライブラリになりました。
君が天才！

argparse（やRustのclap）ではできていました。位置引数のデフォルト値をそれほど使っていない私としては、あまり痛くはないです↩
uvがinline script metadataを読んでいるという出力（「Reading inline script metadata」）をしなくする--quietを見つけました。https://docs.astral.sh/uv/reference/cli/#uv-run ↩
設定の素振りの様子：pydantic-settings素振りの記：ネストした設定〜BaseModel継承クラスが全ての属性でデフォルト値を持つならば、インスタンス化してBaseSettings側のデフォルト値とする〜 - nikkie-ftnextの日記 ↩

nikkie-ftnextの日記

イベントレポートや読書メモを発信

pydantic-settingsで環境変数からもオプション引数を指定できるCLIを作る〜サブコマンド篇〜

はじめに

目次

pydantic-settingsでCLIが作れる！

サブコマンド

終わりに