pytho****@googl*****
pytho****@googl*****
2011年 3月 10日 (木) 16:23:35 JST
Revision: 2711931525 Author: INADA Naoki <inada****@klab*****> Date: Wed Mar 9 23:21:55 2011 Log: Update to 2.6.6: library/optparse.rst http://code.google.com/p/python-doc-ja/source/detail?r=2711931525 Modified: /library/optparse.rst ======================================= --- /library/optparse.rst Sun Nov 14 15:57:39 2010 +++ /library/optparse.rst Wed Mar 9 23:21:55 2011 @@ -11,12 +11,15 @@ .. sectionauthor:: Greg Ward <gward****@pytho*****> -:mod:`optparse` モジュールは、昔からある ``getopt`` よりも簡便で、柔軟性に 富み、かつ強力なコマンドライン解析ライブラリです。 -:mod:`optparse` では、より明快なスタイルのコマンドライン解析手法、すなわ ち :class:`OptionParser` -のインスタンスを作成してオプションを追加してゆき、そのインスタンスでコマン ドラインを解析するという手法をとっています。 ``optparse`` -を使うと、GNU/POSIX 構文でオプションを指定できるだけでなく、使用法やヘルプ メッセージの生成も行えます。 - -:mod:`optparse` を使った簡単なスクリプト例を以下に示します:: +:mod:`optparse` モジュールは、昔からある :mod:`getopt` よりも簡便で、 +柔軟性に富み、かつ強力なコマンドライン解析ライブラリです。 +:mod:`optparse` では、より宣言的なスタイルのコマンドライン解析手法、すなわ ち +:class:`OptionParser` のインスタンスを作成してオプションを追加してゆき、そ の +インスタンスでコマンドラインを解析するという手法をとっています。 +:mod:`optparse` を使うと、GNU/POSIX 構文でオプションを指定できるだけでな く、 +使用法やヘルプメッセージの生成も行えます。 + +:mod:`optparse` を使った簡単なスクリプトの例を以下に示します。 :: from optparse import OptionParser @@ -30,15 +33,19 @@ (options, args) = parser.parse_args() -このようにわずかな行数のコードによって、スクリプトのユーザはコマンドライン 上で例えば以下のような「よくある使い方」を実行できるようになります:: +このようにわずかな行数のコードによって、スクリプトのユーザはコマンドライン 上で +例えば以下のような「よくある使い方」を実行できるようになります。 :: <yourscript> --file=outfile -q -コマンドライン解析の中で、 ``optparse`` はユーザの指定したコマンドライン引 数値に応じて :meth:`parse_args` の返す +コマンドライン解析の中で、 :mod:`optparse` はユーザの指定した +コマンドライン引数値に応じて :meth:`parse_args` の返す ``options`` の属性値を設定してゆきます。 :meth:`parse_args` がコマンドライ ン解析から処理を戻したとき、 ``options.filename`` は ``"outfile"`` に、 ``options.verbose`` は ``False`` -になっているはずです。 ``optparse`` は長い形式と短い形式の両方のオプション 表記をサポートしており、 -短い形式は結合して指定できます。また、様々な形でオプションに引数値を関連付 けられます。従って、以下のコマンドラインは全て上の例と同じ意味になります:: +になっているはずです。 :mod:`optparse` は長い形式と短い形式の両方のオプショ ン表記をサポートしており、 +短い形式は結合して指定できます。 +また、様々な形でオプションに引数値を関連付けられます。 +従って、以下のコマンドラインは全て上の例と同じ意味になります。 :: <yourscript> -f outfile --quiet <yourscript> --quiet --file outfile @@ -50,7 +57,9 @@ <yourscript> -h <yourscript> --help -のいずれかを実行すると、 :mod:`optparse` はスクリプトのオプションについて簡 単にまとめた内容を出力します:: +のいずれかを実行すると、 :mod:`optparse` はスクリプトのオプションについて簡 単にまとめた内容を出力します。 + +.. code-block:: text usage: <yourscript> [options] @@ -109,12 +118,16 @@ オプション引数 (option argument) あるオプションの後ろに続く引数で、そのオプションに密接な関連をもち、オプ ションと同時に引数リストから取り出されます。 :mod:`optparse` - では、オプション引数は以下のように別々の引数にできます:: + では、オプション引数は以下のように別々の引数にできます。 + + .. code-block:: text -f foo --file foo - また、一つの引数中にも入れられます:: + また、一つの引数中にも入れられます。 + + .. code-block:: text -ffoo --file=foo @@ -131,9 +144,7 @@ 必須のオプション (required option) コマンドラインで与えなければならないオプションです; 「必須なオプション (required option)」という語は、英語では矛盾した言葉です。 :mod:`optparse` - では必須オプションの実装を妨げてはいませんが、とりたてて実装上役立つこと もしていません。 :mod:`optparse` - で必須オプションを実装する方法は、 :mod:`optparse` ソースコード配布物中 の ``examples/required_1.py`` や - ``examples/required_2.py`` を参照してください。 + では必須オプションの実装を妨げてはいませんが、とりたてて実装上役立つこと もしていません。 例えば、下記のような架空のコマンドラインを考えてみましょう:: @@ -242,8 +253,10 @@ * オプションの解析後に残った固定引数からなるリスト ``args`` 。 -このチュートリアルの節では、最も重要な四つのオプション属 性: :attr:`action`, :attr:`type`, :attr:`dest` -(destination), および :attr:`help` についてしか触れません。このうち最も重要 なのは :attr:`action` です。 +このチュートリアルの節では、最も重要な四つのオプション属性: +:attr:`~Option.action`, :attr:`~Option.type`, :attr:`~Option.dest` +(destination), :attr:`~Option.help` についてしか触れません。 +このうち最も重要なのは :attr:`~Option.action` です。 .. _optparse-understanding-option-actions: @@ -338,16 +351,16 @@ この他にも、 :mod:`optparse` は以下のようなアクションをサポートしています: -``store_const`` +``"store_const"`` 定数値を保存します。 -``append`` +``"append"`` オプションの引数を指定のリストに追加します。 -``count`` +``"count"`` 指定のカウンタを 1 増やします。 -``callback`` +``"callback"`` 指定の関数を呼び出します。 これらのアクションについては、 :ref:`optparse-reference-guide` 節の「リファ レンスガイド」および @@ -400,7 +413,8 @@ ^^^^^^^^^^^^ :mod:`optparse` にはヘルプと使い方の説明 (usage text) を生成する機能があ り、 -ユーザに優しいコマンドラインインタフェースを作成する上で役立ちます。やらな ければならないのは、各オプションに対する :attr:`help` の値と、 +ユーザに優しいコマンドラインインタフェースを作成する上で役立ちます。 +やらなければならないのは、各オプションに対する :attr:`~Option.help` の値 と、 必要ならプログラム全体の使用法を説明する短いメッセージを与えることだけで す。 ユーザフレンドリな (ドキュメント付きの) オプションを追加し た :class:`OptionParser` を以下に示します:: @@ -414,7 +428,7 @@ 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"), + metavar="FILE", help="write output to FILE") parser.add_option("-m", "--mode", default="intermediate", help="interaction mode: novice, intermediate, " @@ -422,7 +436,9 @@ :mod:`optparse` がコマンドライン上で ``"-h"`` や ``"--help"`` を 見つけた場合や、 :meth:`parser.print_help` を呼び出した場合、こ の :class:`OptionParser` -は以下のようなメッセージを標準出力に出力します:: +は以下のようなメッセージを標準出力に出力します。 + +.. code-block:: text usage: <yourscript> [options] arg1 arg2 @@ -498,7 +514,9 @@ .. This would result in the following help output:: -この結果のヘルプ出力は次のようになります。 :: +この結果のヘルプ出力は次のようになります。 + +.. code-block:: text usage: [options] arg1 arg2 @@ -537,6 +555,30 @@ のようになります。 +.. The following two methods can be used to print and get the ``version`` string: + +以下の2つのメソッドを、 ``version`` 文字列を表示するために利用できます。 + +.. method:: OptionParser.print_version(file=None) + + .. Print the version message for the current program (``self.version``) to + *file* (default stdout). As with :meth:`print_usage`, any occurrence + of ``"%prog"`` in ``self.version`` is replaced with the name of the current + program. Does nothing if ``self.version`` is empty or undefined. + + 現在のプログラムのバージョン (``self.version``) を *file* (デフォルト: stdout) + へ表示します。 :meth:`print_usage` と同じく、 ``self.version`` の中の全 ての + ``"%prog"`` が現在のプログラム名に置き換えられます。 + ``self.version`` が空文字列だだったり未定義だったときは何もしません。 + +.. method:: OptionParser.get_version() + + .. Same as :meth:`print_version` but returns the version string instead of + printing it. + + :meth:`print_version` と同じですが、バージョン文字列を表示する代わりに + 返します。 + .. _optparse-how-optparse-handles-errors: @@ -545,13 +587,16 @@ :mod:`optparse` を使う場合に気を付けねばならないエラーには、大きく分けてプ ログラマ側のエラーとユーザ側のエラーという二つの種類があります。 プログラマ側のエラーの多くは、例えば不正なオプション文字列や定義されていな いオプション属性の指定、あるいはオプション属性を指定し忘れるといった、 -誤った ``parser.add_option()`` 呼び出しによるものです。 -こうした誤りは通常通りに処理されます。すなわち、例外 (``optparse.OptionError`` や :exc:``TypeError``) -を送出して、プログラムをクラッシュさせます。もっと重要なのはユーザ側のエ ラーの処理です。というのも、ユーザの操作エラーという\ +誤った ``OptionParser.add_option()`` 呼び出しによるものです。 +こうした誤りは通常通りに処理されます。すなわち、例外 (:exc:``optparse.OptionError`` や :exc:``TypeError``) +を送出して、プログラムをクラッシュさせます。 + +もっと重要なのはユーザ側のエラーの処理です。というのも、ユーザの操作エラー という\ ものはコードの安定性に関係なく起こるからです。 :mod:`optparse` は、誤ったオ プション引数の指定 (整数を引数にとるオプション :option:`-n` に対して ``"-n4x"`` と指定してしまうなど) や、引数を指定し忘れ た場合 (:option:`-n` が何らかの引数をとるオプションであるのに、 ``"-n"`` が引数の末尾に来ている 場合) といった、ユーザによるエラーを自動的に\ -検出します。また、アプリケーション側で定義されたエラー条件が起きた場合、 ``parser.error()`` を呼び出してエラーを通知できます:: +検出します。また、アプリケーション側で定義されたエラー条件が起きた場合、 +:func:``OptionParser.error()`` を呼び出してエラーを通知できます:: (options, args) = parser.parse_args() [...] @@ -576,10 +621,11 @@ foo: error: -n option requires an argument :mod:`optparse` は、常にエラーを引き起こしたオプションについて説明の入った エラーメッセージを生成するよう気を配ります; -従って、 ``parser.error()`` をアプリケーションコードから呼び出す場合にも、 同じようなメッセージになるようにしてください。 +従って、 :func:``OptionParser.error()`` をアプリケーションコードから呼び出 す場合にも、同じようなメッセージになるようにしてください。 :mod:`optparse` のデフォルトのエラー処理動作が気に入らないのな ら、 :class:`OptionParser` -をサブクラス化して、 :meth:`exit` かつ/または :meth:`error` をオーバライド する必要があります。 +をサブクラス化して、 :meth:`~OptionParser.exit` かつ/または +:meth:`~OptionParser.error` をオーバライドする必要があります。 .. _optparse-putting-it-all-together: @@ -625,9 +671,9 @@ parserを作る ^^^^^^^^^^^^^^^^^^^ -:mod:`optparse` を使う最初の一歩は OptionParser インスタンスを作ることで す。 :: - - parser = OptionParser(...) +:mod:`optparse` を使う最初の一歩は OptionParser インスタンスを作ることで す。 + +.. class:: OptionParser(...) OptionParser のコンストラクタの引数はどれも必須ではありませんが、いくつもの キーワード引数がオプションとして使えます。これらはキーワード引数と\ して渡さなければなりません。すなわち、引数が宣言されている順番に頼ってはい けません。 @@ -635,8 +681,8 @@ ``usage`` (デフォルト: ``"%prog [options]"``) プログラムが間違った方法で実行されるかまたはヘルプオプションを付けて 実行された場合に表示される使用法です。 :mod:`optparse` は使用法の文\ 字列を表示する際に ``%prog`` を ``os.path.basename(sys.argv[0])`` (ま たは ``prog`` - キーワード引数が指定されていればその値) に展開します。使用法メッセー ジを抑制するためには特別な ``optparse.SUPPRESS_USAGE`` - という値を指定します。 + キーワード引数が指定されていればその値) に展開します。使用法メッセー ジを抑制するためには特別な + :data:``optparse.SUPPRESS_USAGE`` という値を指定します。 ``option_list`` (デフォルト: ``[]``) パーザに追加する Option オブジェクトのリストです。 ``option_list`` の 中のオプションは ``standard_option_list`` @@ -659,7 +705,7 @@ プログラムの概要を表す一段落のテキストです。 :mod:`optparse` はユーザ がヘルプを要求したときにこの概要を現在のターミナルの幅に合わせて\ 整形し直して表示します (``usage`` の後、オプションリストの前に表示さ れます)。 - ``formatter`` (デフォルト: 新しい IndentedHelpFormatter) + ``formatter`` (デフォルト: 新しい :class:`IndentedHelpFormatter`) ヘルプテキストを表示する際に使われる optparse.HelpFormatter のインス タンスです。 :mod:`optparse` はこの目的のためにすぐ使えるクラスを二つ提供しています。 IndentedHelpFormatter と TitledHelpFormatter がそれです。 @@ -671,6 +717,11 @@ ``usage`` や ``version`` の中の ``"%prog"`` を展開するときに ``os.path.basename(sys.argv[0])`` の代わりに使われる文字列です。 + ``epilog`` (default: ``None``) + + .. A paragraph of help text to print after the option help. + + オプションのヘルプの後に表示されるヘルプテキスト. .. _optparse-populating-parser: @@ -680,8 +731,8 @@ パーザにオプションを加えていくにはいくつか方法があります。 推奨するのは :ref:`optparse-tutorial` 節で示したような -``OptionParser.add_option()`` を使う方法です。 -:meth:`add_option` は以下の二つのうちいずれかの方法で呼び出せます: +meth:``OptionParser.add_option()`` を使う方法です。 +:meth:`add_option` は以下の二つのうちいずれかの方法で呼び出せます。 * (:func:`make_option` などが返す) :class:`Option` インスタンスを渡します。 @@ -716,63 +767,75 @@ 一つの :class:`Option` には任意の数のオプションを短い形式でも長い形式でも指 定できます。 ただし、少なくとも一つは指定せねばなりません。 -正しい方法で :class:`Option` インスタンスを生成するに は、 :class:`OptionParser` の :meth:`add_option` -を使います:: - - parser.add_option(opt_str[, ...], attr=value, ...) - -短い形式のオプション文字列を一つだけ持つようなオプションを生成するには:: - - parser.add_option("-f", attr=value, ...) - -のようにします。 - -また、長い形式のオプション文字列を一つだけ持つようなオプションの定義は:: - - parser.add_option("--foo", attr=value, ...) - -のようになります。 - -キーワード引数は新しい :class:`Option` オブジェクトの属性を定義します。オプ ションの属性のうちでもっとも重要なのは :attr:`action` -です。 :attr:`action` は他のどの属性と関連があるか、そしてどの属性が必要か に大きく作用します。関係のないオプション属性を指定したり、 -必要な属性を指定し忘れたりすると、 :mod:`optparse` は誤りを解説し た :exc:`OptionError` 例外を送出します。 - -コマンドライン上にあるオプションが見つかったときの :mod:`optparse` の振舞い を決定しているのは *アクション(action)* です。 -:mod:`optparse` でハードコードされている標準的なアクションには以下のような ものがあります: - -``store`` - オプションの引数を保存します (デフォルトの動作です) - -``store_const`` - 定数を保存します - -``store_true`` - 真 (:const:`True`) を保存します - -``store_false`` - 偽 (:const:`False`) を保存します - -``append`` - オプションの引数をリストに追加します - -``append_const`` - 定数をリストに追加します - -``count`` - カウンタを一つ増やします - -``callback`` - 指定された関数を呼び出します - -:attr:`help` - 全てのオプションとそのドキュメントの入った使用法メッセージを出力します。 - -(アクションを指定しない場合、デフォルトは ``store`` になります。このアクシ ョンでは、 :attr:`type` および :attr:`dest` -オプション属性を指定せねばなりません。下記を参照してください。) - -すでにお分かりのように、ほとんどのアクションはどこかに値を保存したり、値を 更新したりします。この目的のために、 :mod:`optparse` -は常に特別なオブジェクトを作り出し、それは通常 ``options`` と呼ばれます (``optparse.Values`` の -インスタンスになっています)。オプションの引数 (や、その他の様々な値) は、 :attr:`dest` (保存先: destination) +正しい方法で :class:`Option` インスタンスを生成するに は、 :class:`OptionParser` +の :meth:`add_option` を使います。 + +.. method:: OptionParser.add_option(opt_str[, ...], attr=value, ...) + + 短い形式のオプション文字列を一つだけ持つようなオプションを生成するには + 次のようにします。 :: + + parser.add_option("-f", attr=value, ...) + + + また、長い形式のオプション文字列を一つだけ持つようなオプションの定義は + 次のようになります。 :: + + parser.add_option("--foo", attr=value, ...) + + .. The keyword arguments define attributes of the new Option object. The most + important option attribute is :attr:`~Option.action`, and it largely + determines which other attributes are relevant or required. If you pass + irrelevant option attributes, or fail to pass required ones, :mod:`optparse` + raises an :exc:`OptionError` exception explaining your mistake. + + キーワード引数は新しい :class:`Option` オブジェクトの属性を定義します。 + オプションの属性のうちでもっとも重要なのは :attr:`~Option.action` です。 + この属性は、他のどの属性と関連があるか、そしてどの属性が必要かに大きく + 作用します。関係のないオプション属性を指定したり、必要な属性を指定し忘れ たり + すると、 :mod:`optparse` は誤りを解説した :exc:`OptionError` 例外を送出 します。 + + コマンドライン上にあるオプションが見つかったときの :mod:`optparse` の振 舞いを + 決定しているのは *アクション(action)* です。 :mod:`optparse` でハード コード + されている標準的なアクションには以下のようなものがあります: + + ``"store"`` + オプションの引数を保存します (デフォルトの動作です) + + ``"store_const"`` + 定数を保存します + + ``"store_true"`` + 真 (:const:`True`) を保存します + + ``"store_false"`` + 偽 (:const:`False`) を保存します + + ``"append"`` + オプションの引数をリストに追加します + + ``"append_const"`` + 定数をリストに追加します + + ``"count"`` + カウンタを一つ増やします + + ``"callback"`` + 指定された関数を呼び出します + + ``"help"`` + 全てのオプションとそのドキュメントの入った使用法メッセージを出力しま す。 + + (アクションを指定しない場合、デフォルトは ``"store"`` になります。 + このアクションでは、 :attr:`~Option.type` および :attr:`~Option.dest` + オプション属性を指定できます。 + :ref:`optparse-standard-option-actions` を参照してください。) + +すでにお分かりのように、ほとんどのアクションはどこかに値を保存したり、 +値を更新したりします。この目的のために、 :mod:`optparse` +は常に特別なオブジェクトを作り出し、それは通常 ``options`` と呼ばれます +(:class:`optparse.Values` のインスタンスになっています)。オプションの引数 +(や、その他の様々な値) は、 :attr:`~Option.dest` (保存先: destination) オプション属性に従って、 *options* の属性として保存されます。 例えば、 :: @@ -783,7 +846,7 @@ options = Values() -パーザ中で以下のようなオプション :: +パーザ中で以下のようなオプション :: parser.add_option("-f", "--file", action="store", type="string", dest="filename") @@ -800,8 +863,95 @@ と同等の処理を行います。 -:attr:`type` および :attr:`dest` オプション属性は :attr:`action` と同じくら い重要ですが、 *全ての* -オプションで意味をなすのは :attr:`action` だけなのです。 +:attr:`~Option.type` および :attr:`~Option.dest` オプション属性は +:attr:`~Option.action` と同じくらい重要ですが、 *全ての* +オプションで意味をなすのは :attr:`~Option.action` だけなのです。 + + +.. _optparse-option-attributes: + +オプション属性 +^^^^^^^^^^^^^^ + +以下のオプション属性は :meth:`parser.add_option` へのキーワード引数として渡 す +ことができます。特定のオプションに無関係なオプション属性を渡した場合、また は +必須のオプションを渡しそこなった場合、 :mod:`optparse` は :exc:`OptionError` +を送出します。 + +.. attribute:: Option.action + + (デフォルト: ``"store"``) + + このオプションがコマンドラインにあった場合に :mod:`optparse` に何を + させるかを決めます。 + 取りうるオプションについては + :ref:`こちら <optparse-standard-option-actions>` を参照してください。 + +.. attribute:: Option.type + + (デフォルト: ``"string"``) + + このオプションに与えられる引数の型 (たとえば ``"string"`` や ``"int"``) + です。 + 取りうるオプションについては + :ref:`こちら <optparse-standard-option-types>` を参照してください。 + +.. attribute:: Option.dest + + (デフォルト: オプション文字列を使う) + + このオプションのアクションがある値をどこかに書いたり書き換えたりを意味す る + 場合、これは :mod:`optparse` にその書く場所を教えます。詳しく言えば + :attr:`~Option.dest` には :mod:`optparse` がコマンドラインを解析しながら + 組み立てる ``options`` オブジェクトの属性の名前を指定します。 + +.. attribute:: Option.default + + コマンドラインに指定がなかったときにこのオプションの対象に使われる値で す。 + :meth:`OptionParser.set_defaults` も参照してください。 + +.. attribute:: Option.nargs + + (デフォルト: 1) + + このオプションがあったときに幾つの :attr:`~Option.type` 型の引数が + 消費されるべきかを指定します。 1 より大きい場合、 :mod:`optparse` は + :attr:`~Option.dest` に値のタプルを格納します。 + +.. attribute:: Option.const + + 定数を格納する動作のための、その定数です。 + +.. attribute:: Option.choices + + ``"choice"`` 型オプションに対してユーザが選べる選択肢となる文字列の + リストです。 + +.. attribute:: Option.callback + + アクションが ``"callback"`` であるオプションに対し、このオプションがあっ た + ときに呼ばれる呼び出し可能オブジェクトです。呼び出し時に渡される引数の + 詳細については、 :ref:`optparse-option-callbacks` を参照してください。 + +.. attribute:: Option.callback_args + Option.callback_kwargs + + ``callback`` に渡される標準的な4つのコールバック引数の後ろに追加する、 + 位置指定引数とキーワード引数。 + +.. attribute:: Option.help + + ユーザが :attr:`~Option.help` オプション(``"--help"`` のような)を指定 + したときに表示される、使用可能な全オプションのリストの中のこのオプション に + 関する説明文です。説明文を提供しておかなければ、オプションは説明文なしで 表示されます。 + オプションを隠すには特殊な値 :data:`optparse.SUPPRESS_HELP` を使います。 + +.. attribute:: Option.metavar + + (デフォルト: オプション文字列から) + + 説明文を表示する際にオプションの引数の身代わりになるものです。 + 例は :ref:`optparse-tutorial` 節を参照してください。 .. _optparse-standard-option-actions: @@ -809,23 +959,31 @@ 標準的なオプション・アクション ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -様々なオプション・アクションにはどれも互いに少しづつ異なった条件と作用があ ります。ほとんどのアクションに関連するオプション属性がいくつかあり、値を指定 して -:mod:`optparse` の挙動を操作できます; いくつかのアクションには必須の属性が あり、必ず値を指定せねばなりません。 - -* ``store`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] - - オプションの後には必ず引数が続きます。引数は :attr:`type` に従った値に変 換されて :attr:`dest` に保存されます。 *nargs* > 1 - の場合、複数の引数をコマンドラインから取り出します; 引数は全 て :attr:`type` に従って変換され、 :attr:`dest` - にタプルとして保存されます。下記の :ref:`optparse-standard-option-types` 節「標準のオプション型」を +様々なオプション・アクションにはどれも互いに少しづつ異なった条件と作用が +あります。ほとんどのアクションに関連するオプション属性がいくつかあり、 +値を指定して :mod:`optparse` の挙動を操作できます。いくつかのアクションには +必須の属性があり、必ず値を指定せねばなりません。 + +* ``"store"`` [関連: :attr:`~Option.type`, :attr:`~Option.dest`, + :attr:`~Option.nargs`, :attr:`~Option.choices`] + + オプションの後には必ず引数が続きます。引数は :attr:`~Option.type` に従っ て + 値に変換されて :attr:`~Option.dest` に保存されます。 + :attr:`~Option.nargs` > 1 の場合、複数の引数をコマンドラインから取り出し ます。 + 引数は全て :attr:`~Option.type` に従って変換され、 :attr:`~Option.dest` + にタプルとして保存されます。 :ref:`optparse-standard-option-types` 節を 参照してください。 - ``choices`` を(文字列のリストかタプルで) 指定した場合、型のデフォルト値 は "choice" になります。 - - :attr:`type` を指定しない場合、デフォルトの値は ``string`` です。 - - :attr:`dest` を指定しない場合、 :mod:`optparse` は保存先を最初の長い形式 のオプション文字列から導出します - (例えば、 ``"--foo-bar"`` は ``foo_bar`` になります)。長い形式のオプショ ン文字列がない場合、 :mod:`optparse` - は最初の短い形式のオプションから保存先の変数名を導出します (``"-f"`` は ``f`` になります)。 + :attr:`~Option.choices` を(文字列のリストかタプルで) 指定した場合、型の + デフォルト値は ``"choice"`` になります。 + + :attr:`~Option.type` を指定しない場合、デフォルトの値は ``"string"`` で す。 + + :attr:`~Option.dest` を指定しない場合、 :mod:`optparse` は保存先を最初の + 長い形式のオプション文字列から導出します + (例えば、 ``"--foo-bar"`` は ``foo_bar`` になります)。長い形式の + オプション文字列がない場合、 :mod:`optparse` は最初の短い形式のオプション + から保存先の変数名を導出します (``"-f"`` は ``f`` になります)。 例えば:: @@ -844,9 +1002,10 @@ のように設定を行います。 -* ``store_const`` [required: ``const``; relevant: :attr:`dest`] - - 値 ``cost`` を :attr:`dest` に保存します。 +* ``"store_const"`` [関連: :attr:`~Option.const`; 関連: + :attr:`~Option.dest`] + + 値 :attr:`~Option.cost` を :attr:`dest` に保存します。 例えば:: @@ -857,34 +1016,36 @@ parser.add_option("--noisy", action="store_const", const=2, dest="verbose") - とします。 - - ``"--noisy"`` が見つかると、 :mod:`optparse` は :: + とします。 ``"--noisy"`` が見つかると、 :mod:`optparse` は :: options.verbose = 2 のように設定を行います。 -* ``store_true`` [relevant: :attr:`dest`] - - ``store_const`` の特殊なケースで、真 (True) を :attr:`dest` に保存しま す。 - -* ``store_false`` [relevant: :attr:`dest`] - - ``store_true`` と同じですが、偽 (False) を保存します。 +* ``"store_true"`` [関連: :attr:`~Option.dest`] + + ``"store_const"`` の特殊なケースで、真 (True) を :attr:`dest` に保存しま す。 + +* ``"store_false"`` [関連::attr:`~Option.dest`] + + ``"store_true"`` と似ていて、偽 (False) を保存します。 例:: parser.add_option("--clobber", action="store_true", dest="clobber") parser.add_option("--no-clobber", action="store_false", dest="clobber") -* ``append`` [relevant: :attr:`type`, :attr:`dest`, ``nargs``, ``choices``] - - このオプションの後ろには必ず引数が続きます。引数は :attr:`dest` のリスト に追加されます。 :attr:`dest` - のデフォルト値を指定しなかった場合、 :mod:`optparse` がこのオプションを最 初にみつけた時点で空のリストを自動的に生成します。 ``nargs`` - > 1 の場合、複数の引数をコマンドラインから取り出し、長さ ``nargs`` のタプ ルを生成して :attr:`dest` に追加します。 - - :attr:`type` および :attr:`dest` のデフォルト値は ``store`` アクションと 同じです。 +* ``"append"`` [関連: :attr:`~Option.type`, :attr:`~Option.dest`, + :attr:`~Option.nargs`, :attr:`~Option.choices`] + + このオプションの後ろには必ず引数が続きます。引数は :attr:`~Option.dest` の + リストに追加されます。 :attr:`~Option.dest` のデフォルト値を指定しなかっ た場合、 + :mod:`optparse` がこのオプションを最初にみつけた時点で空のリストを自動的 に生成します。 + :attr:`~Option.nargs` > 1 の場合、複数の引数をコマンドラインから取り出 し、 + 長さ :attr:`~Option.nargs` のタプルを生成して :attr:`~Option.dest` に追加 します。 + + :attr:`~Option.type` および :attr:`~Option.dest` のデフォルト値は ``"store"`` + アクションと同じです。 例:: @@ -903,14 +1064,18 @@ を実行します。 -* ``append_const`` [required: ``const``; relevant: :attr:`dest`] - - ``store_const`` と同様ですが、 ``const`` の値は :attr:`dest` に追加 (append)されます。 ``append`` - の場合と同じように :attr:`dest` のデフォルトは ``None`` ですがこのオプシ ョンを最初にみつけた時点で空のリストを自動的に生成します。 - -* ``count`` [relevant: :attr:`dest`] - - :attr:`dest` に保存されている整数値をインクリメントします。 :attr:`dest` は (デフォルトの値を指定しない限り) +* ``"append_const"`` [関連: :attr:`~Option.const`; 関連: + :attr:`~Option.dest`] + + ``"store_const"`` と同様ですが、 :attr:`~Option.const` の値は + :attr:`~Option.dest` に追加(append)されます。 ``"append"`` + の場合と同じように :attr:`~Option.dest` のデフォルトは ``None`` + ですがこのオプションを最初にみつけた時点で空のリストを自動的に生成しま す。 + +* ``"count"`` [関連: :attr:`~Option.dest`] + + :attr:`~Option.dest` に保存されている整数値をインクリメントします。 + :attr:`~Option.dest` は (デフォルトの値を指定しない限り) 最初にインクリメントを行う前にゼロに設定されます。 例:: @@ -930,41 +1095,50 @@ を実行します。 -* ``callback`` [required: ``callback``; relevant: :attr:`type`, ``nargs``, - ``callback_args``, ``callback_kwargs``] - - ``callback`` に指定された関数を次のように呼び出します。 :: +* ``"callback"`` [必須: :attr:`~Option.callback`; 関連: + :attr:`~Option.type`, :attr:`~Option.nargs`, :attr:`~Option.callback_args`, + :attr:`~Option.callback_kwargs`] + + :attr:`~Option.callback` に指定された関数を次のように呼び出します。 :: func(option, opt_str, value, parser, *args, **kwargs) 詳細は、 :ref:`optparse-option-callbacks` 節を参照してください。 -* :attr:`help` - - 現在のオプションパーザ内の全てのオプションに対する完全なヘルプメッセージ を出力します。ヘルプメッセージは :class:`OptionParser` - のコンストラクタに渡した ``usage`` 文字列と、各オプションに渡し た :attr:`help` 文字列から生成します。 - - オプションに :attr:`help` 文字列が指定されていなくても、オプションは - ヘルプメッセージ中に列挙されます。オプションを完全に表示させないようにす るには、特殊な値 ``optparse.SUPPRESS_HELP`` - を使ってください。 - - :mod:`optparse` は全ての :class:`OptionParser` に自動的に :attr:`help` +* ``"help"`` + + 現在のオプションパーザ内の全てのオプションに対する完全なヘルプメッセージ を出力します。 + ヘルプメッセージは :class:`OptionParser` + のコンストラクタに渡した ``usage`` 文字列と、各オプションに渡した + :attr:`~Option.help` 文字列から生成します。 + + オプションに :attr:`~Option.help` 文字列が指定されていなくても、オプショ ンは + ヘルプメッセージ中に列挙されます。オプションを完全に表示させないようにす るには、 + 特殊な値 :data:`optparse.SUPPRESS_HELP` を使ってください。 + + :mod:`optparse` は全ての :class:`OptionParser` に自動的 に :attr:`~Option.help` オプションを追加するので、通常自分で生成する必要はありません。 例:: from optparse import OptionParser, SUPPRESS_HELP - parser = OptionParser() - parser.add_option("-h", "--help", action="help"), + # 通常、 help オプションは自動的に追加されますが、 + # add_help_option 引数を使って抑制することができます。 + parser = OptionParser(add_help_option=False) + + parser.add_option("-h", "--help", action="help") parser.add_option("-v", action="store_true", dest="verbose", help="Be moderately verbose") parser.add_option("--file", dest="filename", - help="Input file to read data from"), + help="Input file to read data from") parser.add_option("--secret", help=SUPPRESS_HELP) - :mod:`optparse` がコマンドライン上に ``"-h"`` または ``"--help"`` を見つ けると、以下のようなヘルプメッセージを - 標準出力に出力します (``sys.argv[0]`` は ``"foo.py"`` だとします):: + :mod:`optparse` がコマンドライン上に ``"-h"`` または ``"--help"`` を + 見つけると、以下のようなヘルプメッセージを標準出力に出力します + (``sys.argv[0]`` は ``"foo.py"`` だとします)。 + + .. code-block:: text usage: foo.py [options] @@ -973,76 +1147,18 @@ -v Be moderately verbose --file=FILENAME Input file to read data from - ヘルプメッセージの出力後、 :mod:`optparse` は ``sys.exit(0)`` でプロセス を終了します。 - -* ``version`` - - :class:`OptionParser` に指定されているバージョン番号を標準出力に出力して 終了します。バージョン番号は、実際には - :class:`OptionParser` の :meth:`print_version` メソッドで書式化されてから 出力されます。通常、 - :class:`OptionParser` のコンストラクタに *version* が指定されたときのみ関 係のあるアクションです。 :attr:`help` - オプションと同様、 :mod:`optparse` はこのオプションを必要に応じて自動的に 追加するので、 ``version`` オプションを作成する - ことはほとんどないでしょう。 - - -.. _optparse-option-attributes: - -オプション属性 -^^^^^^^^^^^^^^ - -以下のオプション属性は ``parser.add_option()`` へのキーワード引数として -渡すことができます。特定のオプションに無関係なオプション属性を渡した場合、 または必須のオプションを渡しそこなった場合、 :mod:`optparse` は -:exc:`OptionError` を送出します。 - -* :attr:`action` (デフォルト: ``"store"``) - - このオプションがコマンドラインにあった場合に :mod:`optparse` に何をさせる かを決めます。取りうるオプションについては既に説明しました。 - -* :attr:`type` (デフォルト: ``"string"``) - - このオプションに与えられる引数の型 (たとえば ``"string"`` や ``"int"``) です。取りうるオプションの型については既に説明しました。 - -* :attr:`dest` (デフォルト: オプション文字列から) - - このオプションのアクションがある値をどこかに書いたり書き換えたりを意味す る場合、これは :mod:`optparse` にその書く場所を教えます。詳しく言えば - :attr:`dest` には :mod:`optparse` がコマンドラインを解析しながら組み立て る ``options`` - オブジェクトの属性の名前を指定します。 - -* ``default`` (非推奨) - - コマンドラインに指定がなかったときにこのオプションの対象に使われる値で す。使用は推奨されません。代わりに ``parser.set_defaults()`` - を使ってください。 - -* ``nargs`` (デフォルト: 1) - - このオプションがあったときに幾つの :attr:`type` 型の引数が消費されるべき かを指定します。もし > 1 ならば、 :mod:`optparse` は - :attr:`dest` に値のタプルを格納します。 - -* ``const`` - - 定数を格納する動作のための、その定数です。 - -* ``choices`` - - ``"choice"`` 型オプションに対してユーザがその中から選べる文字列のリストで す。 - -* ``callback`` - - アクションが ``"callback"`` であるオプションに対し、このオプションがあっ たときに呼ばれる呼び出し可能オブジェクトです。 ``callable`` - に渡す引数の詳細については、 :ref:`optparse-option-callbacks` 節を参照し てください。 - -* ``callback_args``, ``callback_kwargs`` - - ``callback`` に渡される標準的な4つのコールバック引数の後ろに追加する位置 による引数またはキーワード引数です。 - -* :attr:`help` - - ユーザが :attr:`help` オプション(``"--help"`` のような)を指定したときに - 表示される使用可能な全オプションのリストの中のこのオプションに関する説明 文です。説明文を提供しておかなければ、オプションは説明文なしで表示されます。 - オプションを隠すには特殊な値 ``SUPPRESS_HELP`` を使います。 - -* ``metavar`` (デフォルト: オプション文字列から) - - 説明文を表示する際にオプションの引数の身代わりになるものです。例 は :ref:`optparse-tutorial` 節を参照してください。 + ヘルプメッセージの出力後、 :mod:`optparse` は ``sys.exit(0)`` で + プロセスを終了します。 + +* ``"version"`` + + :class:`OptionParser` に指定されているバージョン番号を標準出力に出力して + 終了します。バージョン番号は、実際には :class:`OptionParser` の + :meth:`print_version` メソッドで書式化されてから出力されます。 + 通常、 :class:`OptionParser` のコンストラクタに ``version`` 引数が指定さ れた + ときのみ関係のあるアクションです。 :attr:`~Option.help` オプションと同 様、 + :mod:`optparse` はこのオプションを必要に応じて自動的に追加するので、 + ``version`` オプションを作成することはほとんどないでしょう。 .. _optparse-standard-option-types: @@ -1050,14 +1166,14 @@ 標準のオプション型 ^^^^^^^^^^^^^^^^^^ -:mod:`optparse` には、 :dfn:`string` (文字列)、 :dfn:`int` (整数 )、 :dfn:`long` (長整数)、 -:dfn:`choice` (選択肢)、 :dfn:`float` (浮動小数点数) およ び :dfn:`complex` (複素数) の 6 -種類のオプション型があります。新たなオプションの型を追加したけれ ば、 :ref:`optparse-extending-optparse` +:mod:`optparse` には、 ``"string"``, ``"int"``, ``"long"``, ``"choice"``, +``"float"``, ``"complex"`` の 6 種類のビルトインのオプション型があります。 +新たなオプションの型を追加したければ、 :ref:`optparse-extending-optparse` 節を参照してください。 文字列オプションの引数はチェックや変換を一切受けません: コマンドライン上の テキストは保存先にそのまま保存されます (またはコールバックに渡されます)。 -整数引数 (``int`` 型や ``long`` 型) は次のように読み取られます。 +整数引数 (``"int"`` 型や ``"long"`` 型) は次のように読み取られます。 * 数が ``0x`` から始まるならば、16進数として読み取られます @@ -1068,15 +1184,19 @@ * それ以外の場合、数は10進数として読み取られます -変換は適切な底(2, 8, 10, 16 のどれか)とともに ``int()`` または ``long()`` を呼び出すことで行なわれます。 -この変換が失敗した場合 :mod:`optparse` の処理も失敗に終わりますが、より役に 立つエラーメッセージを出力します。 - -``float`` および ``complex`` のオプション引数は直接 ``float()`` や ``complex()`` で変換されます。 -エラーは同様の扱いです。 - -``choice`` オプションは ``string`` オプションのサブタイプです。 ``choice`` オプションの属性 (文字列からなるシーケンス) -には、利用できるオプション引数のセットを指定します。 ``optparse.check_choice()`` -はユーザの指定したオプション引数とマスタリストを比較して、無効な文字列が指 定された場合には :exc:`OptionValueError` を送出します。 +変換は適切な底(2, 8, 10, 16 のどれか)とともに :func:`int` また は :func:`long` +を呼び出すことで行なわれます。 +この変換が失敗した場合 :mod:`optparse` の処理も失敗に終わりますが、 +より役に立つエラーメッセージを出力します。 + +``"float"`` および ``"complex"`` のオプション引数は直接 :func:`float` や +:func:`complex` で変換されます。エラーは同様の扱いです。 + +``"choice"`` オプションは ``"string"`` オプションのサブタイプです。 +:attr:`~Option.choice` オプションの属性 (文字列からなるシーケンス) には、 +利用できるオプション引数のセットを指定しま す。 :func:`optparse.check_choice` +はユーザの指定したオプション引数とマスタリストを比較して、無効な文字列が +指定された場合には :exc:`OptionValueError` を送出します。 .. _optparse-parsing-arguments: @@ -1094,20 +1214,24 @@ 処理する引数のリスト (デフォルト: ``sys.argv[1:]``) ``values`` - オプション引数を格納するオブジェクト (デフォルト: 新しい optparse.Values のインスタンス) + オプション引数を格納する :class:`optparse.Values` のオブジェクト + (デフォルト: 新しい :class:`Values` のインスタンス) -- + 既存のオブジェクトを指定した場合、オプションのデフォルトは + 初期化されません。 であり、戻り値は ``options`` - ``values`` に渡されたものと同じオブジェクト、または :mod:`optparse` によ って生成された optparse.Values - インスタンス + ``values`` に渡されたものと同じオブジェクト、または :mod:`optparse` + によって生成された optparse.Values インスタンス ``args`` 全てのオプションの処理が終わった後で残った位置引数 です。 -一番普通の使い方は一切キーワード引数を使わないというものです。 ``options`` を指定した場合、それは繰り返される ``setattr()`` +一番普通の使い方は一切キーワード引数を使わないというものです。 +``values`` を指定した場合、それは繰り返される :func:`setattr` の呼び出し (大雑把に言うと保存される各オプション引数につき一回ずつ) で更新 されていき、 :meth:`parse_args` で返されます。 :meth:`parse_args` が引数リストでエラーに遭遇した場合、 OptionParser の :meth:`error` @@ -1120,38 +1244,67 @@ オプション解析器への問い合わせと操作 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -自前のオプションパーザをつつきまわして、何が起こるかを調べると便利なことが あります。 :class:`OptionParser` では便利な二つのメソッドを提供 -しています: オプションパーザのデフォルトの振る舞いは、ある程度カスタマイズすることがで きます。 また、オプションパーザの中を調べることもできます。 :class:`OptionParser` は幾つかのヘルパーメソッドを提供しています。 -``disable_interspersed_args()`` - オプションで無い最初の引数を見つけた時点でパースを止めるように設定しま す。 - 別のコマンドを実行するコマンドをプロセッサを作成する際、別のコマンドの\ - オプションと自身のオプションが混ざるのを防ぐために利用することができま す。 - 例えば、各コマンドがそれぞれ異なるオプションのセットを持つ場合などに有効 です。 - -``enable_interspersed_args()`` +.. method:: OptionParser.disable_interspersed_args() + + .. Set parsing to stop on the first non-option. For example, if ``"-a"`` and + ``"-b"`` are both simple options that take no arguments, :mod:`optparse` + normally accepts this syntax: + + オプションで無い最初の引数を見つけた時点でパースを止めるように設定しま す。 + 例えば、 ``"-a"`` と ``"-b"`` が両方とも引数を取らないシンプルなオプショ ン + だったとすると、 :mod:`optparse` は通常次の構文を受け付け、 :: + + prog -a arg1 -b arg2 + + .. and treats it as equivalent to : + + それを次と同じように扱います。 :: + + prog -a -b arg1 arg2 + + .. To disable this feature, call :meth:`disable_interspersed_args`. This + restores traditional Unix syntax, where option parsing stops with the first + non-option argument. + + この機能を無効にしたいときは、 :meth:`disable_interspersed_args` メソッ ドを + 呼び出してください。古典的な Unix システムのように、最初のオプションでな い + 引数を見つけたときにオプションの解析を止めるようになります。 + + .. Use this if you have a command processor which runs another command which has + options of its own and you want to make sure these options don't get + confused. For example, each command might have a different set of options. + + 別のコマンドを実行するコマンドをプロセッサを作成する際、別のコマンドの + オプションと自身のオプションが混ざるのを防ぐために利用することができま す。 + 例えば、各コマンドがそれぞれ異なるオプションのセットを持つ場合などに有効 です。 + +.. method:: OptionParser.enable_interspersed_args() + オプションで無い最初の引数を見つけてもパースを止めないように設定します。 オプションとコマンド引数の順序が混ざっても良いようになります。 - 例えば、 ``"-s arg1 --long arg2"`` というコマンドライン引数に対して、 - ``["arg1", "arg2"]`` とオプション ``-s --long`` を返します。 これはデフォルトの動作です。 -``has_option(opt_str)`` - :class:`OptionParser` に(``"-q"`` や ``"--verbose"`` のような) オプショ ン ``opt_str`` - がある場合、真を返します。 - -``get_option(opt_str)`` - オプション文字列 ``opt_str`` に対する :class:`Option` インスタンスを返し ます。該当するオプションがなければ ``None`` - を返します。 - -``remove_option(opt_str)`` +.. method:: OptionParser.get_option(opt_str) + + オプション文字列 ``opt_str`` に対する :class:`Option` インスタンスを + 返します。該当するオプションがなければ ``None`` を返します。 + +.. method:: OptionParser.has_option(opt_str) + + :class:`OptionParser` に(``"-q"`` や ``"--verbose"`` のような) オプショ ン + ``opt_str`` がある場合、真を返します。 + +.. method:: OptionParser.remove_option(opt_str) + :class:`OptionParser` に ``opt_str`` に対応するオプションがある場合、 - そのオプションを削除します。該当するオプションに他のオプション文字列が指 定されていた場合、それらのオプション文字列は全て無効になります。 - ``opt_str`` がこの :class:`OptionParser` オブジェクトのどのオプションに も属さない場合、 :exc:`ValueError` - を送出します。 + そのオプションを削除します。該当するオプションに他のオプション文字列が + 指定されていた場合、それらのオプション文字列は全て無効になります。 + *opt_str* がこの :class:`OptionParser` オブジェクトのどのオプションにも + 属さない場合、 :exc:`ValueError` を送出します。 .. _optparse-conflicts-between-options: @@ -1159,7 +1312,7 @@ オプション間の衝突 ^^^^^^^^^^^^^^^^^^ -注意が足りないと、衝突するオプションを定義しやすくなります:: +注意が足りないと、衝突するオプションを定義してしまうことがあります。 :: ***The diff for this file has been truncated for email.***
