\section{\module{optparse} --- 強力なコマンドラインオプション解析器} \declaremodule{standard}{optparse} \moduleauthor{Greg Ward}{gward@python.net} \sectionauthor{Johannes Gijsbers}{jlgijsbers@users.sf.net} \sectionauthor{Greg Ward}{gward@python.net} \modulesynopsis{強力で柔軟、拡張性があり簡単に利用できるコマンドライン解析ライブラリ} \versionadded{2.3} \module{optparse} モジュールは、Python による強力で柔軟、拡張性があり 簡単に利用できるコマンドライン解析ライブラリです。 \module{optparse} を使うことで、有能で洗練されたコマンドラインオプションの 解析機能を少ない労力でスクリプトに追加できます。 以下は \module{optparse} を使っていくつかのコマンドラインオプション を簡単なスクリプトに追加する例です: \begin{verbatim} from optparse import OptionParser parser = OptionParser() parser.add_option("-f", "--file", dest="filename", help="write report to FILE", metavar="FILE") parser.add_option("-q", "--quiet", action="store_false", dest="verbose", default=1, help="don't print status messages to stdout") (options, args) = parser.parse_args() \end{verbatim} このようにわずかな行数のコードによって、スクリプトのユーザは コマンドライン上で以下のような "よくある使い方" を実行できるように なります: \begin{verbatim} $ -f outfile --quiet $ -qfoutfile $ --file=outfile -q $ --quiet --file outfile \end{verbatim} (これらの結果は全て \code{options.filename == "outfile"} および \code{options.verbose == 0} ...つまり予想していた結果となります) もっと気の利いたことに、ユーザは \begin{verbatim} $ -h $ --help \end{verbatim} のいずれかを実行することができ、\module{optparse} はスクリプトの オプションについて簡単にまとめた内容を出力します: \begin{verbatim} usage: [options] options: -h, --help show this help message and exit -fFILE, --file=FILE write report to FILE -q, --quiet don't print status messages to stdout \end{verbatim} 以上は \module{optparse} がコマンドライン解析に与える柔軟性のほんの 一部にすぎません。 \subsection{オプション解析への道\label{optparse-tao}} \module{optparse} は、私が考えている最も明瞭かつ素直で ユーザフレンドリーなコマンドラインプログラムのインタフェース を設計するための方法を実装したものです。 簡単に言うと、私は引数解析の王道 (そしてたくさんの邪道) についてかなり頑固な考えを持っており、\module{optparse} はそういった考えの多くを反映しています。 この節では上記の哲学について説明するつもりです。この哲学は \UNIX{} と GNU ツールキットに強く影響されています。 \subsubsection{用語\label{optparse-terminology}} まずは用語の定義を行う必要があります。 \begin{definitions} \term{引数 (argument)} コマンドラインでユーザが入力するテキストの塊で、シェルが \cfunction{execl()} や \cfunction{execv()} に引き渡すものです。 Python では、引数は \var{sys.argv[1:]} の要素となります。 (\var{sys.argv[0]} は実行しようとしているプログラムの名前です; 引数解析に関しては、この要素はあまり重要ではありません。) \UNIX{} シェルでは、 ``語 (word)'' という用語も使います。 場合によっては \var{sys.argv[1:]} 以外の引数リストを代入する方が 望ましいことがあるので、``引数'' は ``\var{sys.argv[1:]} または \var{sys.argv[1:]} の代替として提供される別のリストの要素'' と読解するべきでしょう。 \term{オプション (option)} 追加的な情報を与えるための引数で、プログラムの実行に対する教示や カスタマイズを行います。オプションには多様な文法が存在します; 伝統的な \UNIX{} における書法は \programopt{-} の後ろに一文字 が続くもので、例えば \programopt{-x} や \programopt{-F} です。 また、伝統的な \UNIX{} における書法では、複数のオプションを 一つの引数にまとめることができ、例えば \programopt{-x -F} は \programopt{-xF} と等価です。 GNU プロジェクトでは \longprogramopt{} の後ろにハイフンで区切られた 語を続ける方法、例えば \longprogramopt{file} や \longprogramopt{dry-run} を導入しています。\module{optparse} ではこれら二種類のオプション書法 だけを提供しています。 他に見られる他のオプション書法には以下のようなものがあります: \begin{itemize} \item ハイフンの後ろに数個の文字が続くもので、例えば \programopt{-pf} 。 (このオプションは複数のオプションを一つにまとめたものとは *違います*。) \item ハイフンの後ろに語が続くもので、例えば \programopt{-file} 。 (これは技術的には上の書式と同じですが、通常同じプログラム上で一緒に 使われることはありません。) \item プラス記号の後ろに一文字、数個の文字、または語を続けたもので、例えば \programopt{+f} 、 \programopt{+rgb} 。 \item スラッシュ記号の後ろに一文字、数個の文字、または語を続けたもので、例えば \programopt{/f} 、 \programopt{/file} 。 \end{itemize} これらのオプション書法は \module{optparse} ではサポートされておらず、 将来にわたってサポートされることもありません。 (これらのオプション 書法のいずれかを本当に使いたいのなら、 OptionParser をサブクラス化 して、難解な部分を全て上書きしなければならないでしょう。しかし できればやめてください！ \module{optparse} は熟慮の上で伝統的な \UNIX/GNU 的書法を採っています; 最初の 3 つの書法は場所によっては非標準 ですし、最後の書法は MS-DOS/Windows かつ/または VMS をターゲットに しているときしか意味をなしません。) \term{オプション引数 (option argument)} あるオプションの後ろに続く引数で、そのオプションに密接な関連を もち、オプションと同時に引数リストから取り出されます。 しばしば、オプション引数はオプションと一体の引数としてとりこまれる ことがあります。例えば以下: \begin{verbatim} ["-f", "foo"] \end{verbatim} は以下の引数: \begin{verbatim} ["-ffoo"] \end{verbatim} と等価なことがあります。(\module{optparse} ではこの書法をサポート しています) あるオプションは引数をとることがなく、またあるオプションは 常に引数をとります。多くの人々が ``オプションのオプション引数'' 機能を欲しています。これ、あるオプションについては引数 が存在するときだけ引数をとり、そうでないときには引数をとらない ようにするという機能です。この機能は引数解析をあいまいにするため、 議論の的となる点です: 例えば、もし \programopt{-a} がオプション引数を とり、\programopt{-b} がまったく別のオプションだとしたら、 \programopt{-ab} をどうやって解析すればいいのでしょうか？ \module{optparse} は今のところこの機能をサポートしていません。 \term{固定引数 (positional argument)} 他のオプションが解析される、すなわち他のオプションとその引数が 解析されて引数リストから除去された後に引数リストに置かれている ものです。 \term{必須のオプション (required option)} コマンドラインで与えなければならないオプションです; ``必須なオプション'' という言葉は矛盾のある語法であり、通常は貧弱なユーザインタフェース デザインと考えられています。 \module{optparse} では必須オプションの 実装を妨げはしませんが、とりたてて実装の役に立つようにもなっていません。 \module{optparse} で必須オプションを実装する方法については ``拡張の例'' (\ref{optparse-extending-examples} 節) を参照してください。 \end{definitions} 例えば、以下のような架空のコマンドラインを考えてみてください: \begin{verbatim} prog -v --report /tmp/report.txt foo bar \end{verbatim} \programopt{-v} と \longprogramopt{report} は両方ともオプションです。 \longprogramopt{report} が引数を一つとると仮定すると、 ``/tmp/report.txt'' はオプション引数です。 ``foo'' および ``bar'' は固定引数です。 \subsubsection{オプションはどう使うのでしょうか？\label{optparse-options}} オプションはプログラムの実行をチューニングしたり、カスタマイズ したりするための補足的な情報を与えるために使われます。 補足すると、オプションは通常 \emph{選択可能 (optional)} となっています。 プログラムはいかなるオプションが指定されていなくても、きちんと 動作できなくてはなりません。(\UNIX{} や GNU ツールセットから プログラムをランダムに取り出してみてください。プログラムは オプション無しで動作して、意味のある結果になるでしょう？ 私の知っている例外は \program{find} 、 \program{tar} 、 \program{dd} といったプログラムです --- これらは全て 変種のはみだし者で、インタフェースが非標準で混乱をまねくものだと 批判されてきました。) 大多数の人々が、プログラムに ``必須オプション'' を持たせたいと 望んでいます。しかし考えてみてください。もしオプションが必須だと いうのなら、そのオプションは \emph{オプション:選択可能項目 など ではありません}！ プログラムがうまく動作するために絶対的に必要とする 情報があるとするなら、固定引数を使うべきです。(とはいえ、 どうしても ``必須オプション'' をプログラムに組み込みたいというのなら、 \module{optparse} を使った実装方法については ``拡張の例'' (~\ref{optparse-extending-examples} 節) を読んでください。 ファイルをコピーする地味なユーティリティ \program{cp} について 考えてみましょう。ファイルをコピーしようと試みるときに、コピー先 や少なくとも一つのコピー元を指定しなければ、このコマンドは意味を なしません。従って、\program{cp} は引数無しで実行すると失敗します。 しかしながら、このコマンドは、拡張性のある便利な書法を持っており、 オプションに全然頼っていません: \begin{verbatim} $ cp SOURCE DEST $ cp SOURCE ... DEST-DIR \end{verbatim} You can get pretty far with just that. ほとんどの \program{cp} の実装では、ファイルをどのようにしてコピー するかを的確に微調整するためのオプション: 例えばファイルモードや最終更新時刻を変更しないようにしたり、 シンボリックリンクの追跡を避けたり、既存のファイルをぶちこわし (clobber) にする前に同意を求めたり、などを一そろい提供しています。 しかし、これらのオプションはいずれも、 ファイルを別のファイルにコピーしたり N 個のファイルを他のディレクトリ にコピーしたりするといった、\program{cp} の主要な役割を混乱 させることはありません。 \subsubsection{固定引数はどう使うのでしょうか？ \label{optparse-positional-arguments}} 上の例について補足します: 固定引数とは、プログラムを動作させる ために、絶対的にかつ明確に必要とされる情報の断片です。 よいユーザインタフェースとは、可能な限り少ない固定引数をもつ べきです。プログラムを正しく動作させるために 17 個もの別個の情報が 必要だとしたら、その情報をユーザからどうやって引き出そうかという ことはさほど問題にはなりません --- ほとんどの人はプログラム を正しく動作させられるようになる前にあきらめて立ち去るでしょう。 これはユーザインタフェースがコマンドラインでも、設定ファイルでも GUI やその他のいずれであっても当てはまることがらです: 多くの要求をユーザに押し付ければ、ほとんどのユーザはただ 音をあげるだけなのです。 要するに、ユーザが絶対に提供しなければならない情報だけに制限する --- 可能な限りよく練られたデフォルト設定を使うよう試みてください。 もちろん、プログラムには適度な柔軟性を持たせたいとも望むはずですが、 それこそがオプションの果たす役割です。繰り返しますが、 設定ファイルのエントリであろうが、 GUI の ``環境設定'' ダイアログにあるチェックボックスであろうが、 コマンドライン上のオプションであろうが関係ありません --- より多くオプションを実装すればプログラムはより柔軟性を持ち、 実装はより難解になります。高すぎる柔軟性でユーザ (あなた自身もですよ！) を閉口させるのは至って簡単なのです。 \subsection{基本的な使い方 \label{optparse-basic-usage}} \module{optparse} はとても柔軟性があって強力な一方、基本的なケースを 動作させるために試練を受けたり大量のドキュメントを読む必要は ありません。 このドキュメントでは、いくつかの単純な使用パターンを実演して、 スクリプトで \module{optparse} を使えるようにすることを目的としています。 コマンドラインを \module{optparse} で解析するためには、 \class{OptionParser} インスタンスを作成して populate する必要が あります。当然ながら、\module{optparse} を使うスクリプトはいずれも \class{OptionParser} クラスを import しなければなりません。 \begin{verbatim} from optparse import OptionParser \end{verbatim} メインプログラムの冒頭で、パーザを作成してください: \begin{verbatim} parser = OptionParser() \end{verbatim} これで、パーザ内のオプションを移すことができます。各オプションは 現実には同義のオプション文字列になります; ほとんどの場合、 短いオプション文字列を一つと、長いオプション文字列を一つ --- 例えば \programopt{-f} and \longprogramopt{file} --- を持ちます: \begin{verbatim} parser.add_option("-f", "--file", ...) \end{verbatim} もちろん、最も知りたいことは、オプション文字列の後に続くキーワード 引数が何かということです。このドキュメントでは、キーワード引数として 指定できる内容について 4 種類: \var{action}、\var{type}、 \var{dest} (destination: 目的変数)、 および\var{help} だけをカバーします。 \subsubsection{"store" アクション\label{optparse-store-action}} アクションは、\var{action} が設定されているオプションがコマンド ライン内に見つかったときに \module{optparse} が行うべきことを 教えます。例えば、 \var{store} はこういう意味です: 次の引数 (または現在の引数の残りの部分) を取り上げ、正しい型であるか 確認して、決められた目的変数に保存します。 例として、先ほどのオプションの "..." を埋めてみましょう: \begin{verbatim} parser.add_option("-f", "--file", action="store", type="string", dest="filename") \end{verbatim} 次に、架空のコマンドラインをでっち上げて、\module{optparse} に解析してもらいましょう: \begin{verbatim} args = ["-f", "foo.txt"] (options, args) = parser.parse_args(args) \end{verbatim} (引数リストを \function{parse_args()} に渡さなければ、 自動的に \var{sys.argv[1:]} を使うので注意してください。) \module{optparse} が \programopt{-f} を見つけると、次の引数 --- ``foo.txt'' --- を吸出し、特殊なオブジェクトの \var{filename} 属性に記憶します。このオブジェクトは \function{parse_args()} の 戻り値の最初の値です。従って以下のコード: \begin{verbatim} print options.filename \end{verbatim} は ``foo.txt'' を出力します。 \module{optparse} でサポートされている他のオプションの型は ``int'' と ``float'' です。以下に整数型の引数を要求するオプションの例を示し ます: \begin{verbatim} parser.add_option("-n", type="int", dest="num") \end{verbatim} 長い文字列によるオプションを与えていないことに注意してください。 これはまったく問題なく受理されます。 また、\var{action}を指定していません --- これはアクションがデフォルト で ``store'' になるからです。 架空のコマンドラインをもう一つ解析してみましょう。今度は、 オプション引数をオプションの右側にぴったりくっつけて一緒くたに します --- \programopt{-n42} (一つの引数のみ) は \programopt{-n 42} (二つの引数からなる) と等価になります: \begin{verbatim} (options, args) = parser.parse_args(["-n42"]) print options.num \end{verbatim} は ``42'' を出力します。 ``float'' 型を使った例は、読者のための練習課題として残しておきます。 型を指定しない場合、 \module{optparse} は引数を ``string'' 型と 仮定します。デフォルトのアクションが ``store'' であることも 併せて考えると、最初の例はもっと短くなります: \begin{verbatim} parser.add_option("-f", "--file", dest="filename") \end{verbatim} 目的変数名を与えなければ、\module{optparse} はオプション文字列 から気の利いたデフォルト値を決めます: 最初の長い形式のオプション 文字列が \longprogramopt{foo-bar} だったとすると、デフォルトの 目的変数は \var{foo_bar} となります。長い形式のオプションが ない場合、\module{optparse} は最初の短いオプションに注目します: \programopt{-f} に対するデフォルトの目的変数は \var{f} となります。 型を追加するのはかなり簡単です; ~\ref{optparse-adding-types} 節、 ``新しい型を追加する'' を参照してください。 \subsubsection{その他の "store_*" 操作 \label{optparse-other-store-actions}} フラグオプション --- 特定のオプションが見つかったときに、ある変数を 真または偽にする --- は、とても一般的な機能です。\module{optparse} では、フラグオプションを二つの別個のアクション ``store_true'' と ``store_false'' でサポートします。例えば、 \var{verbose} フラグが \programopt{-v} でオンにされ、 \programopt{-q} でオフにされると します: \begin{verbatim} parser.add_option("-v", action="store_true", dest="verbose") parser.add_option("-q", action="store_false", dest="verbose") \end{verbatim} ここで二つのオプションを同じ目的変数に設定しましたが、これは全く 問題ありません。 (ただし、デフォルト値を設定する際に少しだけ 注意する必要があります --- 以下を参照してください。) \module{optparse} が \programopt{-v} をコマンドライン内に見つけると、 特殊な {option values} オブジェクトの\var{verbose} 属性を 1 に 設定します; \programopt{-q} が見つかれば、 \var{verbose} を 0 に 設定します。 \subsubsection{デフォルト値を設定する \label{optparse-setting-default-values}} 上で述べてきた例は全て、あるコマンドラインオプションが見つかった 際に何らかの変数 (``destination: 目的変数'') の設定を伴うもの でした。ではこれらのオプションがなければどうなるのでしょうか？ デフォルト値を与えていないので、これらの値は全て None になります。 これはこれでよいときもあります (デフォルトで None になるように しているのはこのためです) が、もっときちんと制御したい場合も あります。その要求を満たすために、\module{optparse} では各目的変数 ごとにデフォルトの値を指定できるようにしており、デフォルト値は コマンドラインが解析される前に代入されます。 まず、 verbose/quiet の例を考えてみましょう。\module{optparse} に 対して、\programopt{-q} がない限り \var{verbose} を 1 に設定させたい なら、以下のようにします: \begin{verbatim} parser.add_option("-v", action="store_true", dest="verbose", default=1) parser.add_option("-q", action="store_false", dest="verbose") \end{verbatim} 奇妙なことに、上のコードは以下とまったく等価です: Oddly enough, this is exactly equivalent: \begin{verbatim} parser.add_option("-v", action="store_true", dest="verbose") parser.add_option("-q", action="store_false", dest="verbose", default=1) \end{verbatim} これらのコードが等価なのは、オプションの \emph{目的変数} に対して デフォルト値を指定しており、各コードの二つのオプションは同じ 目的変数 (\var{verbose} 変数) を持っているからです。 以下のコード: \begin{verbatim} parser.add_option("-v", action="store_true", dest="verbose", default=0) parser.add_option("-q", action="store_false", dest="verbose", default=1) \end{verbatim} を考えてみましょう。繰り返しますが、\var{verbose} のデフォルト値は 1 です: 特定の目的変数に対するデフォルト値として有効なのは、最後に指定 した値です。 \subsubsection{ヘルプを作成する \label{optparse-generating-help}} どのスクリプトでも使うことになる機能の最後の一つは、\module{optparse} の機能を使ったヘルプメッセージの生成です。やらなければならないことは、 オプションを追加する際に \var{help} 値を指定することだけです。 新たなパーザを作成し、ユーザに優しい (ドキュメント付きになっている) オプションを追加していきましょう: \begin{verbatim} 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'") \end{verbatim} \module{optparse} がコマンドラインの解析中に \programopt{-h} か \longprogramopt{--help} に遭遇するか、または単に \method{parser.print_help()} を呼び出すと、以下の内容を 標準出力に出力します: \begin{verbatim} 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' \end{verbatim} \module{optparse} に可能な限り親切なヘルプメッセージを出力させる 上で役に立つと思われることを以下にざっと述べます: \begin{itemize} \item スクリプト自体の使用法メッセージ (usage) を以下のようにして定義 します: \begin{verbatim} usage = "usage: %prog [options] arg1 arg2" \end{verbatim} \module{optparse} は、使用法メッセージ文字列中の "\%prog" に 現在のスクリプト名、すなわち \code{os.path.basename(sys.argv[0])} を展開します。展開された文字列は、詳細なオプションヘルプの前に 出力されます。 使用法メッセージ文字列を与えなければ、\module{optparse} は面白みの ない、とはいえ気の利いたデフォルト値: ``usage: \%prog [options]'' を使います。スクリプトが固定引数を採っていなければ、この値で かまわないでしょう。 \item 各オプションはヘルプ文字列を定義していますが、行の折り返しに ついて悩むことはありません --- \module{optparse} が行を折り返し、 ヘルプメッセージ出力の見栄えがよくなるよう気を配ります。 \item 値をとるオプションについては、そのことを示す内容が ヘルプメッセージ内に自動的に生成されます。例えば、``mode'' オプションは: \begin{verbatim} -mMODE, --mode=MODE \end{verbatim} となります。ここで、``MODE'' はメタ変数と呼ばれます: この値は ユーザが \programopt{-m}/\longprogramopt{mode} に対して指定するよう スクリプトが期待している引数を表します。デフォルトでは、 \module{optparse} は目的変数の名前を大文字に変換して、メタ変数として使います。 時にこれは期待通りの値になりません --- 例えば、上の例の \var{filename} オプションでは明示的に \code{metavar="FILE"} を設定しており、その結果 自動生成されたオプション説明は以下のようになります: \begin{verbatim} -fFILE, --file=FILE \end{verbatim} この機能は重要なもので、それは表示スペースを節約するといった理由 にとどまりません: 上の例では、手作業で書かれたヘルプテキストの 中では、メタ変数として ``FILE'' を使っています。その結果、 ユーザに対して、堅苦しく表現された書法 ``-fFILE'' とくだけた 意味付け説明 ``write output to FILE'' が対応しているという情報 を与えます。これは、ヘルプテキストをエンドユーザに対してより明快で より有用にする上では、単純でありながら効果的な手法です。 \end{itemize} 数多くのオプションを扱うときには、オプションをグループ化すると ヘルプメッセージ出力をよりよくする上で便利です。\class{OptionParser} は複数のオプショングループを収めることができ、各グループは 複数のオプションを収めることができます。 上で定義されたパーザに続けて \class{OptionGroup} を追加するのは 簡単です: \begin{verbatim} 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) \end{verbatim} このコードは以下のヘルプ出力になります: \begin{verbatim} 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. \end{verbatim} \subsubsection{バージョン番号を出力する \label{optparse-print-version}} 要約された使用法メッセージ文字列と同様に、\module{optparse} は プログラムのバージョン文字列を出力できます。これを行うには、 \var{version} 引数を \class{OptionParser} に文字列で渡さなければ なりません: \begin{verbatim} parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0") \end{verbatim} ``\%prog'' が \var{usage} とまったく同じように展開されることに注意して ください。またこれとは別に、\var{version} には何でも必要なものを 入れることができます。\var{version} を指定すると、\module{optparse} は自動的に \longprogramopt{version} オプションをパーザに追加します。 コマンドライン上でこのオプションが見つかると、 \var{version} 文字列を (``\%prog'' を置換して) 展開し、標準出力に 出力してから終了します。 例えば、スクリプトが /usr/bin/foo という名前なら、ユーザは以下のように するはずです: \begin{verbatim} $ /usr/bin/foo --version foo 1.0 $ \end{verbatim} \subsubsection{エラー処理 \label{optparse-error-handling}} 基本的な使い方をする上でもう一つ知っておかなければならないのは、 \module{optparse} がコマンドライン上でエラーに遭遇した --- 例えば、\programopt{-n} が整数値のオプションの時に \programopt{-n4x} が指定された --- ときに、どのように振舞うかということです。 \module{optparse} は標準エラー出力に使用法メッセージを出力し、 有用かつ人間が読めるエラーメッセージを続けます。その後、 プログラムをゼロでない終了状態で終了し (\function{sys.exit()} を 呼び出し) ます。 この動作が気に入らないなら、\class{OptionParser} をサブクラスして \method{error()} メソッドを上書きしてください。 ~\ref{optparse-extending} 節、``\module{optparse} を拡張する'' を参照してください。 \subsubsection{全てをつなぎ合わせる \label{optparse-basic-summary}} \module{optparse} を使った私のスクリプトがだいたいどのようになって いるかを以下に示します: \begin{verbatim} from optparse import OptionParser ... def main (): usage = "usage: %prog [options] arg" parser = OptionParser(usage) parser.add_option("-f", "--file", type="string", dest="filename", help="read data from FILENAME") parser.add_option("-v", "--verbose", action="store_true", dest="verbose") parser.add_option("-q", "--quiet", action="store_false", dest="verbose") # more options ... (options, args) = parser.parse_args() if len(args) != 1: parser.error("incorrect number of arguments") if options.verbose: print "reading %s..." % options.filename # go to work ... if __name__ == "__main__": main() \end{verbatim} \subsection{進んだ使い方 \label{optparse-advanced-usage}} ここからはリファレンスのドキュメントです。まだ ~\ref{optparse-basic-usage} 節の基本的なドキュメントを読んでいない なら、まず読んでください。 \subsubsection{パーザを生成してオプションを追加する \label{optparse-creating-the-parser}} パーザにオプションを加えていく方法はいくつかあります。一つ \class{Options} からなるリストを \class{OptionParser} のコンストラクタ に渡す方法です: \begin{verbatim} parser = OptionParser(option_list=[ make_option("-f", "--filename", action="store", type="string", dest="filename"), make_option("-q", "--quiet", action="store_false", dest="verbose")]) \end{verbatim} (\function{make_option()} は \class{Option} クラスの別名、 すなわち \class{Option} のコンストラクタを呼び出すだけです。 \module{optparse} の将来のバージョンでは、おそらく \class{Option} を 複数のクラスに分割し、 \function{make_option()} は正しいクラスを 取り出してインスタンス化するファクトリ関数になるはずです。) 長い形式のオプションリストについては、リストを別に生成する方が しばしば便利です: \begin{verbatim} option_list = [make_option("-f", "--filename", action="store", type="string", dest="filename"), # 17 other options ... make_option("-q", "--quiet", action="store_false", dest="verbose")] parser = OptionParser(option_list=option_list) \end{verbatim} また、\class{OptionParser} の \method{add_option()} メソッドを 使って、オプションを一つ一つ追加することもできます: \begin{verbatim} parser = OptionParser() parser.add_option("-f", "--filename", action="store", type="string", dest="filename") parser.add_option("-q", "--quiet", action="store_false", dest="verbose") \end{verbatim} このメソッドは \class{Option} コンストラクタが発行する例外を 簡単に追跡できるようにします。例外が発生するのはよくあることで、 これは数多くのキーワード引数間で複雑な相互依存関係が発生する ためです --- うまく指定がされていない場合、\module{optparse} は \exception{OptionError} を発行します。 \method{add_option()} は以下の二つの方法のいずれかで呼び出す ことができます: \begin{itemize} \item (\function{make_option()} が返すような) \class{Option} インスタンスを渡す 。 \item \function{make_option()} (すなわち \class{Option} の コンストラクタ) が受理できるような固定引数およびキーワード引数の 組み合わせを渡し、 \class{Option} インスタンスを生成する (上述)。 \end{itemize} \subsubsection{オプションを定義する \label{optparse-defining-options}} 各 \class{Option} インスタンスは、同じ意味を持つ一群のコマンドライン オプション、すなわち同じ意味と効果をもつが、つづりが異なるような オプションを表します。任意の数の短いオプションと長いオプションを 指定することができますが、少なくとも一つのオプション文字列を与え なければなりません。 短い形式のオプション文字列を一つだけもつオプションを定義するには 以下のようにします: \begin{verbatim} make_option("-f", ...) \end{verbatim} 長い形式のオプション文字列を一つだけもつオプションを定義するには 以下のようにします: \begin{verbatim} make_option("--foo", ...) \end{verbatim} ``...'' は、\class{Option} オブジェクトの属性を定義する一群の キーワード引数を表しています。ある \class{Option} に対してどのような キーワードを与えれば十分かという問題はかなり複雑です (信じられない というなら、\class{Option} の数々の \method{_check_*()} メソッド群を 調べてみてください) が、だいたい \emph{何がしか} 指定しなければ なりません。うまく指定されていなければ、\module{optparse} は \exception{OptionError} 例外を発行し、犯した間違いを説明してくれます。 オプションの中でもっとも重要な属性はアクション、すなわちコマンドライン 中でそのオプションが見つかったときにどうするかを決める属性です。 とりうるアクションを以下に挙げます: \begin{definitions} \term{store} [default] このオプションに対する引数を値として保存します。 \term{store_const} 定数値を保存します。 \term{store_true} 真を表す値を保存します。 \term{store_false} 偽を表す値を保存します。 \term{append} このオプションに対する引数をリストに追加します。 \term{count} カウンタを 1 増やします。 \term{callback} 指定された関数を呼び出します。 \term{help} 全てのオプションとそれに対するドキュメントを含めた、使用法メッセージ を出力します。 \end{definitions} (アクションを指定しなければ、デフォルト値は ``store'' になります。 このアクションでは、 \var{type} と \var{dest} キーワードを 与えることができます; 以下を参照してください。) ご覧のとおり、ほとんどのアクションは何らかの値を保存したり 更新したりする処理を含んでいます。\module{optparse} はこの処理の ために、常に特定のオブジェクト(\class{Values} クラスのインスタンス) を生成します。オプション引数 (とその他数々の値) は、 \function{make_option()}/\method{add_option()} の引数 \var{dest} (目的変数) に従って、このオブジェクトの属性として保存されます。 例えば、以下の呼び出し: \begin{verbatim} parser.parse_args() \end{verbatim} を行うと、\module{optparse} は最初に行うことの一つとして、 \var{values} オブジェクトを生成します: \begin{verbatim} values = Values() \end{verbatim} このパーザのオプションの一つが、以下: \begin{verbatim} make_option("-f", "--file", action="store", type="string", dest="filename") \end{verbatim} のように定義されており、解析しているコマンドライン中に以下: \begin{verbatim} -ffoo -f foo --file=foo --file foo \end{verbatim} の文字列が含まれていれば、\module{optparse} は \programopt{-f} や \longprogramopt{file} オプションを見つけた際に、以下のコード: \begin{verbatim} values.filename = "foo" \end{verbatim} と同じ処理を行います。 明らかに、\var{type} と \var{dest} 引数は (大抵) \var{action} と ほぼ同じくらい大事なものです。 \var{action} は *全ての* オプションで 意味をなす唯一の属性ですが、最も重要な属性でもあります。 \subsubsection{オプションに対するアクション \label{optparse-option-actions}} オプションに対する様々なアクションは全て、わずかに異なる要求事項と 効果を持っています。 ``help'' アクションを除き、\class{Option}を 生成する際には少なくとも一つの別のキーワード引数を指定する必要があります; 各アクションに対する厳密な要求事項を以下に挙げます。 \begin{definitions} \term{store} [relevant: \var{type}, \var{dest}, \var{nargs}, \var{choices}] オプションの後には必ず引数が続き、\var{type} に従った値に変換されて \var{dest} に保存されます。\var{nargs} > 1 の場合、複数の引数が コマンドラインから取り出されます; 引数は全て \var{type} に従って 変換され、\var{dest} にタプルとして保存されます。 以下の ~\ref{optparse-option-types} 節、 ``オプションの型'' を 参照してください。 \var{choices} を指定 (文字列のリストかタプル) していれば、 型のデフォルト値は ``choice'' になります。 \var{type} が指定されなければ、デフォルト値は ``string'' になります。 \var{dest} が指定されない場合、 \module{optparse} は目的変数 を最初の長い形式のオプション文字列から導出します (例えば、 \longprogramopt{foo-bar} -> \var{foo_bar})。長い形式のオプション文字列 がない場合、\module{optparse} は最初の短い形式のオプションから 目的変数名を導出します (例えば \programopt{-f} -> \var{f})。 例: \begin{verbatim} make_option("-f") make_option("-p", type="float", nargs=3, dest="point") \end{verbatim} 以下のコマンド: \begin{verbatim} -f foo.txt -p 1 -3.5 4 -fbar.txt \end{verbatim} を与えると、 \module{optparse} は以下のように変数を設定します: \begin{verbatim} values.f = "bar.txt" values.point = (1.0, -3.5, 4.0) \end{verbatim} (実際のところ、 \member{values.f} は二度値設定されますが、 最終的には二回目の設定値だけが読み取れます。) \term{store_const} [required: \var{const}, \var{dest}] \class{Option} コンストラクタに与えられた \var{const} 値が \var{dest} に保存されます。 例: \begin{verbatim} make_option("-q", "--quiet", action="store_const", const=0, dest="verbose"), make_option("-v", "--verbose", action="store_const", const=1, dest="verbose"), make_option(None, "--noisy", action="store_const", const=2, dest="verbose"), \end{verbatim} \longprogramopt{noisy} がなければ、 \module{optparse} は以下のように 値を設定します: \begin{verbatim} values.verbose = 2 \end{verbatim} \term{store_true} [required: \var{dest}] ``store_const'' の特殊なケースで、真値 (厳密には整数の 1) を \var{dest} に保存します。 \term{store_false} [required: \var{dest}] ``store_true'' と同じですが、偽値 (整数の 0) を保存します。 例: \begin{verbatim} make_option(None, "--clobber", action="store_true", dest="clobber") make_option(None, "--no-clobber", action="store_false", dest="clobber") \end{verbatim} \term{append} [relevant: \var{type}, \var{dest}, \var{nargs}, \var{choices}] オプションの後ろには引数が一つ続かなければなりません。この引数は \var{dest} に入っているリストに追加されます。\var{dest} のデフォルト値が 指定されていない (すなわち、デフォルト値が Noneである) 場合、 \module{optparse} が最初にコマンドライン中にこのオプションを見つけた際に 空のリストが自動的に生成されます。 \samp{nargs > 1} であれば、複数の引数が取り出され、長さ \var{nargs} のタプルが \var{dest} に追加されます。 \var{type} と \var{dest} のデフォルト値は ``store'' アクションの値と 同じです。 例: \begin{verbatim} make_option("-t", "--tracks", action="append", type="int") \end{verbatim} \programopt{-t3} がコマンドライン上で見つかると、\module{optparse} は以下と等価な処理を行います: \begin{verbatim} values.tracks = [] values.tracks.append(int("3")) \end{verbatim} その後で \samp{--tracks=4} が見つかると、さらに以下の処理を行います: \begin{verbatim} values.tracks.append(int("4")) \end{verbatim} \module{optparse} が \samp{--tracks=x} のような指定をどのように 扱うかについての情報は、 ``エラー処理'' (~\ref{optparse-error-handling} 節) を参照してください。 \term{count} [required: \var{dest}] \var{dest} に保持されている整数値をインクリメント (1 増加) させます。 \var{dest} は (デフォルトの値を指定しない限り) 最初にインクリメントを 行う前にゼロに設定されます。 例: \begin{verbatim} make_option("-v", action="count", dest="verbosity") \end{verbatim} 最初に \programopt{-v} がコマンドライン上で見つかった際、 \module{optparse} は以下と等価な処理: \begin{verbatim} values.verbosity = 0 values.verbosity += 1 \end{verbatim} を行います。その後 \programopt{-v} が見つかると、さらに以下の処理: \begin{verbatim} values.verbosity += 1 \end{verbatim} を行います。 \term{callback} [required: \var{'callback'}; relevant: \var{type}, \var{nargs}, \var{callback_args}, \var{callback_kwargs}] \var{callback} に指定された関数を呼び出します。この関数の 用法は以下のようになっています: \begin{verbatim} func(option : Option, opt : string, value : any, parser : OptionParser, *args, **kwargs) \end{verbatim} callback オプションについての詳細は、~\ref{optparse-callback-options} 節、 ``callback オプション'' でカバーされています。 \term{help} [required: none] 現在のオプションパーザ内にある全てのオプション対する完全な ヘルプメッセージを出力します。ヘルプメッセージは \class{OptionParser} のコンストラクタに渡された \var{usage} 文字列と、各オプションに 渡された \var{help} 文字列から生成されます。 オプションに \var{help} 文字列が指定されていなくても、ヘルプメッセージ 中には列挙されます。オプションを完全に表示させないようにするには、 特殊な値 \constant{optparse.SUPPRESS_HELP} を使います。 例: \begin{verbatim} from optparse import Option, OptionParser, SUPPRESS_HELP usage = "usage: %prog [options]" parser = OptionParser(usage, option_list=[ make_option("-h", "--help", action="help"), make_option("-v", action="store_true", dest="verbose", help="Be moderately verbose") make_option("--file", dest="filename", help="Input file to read data from"), make_option("--secret", help=SUPPRESS_HELP) \end{verbatim} \module{optparse} がコマンドライン上に \longprogramopt{-h} または \longprogramopt{help} を見つけると、以下のようなヘルプメッセージを 標準出力に出力します: \begin{verbatim} usage: [options] options: -h, --help Show this help message and exit -v Be moderately verbose --file=FILENAME Input file to read data from \end{verbatim} ヘルプメッセージの出力後、\module{optparse} は \code{sys.exit(0)} でプロセスを終了します。 \term{version} [required: none] \class{OptionParser} に指定されているバージョン番号を標準出力に 出力して終了します。バージョン番号は、実際には \class{OptionParser} の\method{print_version()} メソッドで書式化されてから出力されます。 通常、 \class{OptionParser} のコンストラクタに \var{version} が指定されたときのみ関係のあるアクションです。 \end{definitions} \subsubsection{オプションの型\label{optparse-option-types}} \module{optparse} は 6 種類のすばらしいオプション型: \dfn{string} (文字列)、\dfn{int} (整数)、 \dfn{long} (長整数)、 \dfn{choice} (選択項目)、 \dfn{float} (浮動小数点数) および \dfn{complex} (複素数) をサポートしています。(この中で、string、 int、 float、および choice が最もよく使われます -- long と complex は主にオプション型を完全に そろえるするために存在しています。) 新たなオプションの型は、\class{Option} クラスをサブクラス化することで 簡単に追加できます; ~\ref{optparse-extending} 節、 ``\module{optparse} を拡張する'' を参照してください。 文字列オプションの引数は、チェックしたり変換したりはしません: コマンドライン上のテキストが目的変数にそのまま保存されます (または コールバックに渡されます)。 整数引数は \function{int()} に渡され、Python 整数に変換されます。 \function{int()} が失敗すると \module{optparse} も失敗に終わりますが、 より役に立つエラーメッセージを伴います。 内部的には、\module{optparse} は \function{optparse.check_builtin()} で \exception{OptionValueError} を発行します; より高水準 (\class{OptionParser} 内) では、この例外が捕捉され、 \module{optparse} はエラーメッセージを伴ってプログラムを停止させます。 同様に、浮動小数点数引数は \function{float()} 、 長整数引数は \function{long()} 、複素数引数は \function{complex()} に渡されて変換されます。それ以外では、値は整数引数の場合と同様に 扱われます。 選択項目オプションは文字列オプションのサブタイプです。 マスタリストや選択項目のリスト (文字列) はオプションコンストラクタ (\function{make_option()} や \method{OptionParser.add_option()}) に ``choices'' キーワード引数として渡されなければなりません。 選択項目オプション引数は \function{optparse.check_choice()} 内でマスタリストと比較され、マスタリストにない文字列が指定された 場合には \exception{OptionValueError} が発行されます。 \subsubsection{オプションパーザへのクエリと操作\label{optparse-querying-and-manipulating}} 自前のオプションパーザをつつきまわして、何が起こるかを調べると便利 なことがあります。\class{OptionParser} では便利な二つのメソッドを提供 しています: \begin{methoddesc}{has_option}{opt_str} \programopt{-q} や \longprogramopt{verbose} のようなオプション文字列 に対して、\class{OptionParser} がオプションに対応している場合に 真を返します。 \end{methoddesc} \begin{methoddesc}{get_option}{opt_str} 指定されたオプションを実装している \class{Option} インスタンスを 返します。実装されていなければ None を返します。 \end{methoddesc} \begin{methoddesc}{remove_option}{opt_str} \class{OptionParser} が \var{opt_str} に対するオプションを持っている 場合、そのオプションは削除されます。そのオプションが他の文字列で 指定することができる場合、それらのオプション文字列もすべて無効に なります。 \var{opt_str} がこの \class{OptionParser} オブジェクトのどのオプション にも属さない場合、\exception{ValueError} を発行します。 \end{methoddesc} \subsubsection{オプション間の衝突\label{optparse-conflicts}} 注意が足りないと、衝突するオプションを定義しやすくなります: \begin{verbatim} parser.add_option("-n", "--dry-run", ...) ... parser.add_option("-n", "--noisy", ...) \end{verbatim} (標準的なオプションを実装済みの \class{OptionParser} から自前の サブクラスを定義した場合にはさらによく起きます) \module{optparse} はこのような定義は通常間違いによるものだと仮定 しており、デフォルトでは例外 (\exception{OptionConflictError}) を 発行します。この誤りは簡単に修正できるプログラム上のエラーなので、 例外を catch しようとしないほうがせず --- 間違いを直しておくべき です。 時に、故意に新たなオプションで以前のオプションを置き換えたいこと があります。これは以下の呼び出し: \begin{verbatim} parser.set_conflict_handler("resolve") \end{verbatim} で行えます。この操作は \module{optparse} にオプションの衝突を 賢く解決するよう指示します。 からくりはこうなっています: オプションを追加するたびに、 \module{optparse} は以前に追加されたオプションとの衝突がないか 調べます。何らかの衝突が見つかると、\class{OptionParser} の コンストラクタでの指定: \begin{verbatim} parser = OptionParser(..., conflict_handler="resolve") \end{verbatim} か、\method{set_conflict_handler()} で指定されたいずれかの衝突処理 機構 (conflict-handling mechanism ) が起動されます。 デフォルトの衝突処理メカニズムは ``error'' です。その他の唯一の 選択肢は ``ignore'' で、これはバージョン 1.1 またはそれ以前の \module{optparse} の (おそらく壊れている) 挙動を修正します。 以下に例を示します: まず、衝突を解決するように設定された \class{OptionParser} を定義しましょう: \begin{verbatim} parser = OptionParser(conflict_handler="resolve") \end{verbatim} ここでオプションを全て定義します: \begin{verbatim} parser.add_option("-n", "--dry-run", ..., help="original dry-run option") ... parser.add_option("-n", "--noisy", ..., help="be noisy") \end{verbatim} この時点で、\module{optparse} は以前に追加されたオプションで すでに \programopt{-n} オプション文字列が使用されていることを 検出します。\code{conflict_handler == "resolve"} であるため、 この状況は \programopt{-n} を以前のオプションにおけるオプション 文字列リストから削除することによって解決します。こうして、 以前のオプションを有効にする方法は \longprogramopt{dry-run} だけと なります。ユーザがヘルプメッセージを要求すると、ヘルプ文字列は 上の結果を反映します。例えば以下のようになります: \begin{verbatim} options: --dry-run original dry-run option ... -n, --noisy be noisy \end{verbatim} 以前に追加されたオプション文字列を切り詰めていって何も残らない ようにすることは可能ですが、そのオプションをコマンドラインから 起動する手段がなくなってしまうので注意してください。この場合、 \module{optparse} はオプションを完全に除去してしまうので、 こうしたオプションはヘルプテキストやその他のいずれにも表示 されなくなります。例えば、現在の \class{OptionParser} で 続けると: \begin{verbatim} parser.add_option("--dry-run", ..., help="new dry-run option") \end{verbatim} この操作を行った時点で、最初の \programopt{-n}/\longprogramopt{dry-run} オプションはもはやアクセスできなくなり、\module{optparse} は 最初のオプションを除去します。ユーザがヘルプを要求すると、 以下のようなヘルプ: \begin{verbatim} options: ... -n, --noisy be noisy --dry-run new dry-run option \end{verbatim} を読むことになるでしょう。 \subsection{callback オプション\label{optparse-callback-options}} \module{optparse} の組み込みのアクションや型が望みにかなったもので なく、とはいえ \module{optparse} を拡張して独自のアクションや型を 定義するほどではない場合、おそらく callback オプションを定義する 必要があるでしょう。callback オプションの定義はきわめて簡単です; 注意を要するのは、よいコールバック関数 (callback function、 \module{optparse} がオプションをコマンドライン上に見つけた際に 呼び出される関数) を書くところです。 \subsubsection{callback オプションを定義する\label{optparse-defining-callback-option}} 例によって、コールバックオプションの定義は、直接 \class{Option} クラスをインスタンス化するか、\class{OptionParser} オブジェクト の \method{add_option()} メソッドを使うことで定義できます。 指定しなければならない属性は唯一 \var{callback} で、呼び出したい 関数を指定します: \begin{verbatim} parser.add_option("-c", callback=my_callback) \end{verbatim} ここでは関数オブジェクトを与えなければならないことに注意して ください --- つまり、callback オプションを定義する時点で、 関数 \function{my_callback()} はすでに定義済みにしていなければ なりません。上の単純なケースでは、 \module{optparse} は \programopt{-c} が必要とする引数について何の知識もありません。 通常、これはオプションが何ら引数をとらない -- コマンドライン上に \programopt{-c} が存在するかどうかだけが知りたいことの全てである -- ことを意味します。しかし、状況によっては、コールバック関数 が任意の数の引数をコマンドライン引数から取り出したいと思うかも しれません。 これがコールバック関数の記述を難しくしているところです; これについては本ドキュメントの後の方でカバーします。 オプションの属性を定義する際に指定できる属性はいくつかあります: \begin{definitions} \term{type} 通常の意味を持ちます: ``store'' や ``append'' アクションのように、 \module{optparse} に対して引数を一つ消費するように指示します。 この引数は \var{type} に変換できなければなりません。 \module{optparse} は値をどこかに保存する のではなく、\var{type} に変換してコールバック関数に渡します。 \term{nargs} これも通常の意味を持ちます: この属性が与えられ、\samp{nargs > 1} であるばあい、\module{optparse} は \var{nargs} 個の引数を取り出します。 各値は \var{type} に変換可能でなくてはなりません。その後、 変換された値からなるタプルがコールバック関数に渡されます。 \term{callback_args} コールバックに渡す外部の固定引数からなるタプルです。 \term{callback_kwargs} コールバックに渡す外部のキーワード引数です。 \end{definitions} \subsubsection{コールバック関数はどのように呼び出されるか \label{optparse-callbacks-called}} コールバックは全て以下のようにして呼び出されます: \begin{verbatim} func(option, opt, value, parser, *args, **kwargs) \end{verbatim} ここで、 \begin{definitions} \term{option} は、このコールバックを呼び出している \class{Option} のインスタンス です。 \term{opt} は、コールバック呼び出しのきっかけとなったコマンドライン上の オプション文字列です。(長形式のオプションに対する省略形が使われている 場合、\var{opt} は完全な、正式な形のオプション文字列となります --- 例えば、ユーザが \longprogramopt{foobar} の短縮形として \longprogramopt{foo} をコマンドラインに入力した時には、\var{opt} は \longprogramopt{foobar} となります。) \term{value} は、このオプションの引数で、コマンドライン上に見つかったものです。 \module{optparse} は、\var{type} が設定されている場合、 単一の引数しかとりません;\var{value} の型はオプションの型 (~\ref{optparse-option-types}, ``オプションの型'' 参照) で示された 型になります。このオプションに対する \var{type} が None である (引数はない) 場合、\var{value} は None になります。\samp{nargs > 1} なら、 \var{value} は適切な型をもつ値のタプルとなります。 \term{parser} は、現在のオプション解析の全てを駆動している \class{OptionParser} インスタンスです。主に、この値を介して、インスタンス属性としていくつかの 興味深いデータにアクセスできるために便利です: \begin{definitions} \term{parser.rargs} 現在未処理の引数からなるリスト、すなわち、\var{opt} (と、あれば \var{value} ) が除去され、それ以降の引数だけが 残っているリストです。\member{parser.rargs} の変更、例えば さらに引数を取り出すといった変更は、自由に行ってかまいません。 \term{parser.largs} 現在放置されている引数のセット、すなわち処理はされたが、 オプション (やオプションの引数) として取り出されてはいない 引数のセットです。\member{parser.largs} の変更、例えば さらに引数を追加するといった変更は、自由に行ってかまいません。 \term{parser.values} オプションの値がデフォルトで保存されるオブジェクトです。 この値は、コールバック関数がオプションの値を記憶するために、 他の\module{optparse} と同じ機構を使えるようにするので便利です; これでグローバル変数や閉包 (closure) を台無しにすることがありません。 コマンドライン上にすでに現れているオプションの値にアクセスすることも できます。 \end{definitions} \term{args} \var{callback_args} オプション属性で与えられた任意の固定引数 からなるタプルです。 \term{kwargs} \var{callback_args} オプション属性で与えられた任意のキーワード引数 からなるタプルです。 \end{definitions} \var{args} と \var{kwargs} は省略可能 (\var{callback_args} や \var{callback_kwargs} をコールバック定義の際に与えたときのみ 渡されます) なので、最小のコールバック関数定義は以下のようになります: \begin{verbatim} def my_callback (option, opt, value, parser): pass \end{verbatim} \subsubsection{エラー処理 \label{optparse-callback-error-handling}} オプションやその引数に関して問題が発生した場合、 コールバック関数は \exception{OptionValueError} を発行しなければ なりません。\module{optparse} はこの例外を捕捉し、プログラムを終了 します。このとき指定したエラーメッセージを標準出力に出力します。 メッセージは明快、簡潔、正確で、問題がみつかったオプションについて 触れなければなりません。そうでなければ、ユーザは指定したオプションの 何が問題なのか解決するのに苦労するでしょう。 \subsubsection{例 \label{optparse-callback-examples}} 以下に引数をとらず、単に見つかったオプションを記録するだけの コールバックオプションの例を示します: \begin{verbatim} def record_foo_seen (option, opt, value, parser): parser.saw_foo = 1 parser.add_option("--foo", action="callback", callback=record_foo_seen) \end{verbatim} もちろん、``store_true'' アクションを使っても同じことができます。 もう少し興味深い例もあります: \programopt{-a} がコマンドライン上に 見つかった事実を記録するが、\programopt{-b} が見つかると \programopt{-a} を消し去るというものです。 \begin{verbatim} def check_order (option, opt, value, parser): if parser.values.b: raise OptionValueError("can't use -a after -b") parser.values.a = 1 ... parser.add_option("-a", action="callback", callback=check_order) parser.add_option("-b", action="store_true", dest="b") \end{verbatim} このコールバックを同様のオプションに対して複数回使いたい (オプションが見つかるとフラグが設定されるが、\programopt{-b} が見つかると常に消し去られる) 場合、少しだけ作業する必要が あります: すなわち、エラーメッセージと設定されるフラグを 一般化しておかなければなりません。 \begin{verbatim} def check_order (option, opt, value, parser): if parser.values.b: raise OptionValueError("can't use %s after -b" % opt) setattr(parser.values, option.dest, 1) ... parser.add_option("-a", action="callback", callback=check_order, dest='a') parser.add_option("-b", action="store_true", dest="b") parser.add_option("-c", action="callback", callback=check_order, dest='c') \end{verbatim} もちろん、ここでは任意の条件を入れることができます --- できることは、 すでに定義されたオプションの値に対するチェックにとどまりません。 例えば、満月 (full moon) にならないと呼び出してはならないオプション があったとすると、やらなければならない作業は以下のようになります: \begin{verbatim} def check_moon (option, opt, value, parser): if is_full_moon(): raise OptionValueError("%s option invalid when moon full" % opt) setattr(parser.values, option.dest, 1) ... parser.add_option("--foo", action="callback", callback=check_moon, dest="foo") \end{verbatim} (is_full_moon() の定義は読者の練習用に残しておきます。) \strong{固定個の引数} 決まった数の引数をとるような callback オプションを定義する際には、 状況は少し興味深いものとなります。callback オプションが引数を とるよう定義する操作は ``store'' や ``append'' オプションと同様です: \var{type} を定義すると、オプションは単一の引数をとり、この値は 指定された型に変換可能でなくてはなりません; 加えて \var{nargs} を定義すると、オプションは指定数の引数をとるようになります。 標準的な ``store'' アクションをエミュレートするだけの例を以下に 示します: \begin{verbatim} def store_value (option, opt, value, parser): setattr(parser.values, option.dest, value) ... parser.add_option("--foo", action="callback", callback=store_value, type="int", nargs=3, dest="foo") \end{verbatim} \module{optparse} は 3 つの引数を取り出し、整数に変換しようと配慮 することに気をつけてください; これらの値を保存する必要があります (あるいは、何らかの処理を行う必要があります: 明らかに、この例 ではコールバックを使う必要はありません。想像力を働かせてください！) \strong{可変個の引数} オプションが可変個の引数をとるようにしたいのなら、状況はやや 困難になります。この場合、コールバックを書かなければなりません; \module{optparse} では可変個の引数に対する組み込みの機能は まったく提供していません。このため、慣習的な \UNIX{} コマンドライン 解析のための本格的な書法を扱わなくてはなりません。 (以前は、\module{optparse} はこの問題に対する配慮を行っていましたが、 これは不具合がありました。この不具合は、この種のコールバックを より複雑にすることで修正されました。) とりわけ、コールバックでは、裸の \longprogramopt{} や \programopt{-} 引数のことを考えなければなりません; やりかたは以下のようになります: \begin{itemize} \item 裸の \longprogramopt{} が存在し、何らかのオプションの引数で ない場合、コマンドライン処理を停止させ、\longprogramopt{} 自体は消失します。 \item 裸の \programopt{-} も同様にコマンドライン処理を停止させますが、 \programopt{-} 自体は残されます。 \item \longprogramopt{} か \programopt{-} のいずれかがオプションに 対する引数となり得ます。 \end{itemize} オプションが可変個の引数をとるようにさせたいなら、いくつかの 巧妙で厄介な問題に配慮しなければなりません。どういう実装を とるかは、アプリケーションでどのようなトレードオフを考慮するか によります (このため、\module{optparse} では可変個の引数に 関する問題を直接的に取り扱わないのです)。 とはいえ、可変個の引数をもつオプションに対するスタブ (stub、仲介 インタフェース) を以下に示しておきます: \begin{verbatim} def varargs (option, opt, value, parser): assert value is None done = 0 value = [] rargs = parser.rargs while rargs: arg = rargs[0] # Stop if we hit an arg like "--foo", "-a", "-fx", "--file=f", # etc. Note that this also stops on "-3" or "-3.0", so if # your option takes numeric values, you will need to handle # this. if ((arg[:2] == "--" and len(arg) > 2) or (arg[:1] == "-" and len(arg) > 1 and arg[1] != "-")): break else: value.append(arg) del rargs[0] setattr(parser.values, option.dest, value) ... parser.add_option("-c", "--callback", action="callback", callback=varargs) \end{verbatim} この実装固有の弱点は、\programopt{-c} 以後に続いて負の数を表す 引数があった場合、\programopt{-c} の引数ではなく次のオプションとして 解釈されるということです。この問題の修正は読者の練習課題として おきます。 \subsection{\module{optparse} を拡張する \label{optparse-extending}} \module{optparse} がコマンドラインオプションを解析する手法における 二つの主要な制御要素は、各オプションに対するアクションと型です。 このため、ほとんどの拡張の方向性は、新たなアクションか型の追加に なっています。 また、拡張例の節には \module{optparse} に対する異なったやり方での 拡張を実演したものが収められています: 例えば、大小文字の区別 をしないオプションパーザや、``必須オプション'' を実装している 二種類のオプションパーザです。 \subsubsection{新たな型を追加する \label{optparse-adding-types}} 新たな型を追加するには、\module{optparse} の \class{Option} クラス から自前のサブクラスを定義する必要があります。 このクラスは \module{optparse} の型を定義する二つの属性: \member{TYPES} と \member{TYPE_CHECKER} を持っています。 \member{TYPES} は型の名前からなるタプルです; サブクラスでは、 標準のタプルに基づいて新たなタプル \member{TYPES} を定義するだけです。 \member{TYPE_CHECKER} は型の名前を型チェック関数に対応付ける辞書 です。型チェック関数は以下の形式をとります: \begin{verbatim} def check_foo (option : Option, opt : string, value : string) -> foo \end{verbatim} この関数はどんな名前にしてもよく、どんな型を返すようにもできます。 型チェック関数が返す値は \method{OptionParser.parse_args()} が返す \class{OptionValues} インスタンスになるか、\var{value} パラメタと してコールバック関数に渡されます。 自前の型チェック関数が問題に遭遇した場合、\exception{OptionValueError} を発行しなければなりません。\exception{OptionValueError} は単一の 文字列引数をとり、この引数はそのまま \class{OptionParser} の \method{error()} メソッドに渡されます。 \method{error()} メソッドは プログラム名と文字列 ``error:'' を渡された文字列の前に付け、 プロセスを終了する前に全てを標準エラー出力に出力します。 以下のつまらない例では、コマンドライン上の Python 形式の複素数を解析 するために ``複素数 (complex)'' 型を追加する操作を実演します。 (この例は今ではさらにつまらなくなっていましました。というのは、 \module{optparse} 1.3 からは組み込みで [純粋に完備性のためだけに] 複素数のサポートが追加されるようになったからです。ですが、気にしない ことにします。) まず、必要な import を行います: \begin{verbatim} from copy import copy from optparse import Option, OptionValueError \end{verbatim} まず型チェック関数を定義する必要があります。というのは、型チェック 関数は後で (自前の \class{Option} サブクラスにおける \member{TYPE_CHECKER} 属性で) 参照されるからです: \begin{verbatim} def check_complex (option, opt, value): try: return complex(value) except ValueError: raise OptionValueError( "option %s: invalid complex value: %r" % (opt, value)) \end{verbatim} 最後に、\class{Option} サブクラスを定義します: \begin{verbatim} class MyOption (Option): TYPES = Option.TYPES + ("complex",) TYPE_CHECKER = copy(Option.TYPE_CHECKER) TYPE_CHECKER["complex"] = check_complex \end{verbatim} (\member{Option.TYPE_CHECKER} の \function{copy()} を作成しなければ、 \module{optparse} の \class{Option} クラスにおける \member{TYPE_CHECKER} 属性を変更するだけで済みます。 Python では、良いマナーと常識以外にこうした省略をとどめるものは ありません。) これで完成です！もう、新たなオプション型を使うようなスクリプトを 他の \module{optparse} ベースのスクリプトと同じように書くことができます。 ただし、\class{OptionParser} に \class{Option} ではなく \class{MyOption} を使うように指示しなければなりません: \begin{verbatim} parser = OptionParser(option_class=MyOption) parser.add_option("-c", action="store", type="complex", dest="c") \end{verbatim} 別の方法として、自前のオプションリストを構築して、 \class{OptionParser} に渡すこともできます; 上の方法で \method{add_option()} を使わなければ、\class{OptionParser} に どのオプションクラスを使うかを教える必要はありません: \begin{verbatim} option_list = [MyOption("-c", action="store", type="complex", dest="c")] parser = OptionParser(option_list=option_list) \end{verbatim} \subsubsection{新たなアクションを追加する\label{optparse-adding-actions}} アクションの追加は少しだけ厄介です。というのは、\module{optparse} がアクションを二種類に分類していることを理解しなければならないからです: \begin{definitions} \term{"store" アクション} 結果的に \module{optparse} の OptionValues インスタンスの属性に値を 保存することになるアクションです; このアクションをとるオプションは Option のコンストラクタに 'dest' 属性を指定する必要があります。 \term{"typed" アクション} コマンドラインから値をとり、それが特定の型か、あるいは特定の型に 変換される文字列になるはずのアクションです。このアクションをとる オプションは Option のコンストラクタに 'type' 属性を指定する必要があります。 \end{definitions} デフォルトの ``store'' アクションには、``store''、 ``store_const''、 ``append''、および ``count'' があります。デフォルトの ``typed'' アクションは、``store''、 ``append''、および ``callback'' です。 アクションを追加する際、 アクションが ``store''、``typed''、 どちらでもない、両方である、のいずれか決めなければなりません。 \class{Option} (または \class{Option} サブクラス) の3つのクラス属性 がこの決定を制御します: \begin{memberdesc}{ACTIONS} すべてのアクションは ACTIONS に文字列で列挙されていなければなりません。 \end{memberdesc} \begin{memberdesc}{STORE_ACTIONS} "store" 系のアクションはここに列挙されていなければなりません。 \end{memberdesc} \begin{memberdesc}{TYPED_ACTIONS} "typed" 系のアクションはここに列挙されていなければなりません。 \end{memberdesc} 自前の新たなアクションを実際に実装するには、\class{Option} の \method{take_action()} メソッドを上書きして、自前のアクションを 認識する場合を追加しなければなりません。 例として、``extend'' アクションを追加してみましょう。このアクションは 標準の ``append'' アクションに似ていますが、コマンドラインから単一の 値をとって既存のリストに追加する代わりに、 ``extend'' では コンマで区切られた単一の文字列から複数の値をとり、既存のリストに 追加します。すなわち、\longprogramopt{names} が ``extend'' のタイプの オプション文字列であれば、以下のコマンドライン: \begin{verbatim} --names=foo,bar --names blah --names ding,dong \end{verbatim} は以下のリスト: \begin{verbatim} ["foo", "bar", "blah", "ding", "dong"] \end{verbatim} になります。 再び \class{Option} のサブクラスを定義します: \begin{verbatim} class MyOption (Option): ACTIONS = Option.ACTIONS + ("extend",) STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",) TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",) def take_action (self, action, dest, opt, value, values, parser): if action == "extend": lvalue = value.split(",") values.ensure_value(dest, []).extend(lvalue) else: Option.take_action( self, action, dest, opt, value, values, parser) \end{verbatim} 以下のことに注意します: \begin{itemize} \item ``extend'' は値をコマンドラインから要求し、その値をどこかへ 保存するという両方の操作を行うので、\member{STORE_ACTIONS} と \member{TYPED_ACTIONS} の両方に相当します。 \item \method{MyOption.take_action()} ではこの新しいアクションだけを 実装し、標準の\method{Option.take_action()} で \module{optparse} アクションへ 制御を戻します。 \item \var{values} は \class{Values} クラスのインスタンスで、 非常に便利な \method{ensure_value()} メソッドを提供しています。 \method{ensure_value()} は実質的には安全値 (safety value) のある \function{getattr()} です; このメソッドは以下のようにして 呼び出されます: \begin{verbatim} values.ensure_value(attr, value) \end{verbatim} \end{itemize} \var{values} の \member{attr} 属性が存在しないか、または None の 場合、\method{ensure_value()} は属性の値を \var{value} に設定して から \var{value} を返します。この機能は ``extend''、 ``append''、 および ``count'' で便利です。というのは、これらのアクションは すべて、データを変数に蓄積し、その変数が特定の型であるはず (最初の二つはリストで、最後の一つは整数) だからです。 \method{ensure_value()} を使うことで、アクションを使う スクリプトにおいて、オプションの目的変数にデフォルトの値を設定 するよう配慮しなくてよくなります; こうした目的変数はデフォルトを None にしておいてよく、\method{ensure_value()} が必要なときに 正しい値にするよう面倒を見ることになります。 \subsubsection{拡張を行う他の理由 \module{optparse}\label{optparse-extending-other-reasons}} 新たな型やアクションの追加は、\module{optparse} を拡張しようと考える 大きな、かつ明白な理由です。その他に少なくとも二つの分野がかかわって くると考えています。 一つ目の理由は簡単なものです: \class{OptionParser} は必要に応じて、 すなわちコマンドラインにエラーが生じたときはユーザがヘルプを要求 した際に \function{sys.exit()} を呼び出して役に立とうとします。 前者の場合、スクリプトをクラッシュさせてトレースバックを出力する 伝統的なやり方は受け入れがたいものです; このような応答を行うと、 ユーザはコマンドラインエラーを起こしたときにスクリプトにバグが あるのだと考えさせてしまいます。後者の場合、一般的にはヘルプを 出力した後に継続する利点はあまりありません。 この動作が目障りなら、 ``修正'' するのはさほど難しいことでは ありません。以下の実装をおこなわねばなりません。 \begin{enumerate} \item OptionParser をサブクラス化して error() メソッドを上書きします \item Option をサブクラス化して take_action() メソッドを上書きします --- アクション "help" の処理を自前で提供し、sys.exit() を呼ばない 用にする必要があるでしょう \end{enumerate} もう一つの理由は、より複雑ですが、\module{optparse} で実装されている コマンドライン文法をオーバライドするということです。 この場合、オプションに対するアクションと型の機構はすべて捨ておき、 \var{sys.argv} を処理するコードを上書きします。 いずれの場合も、\class{OptionParser} をサブクラス化する必要があります; どれくらい徹底的に書き換えたいかによって、 \method{parse_args()}、 \method{_process_long_opt()}、および \method{_process_short_opts()} について、一つからすべてのメソッド を上書きする必要があるでしょう。 これらは両方とも、読者の練習課題として残しておきます。 実は私は両方とも自分では書いたことがありません。というのも、 \module{optparse} のデフォルトの (自然な) 動作で十分ハッピーで いられるからです。 Happy hacking、 そしてこの言葉を忘れないでください: ルークよ、source を使え (Use the Source, Luke)。 \subsubsection{拡張の例 \label{optparse-extending-examples}} 以下に \module{optparse} モジュールを拡張する例をいくつか示します。 まず、オプション解析で大小文字の区別をしないように変更しましょう: \verbatiminput{caseless.py} 次に、 \module{optparse} で ``必須オプション'' を実装する方法を二つ 挙げます。 その 1: アプリケーションが引数を解析した後に必ず呼び出すメソッドを \class{OptionParser} に追加します: \verbatiminput{required_1.py} その 2: \class{Option} を拡張して \member{required} 属性を追加します; \class{OptionParser} を拡張して、必須オプションが引数解析語に存在する ことを確認させます: \verbatiminput{required_2.py}