どのスクリプトでも使うことになる機能の最後の一つは、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: %prog [options] arg1 arg2"
optparse は、使用法メッセージ文字列中の "%prog" に
現在のスクリプト名、すなわち os.path.basename(sys.argv[0])
を展開します。展開された文字列は、詳細なオプションヘルプの前に
出力されます。
使用法メッセージ文字列を与えなければ、optparse は面白みの ない、とはいえ気の利いたデフォルト値: ``usage: %prog [options]'' を使います。スクリプトが固定引数を採っていなければ、この値で かまわないでしょう。
-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.
ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。