6.21.2.6 ヘルプの生成

optparse にはヘルプと使い方の説明 (usage text) を生成する機能があり、ユーザに優しいコマンドラインインタフェースを作成する上で役立ちます。やらなければならないのは、各オプションに対するhelp の値と、必要ならプログラム全体の使用法を説明する短いメッセージを与えることだけです。

ユーザフレンドリな (ドキュメント付きの) オプションを追加した OptionParser を以下に示します:

usage = "usage: %prog [options] arg1 arg2"
parser = OptionParser(usage=usage)
parser.add_option("-v", "--verbose",
                  action="store_true", dest="verbose", default=True,
                  help="make lots of noise [default]")
parser.add_option("-q", "--quiet",
                  action="store_false", dest="verbose", 
                  help="be vewwy quiet (I'm hunting wabbits)")
parser.add_option("-f", "--filename",
                  metavar="FILE", help="write output to FILE"),
parser.add_option("-m", "--mode",
                  default="intermediate",
                  help="interaction mode: novice, intermediate, "
                       "or expert [default: %default]")

optparse がコマンドライン上で"-h" や"-help" を見つけた場合やユーザがparser.print_help() を呼び出した場合、このOptionParser は以下のようなメッセージを標準出力に出力します:

usage: <yourscript> [options] arg1 arg2

options:
  -h, --help            show this help message and exit
  -v, --verbose         make lots of noise [default]
  -q, --quiet           be vewwy quiet (I'm hunting wabbits)
  -f FILE, --filename=FILE
                        write output to FILE
  -m MODE, --mode=MODE  interaction mode: novice, intermediate, or
                        expert [default: intermediate]

(help オプションでヘルプを出力した場合、optparse は出力後にプログラムを終了します。)

optparse ができるだけうまくメッセージを生成するよう手助けするには、他にもまだまだやるべきことがあります:

スクリプト自体の利用法を表すメッセージを定義します:
```
usage = "usage: %prog [options] arg1 arg2"
```
optparse は "%prog" を現在のプログラム名、すなわち os.path.basename(sys.argv[0]) と置き換えます。この文字列は詳細なオプションヘルプの前に展開され出力されます。
usage の文字列を指定しない場合、optparse は型どおりとはいえ気の効いたデフォルト値、 "usage: %prog [options]" を使います。固定引数をとらないスクリプトの場合はこれで十分でしょう。
全てのオプションにヘルプ文字列を定義します。行の折り返しは気にしなくてかまいません -- optparse は行の折り返しに気を配り、見栄えのよいヘルプ出力を生成します。
オプションが値をとるということは自動的に生成されるヘルプメッセージの中で分かります。例えば、``mode'' option の場合には:
```
-m MODE, --mode=MODE
```
のようになります。
ここで ``MODE'' はメタ変数 (meta-variable) と呼ばれます: メタ変数は、ユーザが -m/--mode に対して指定するはずの引数を表します。デフォルトでは、optparse は保存先の変数名を大文字だけにしたものをメタ変数に使います。これは時として期待通りの結果になりません -- 例えば、上の例の--filename オプションでは明示的に metavar="FILE" を設定しており、その結果自動生成されたオプション説明テキストは:
```
-f FILE, --filename=FILE
```
のようになります。
この機能の重要さは、単に表示スペースを節約するといった理由にとどまりません: 上の例では、手作業で書いたヘルプテキストの中でメタ変数として ``FILE'' を使っています。その結果、ユーザに対してやや堅苦しい表現の書法 ``-f FILE'' と、より平易に意味付けを説明した ``write output to FILE'' との間に対応があるというヒントを与えています。これは、エンドユーザにとってより明解で便利なヘルプテキストを作成する単純でありながら効果的な手法なのです。
デフォルト値を持つオプションのヘルプ文字列には%default を入れられます -- optparse は%default をデフォルト値の str() で置き換えます。該当するオプションにデフォルト値がない場合 (あるいはデフォルト値が None である場合) %default の展開結果は none になります。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。