Pythonのコマンドラインツールを設計する: argparse、main()、終了コード

目的

シェルスクリプトやCIジョブ、エージェントが扱えるコマンドラインツールを作る: 引数の挙動が予測可能で、ヘルプテキストがそのままドキュメントになり、終了コードが構造化されていて、ストリームが整理されている。

前提条件

pyproject.tomlを備えたパッケージ(パッケージングの記事を参照)で、そのロジックは引数処理とは切り離されたインポート可能な関数として実装されていること。

手順

1. def main(argv: list[str] | None = None) -> intを書く。この関数がパーサーを構築し、argvをパースし(渡されなければsys.argv[1:]にフォールバックする)、終了コードを返す。これを[project.scripts] tool = "pkg.cli:main"として登録し、if __name__ == "__main__": sys.exit(main())を追加する。こうすればテストはmain(["--flag", "x"])を呼び出し、戻り値とキャプチャした出力に対してアサートできるようになる。
2. パーサーにはprog、description、そして例を示すepilogを設定する。不正な値が使用法エラーとして報告されるようtype=変換器(int、pathlib.Path、あるいはArgumentTypeErrorを送出する関数)を使い、値が閉じた集合であればchoices=を、複数コマンドのツールにはadd_subparsers(dest="command", required=True)を使う。
3. sys.exitのドキュメントが説明する慣習に従う: Unixのプログラムは一般に、コマンドライン構文エラーには2を、それ以外のすべてのエラーには1を使い、0は成功を意味する。argparseは不正な引数に対してすでにステータス2で終了する。sysexits.h由来のコード(EX_USAGE 64、EX_NOINPUT 66、EX_UNAVAILABLE 69、EX_TEMPFAIL 75)を追加で採用するのは、--helpがそれらを文書化している場合に限る。
4. 結果はstdoutに、診断情報はstderrに書く。出力を他のプログラムが読み取る場合は--jsonを用意し、printをあちこちに散らす代わりにログレベルを設定する--verbose/--quietを用意する。
5. 想定される失敗(FileNotFoundError、接続エラー、ドメイン固有の例外)はmainの中で捕捉し、stderrに1行出力して文書化されたコードを返す。想定外の例外はそのまま伝播させ、トレースバックと終了コード1が保たれるようにする。
6. KeyboardInterruptをクリーンアップしたうえで130を返すことで処理し、これは128にシグナル番号を足すというシェルの慣習に一致する。stdoutのBrokenPipeErrorは握りつぶし、tool | headが静かに終了するようにする。
7. ヘルプを正直に保つ: 読みやすいプレースホルダーのためにmetavarを使い、デフォルト値が表示されるようArgumentDefaultsHelpFormatterを使い、--helpが0で終了することをテストする。

期待される結果

tool --helpがインターフェース全体を文書化する。tool --bad; echo $?は2を出力する。入力の問題があればstderrに1行出力し、文書化されたコードを返す。呼び出し側はテキストを解析することなくコードで分岐できる。

限界と検証の根拠

sys.exitのドキュメントは、ほとんどのシステムで終了コードは0から127の範囲でなければならないと注記している。それを超える値はシェルのシグナルエンコーディングと衝突する。exit_on_error=Falseにすると、パーサーは終了する代わりにArgumentErrorを送出するようになり、これは埋め込み用途には向くが独自のエラー処理が必要になる。慣習は引用したドキュメントに従っており、ユーザビリティの測定結果は主張していない。

Ctrl-C後に終了する

シェルは、終了コードを読み取るのではなく、子プロセスがSIGINTによって死んだかどうかを確認することで、割り込みが外側のスクリプトも止めるべきかどうかを判断する。そのためKeyboardInterruptを捕捉して130を返すツールは、通常の終了のように見えてしまい、for f in *; do tool "$f"; doneはCtrl-Cのたびに次のファイルへと処理を続けてしまう。クリーンアップを行ったうえで、未処理の割り込みが起きた場合と同じようにプロセスを終了させること(Pythonは3.8以降これを自動で行っている):

except KeyboardInterrupt:
    cleanup()
    signal.signal(signal.SIGINT, signal.SIG_DFL)
    os.kill(os.getpid(), signal.SIGINT)

$?は依然として130を示し、そのプロセスをwaitしている親プロセスにはシグナルによる終了として見える。return 130は、コードだけを読むと分かっている呼び出し元向けに取っておく。