nikkie-ftnextの日記

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

docstring に \b を追加して、Click のヘルプメッセージに段落内の改行を保持させる

コマンドラインツール

はじめに

七尾百合子さん、お誕生日 325日目 おめでとうございます！ nikkieです。

Click についての Today（※最近） I Learned です。

目次

Agent Development Kit のヘルプを見ていて

それは v1.23.0 でカスタムメトリクスをサポート1したadk evalのヘルプメッセージを読んでいたときのこと
（※ヘルプメッセージは抜粋しています）

% uvx --python 3.13 --from google-adk==1.23.0 adk eval --help

  For example, we have `sample_eval_set_file.json` file that has following the eval cases:
  sample_eval_set_file.json:   |....... eval_1   |....... eval_2   |....... eval_3   |.......
  eval_4   |....... eval_5

私「なんだろう、ここ？」

実装箇所はこちら
https://github.com/google/adk-python/blob/v1.23.0/src/google/adk/cli/cli_tools_click.py#L704-L711

  For example, we have `sample_eval_set_file.json` file that has following the
  eval cases:
  sample_eval_set_file.json:
    |....... eval_1
    |....... eval_2
    |....... eval_3
    |....... eval_4
    |....... eval_5

なるほど、JSON ファイルに含まれている eval をファイルツリーのように表示したかったんですね。
「これって直せるの？」と、たしか Opus 4.5 に質問したところ、学びがありました。

Click のヘルプメッセージ

ADK は CLI 機能に Click を採用しています2。

Click は docstring からヘルプメッセージを生成します。
https://click.palletsprojects.com/en/stable/documentation/#help-texts

For commands, the docstring of the function is automatically used if provided.

Click は改行1つを無視します。
これがadk evalの先のヘルプメッセージの説明です
https://click.palletsprojects.com/en/stable/documentation/#click-s-wrapping-behavior

Click’s default wrapping ignores single new lines and rewraps the text based on the width of the terminal to a maximum of 80 characters by default,

この wrap を無効にする方法が\bです。
https://click.palletsprojects.com/en/stable/documentation/#escaping-click-s-wrapping

This behavior can be escaped on a per-paragraph basis by adding a line with only \b .

ドキュメントにある書き方の例です

    \b
    This is
    a paragraph
    without rewrapping.

\bを追加するプルリクエストを送る

上記を元にプルリクエストを送りました。

+  \b
  For example, we have `sample_eval_set_file.json` file that has following the
  eval cases:
  sample_eval_set_file.json:
    |....... eval_1
    |....... eval_2
    |....... eval_3
    |....... eval_4
    |....... eval_5

ヘルプメッセージに改行が残るようになりました！

  For example, we have `sample_eval_set_file.json` file that has following the
  eval cases:
  sample_eval_set_file.json:
    |....... eval_1
    |....... eval_2
    |....... eval_3
    |....... eval_4
    |....... eval_5

触りながらコマンドのヘルプを見る中で、気づいたら小さなプルリクエストを送っています。

終わりに

Click は docstring 中の段落内の改行を無視しますが、\b を使うと改行を保持できます。
Click を使っている CLI ツールのヘルプメッセージに改行が変なところを見つけたら、ぜひ\bを追加してプルリクエストしてみてください3！

  1. ↩
  2. 過去記事が少しあります ↩
  3. マインドセットとしてはこちらと共通です ↩