6.20.2.4 ヘルプを作成する

どのスクリプトでも使うことになる機能の最後の一つは、optparse の機能を使ったヘルプメッセージの生成です。やらなければならないことは、オプションを追加する際に help 値を指定することだけです。新たなパーザを作成し、ユーザに優しい (ドキュメント付きになっている) オプションを追加していきましょう:

usage = "usage: %prog [options] arg1 arg2"
parser = OptionParser(usage=usage)
parser.add_option("-v", "--verbose",
                  action="store_true", dest="verbose", default=1,
                  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", "--file", dest="filename",
                  metavar="FILE", help="write output to FILE"),
parser.add_option("-m", "--mode",
                  default="intermediate",
                  help="interaction mode: one of 'novice', "
                       "'intermediate' [default], 'expert'")

optparse がコマンドラインの解析中に -h か ---help に遭遇するか、または単に parser.print_help() を呼び出すと、以下の内容を標準出力に出力します:

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)
  -fFILE, --file=FILE  write output to FILE
  -mMODE, --mode=MODE  interaction mode: one of 'novice', 'intermediate'
                       [default], 'expert'

optparse に可能な限り親切なヘルプメッセージを出力させる上で役に立つと思われることを以下にざっと述べます:

スクリプト自体の使用法メッセージ (usage) を以下のようにして定義します:
```
usage = "usage: %prog [options] arg1 arg2"
```
optparse は、使用法メッセージ文字列中の "%prog" に現在のスクリプト名、すなわち os.path.basename(sys.argv[0]) を展開します。展開された文字列は、詳細なオプションヘルプの前に出力されます。
使用法メッセージ文字列を与えなければ、optparse は面白みのない、とはいえ気の利いたデフォルト値: ``usage: %prog [options]'' を使います。スクリプトが固定引数を採っていなければ、この値でかまわないでしょう。
各オプションはヘルプ文字列を定義していますが、行の折り返しについて悩むことはありません -- optparse が行を折り返し、ヘルプメッセージ出力の見栄えがよくなるよう気を配ります。
値をとるオプションについては、そのことを示す内容がヘルプメッセージ内に自動的に生成されます。例えば、``mode'' オプションは:
```
-mMODE, --mode=MODE
```
となります。ここで、``MODE'' はメタ変数と呼ばれます: この値はユーザが -m/--mode に対して指定するようスクリプトが期待している引数を表します。デフォルトでは、 optparse は目的変数の名前を大文字に変換して、メタ変数として使います。時にこれは期待通りの値になりません -- 例えば、上の例の filename オプションでは明示的に metavar="FILE" を設定しており、その結果自動生成されたオプション説明は以下のようになります:
```
-fFILE, --file=FILE
```
この機能は重要なもので、それは表示スペースを節約するといった理由にとどまりません: 上の例では、手作業で書かれたヘルプテキストの中では、メタ変数として ``FILE'' を使っています。その結果、ユーザに対して、堅苦しく表現された書法 ``-fFILE'' とくだけた意味付け説明 ``write output to FILE'' が対応しているという情報を与えます。これは、ヘルプテキストをエンドユーザに対してより明快でより有用にする上では、単純でありながら効果的な手法です。

数多くのオプションを扱うときには、オプションをグループ化するとヘルプメッセージ出力をよりよくする上で便利です。OptionParser は複数のオプショングループを収めることができ、各グループは複数のオプションを収めることができます。

上で定義されたパーザに続けて OptionGroup を追加するのは簡単です:

group = OptionGroup(parser, "Dangerous Options",
                    "Caution: use these options at your own risk."
                    "  It is believed that some of them bite.")
group.add_option("-g", action="store_true", help="Group option.")
parser.add_option_group(group)

このコードは以下のヘルプ出力になります:

usage:  [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)
  -fFILE, --file=FILE  write output to FILE
  -mMODE, --mode=MODE  interaction mode: one of 'novice', 'intermediate'
                       [default], 'expert'

  Dangerous Options:
    Caution: use of these options is at your own risk.  It is believed that
    some of them bite.
    -g                 Group option.

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