optparse —コマンドラインオプションのパーサー

ソースコード： ：source： `Lib / optparse.py`

バージョン3.2以降非推奨： optparse モジュールは非推奨であり、これ以上開発されません。開発は argparse モジュールで続行されます。

optparse は、古い getopt モジュールよりも、コマンドラインオプションを解析するための便利で柔軟性のある強力なライブラリです。 optparse は、より宣言的なスタイルのコマンドライン解析を使用します。 OptionParser のインスタンスを作成し、オプションを入力して、コマンドラインを解析します。 optparse を使用すると、ユーザーは従来のGNU / POSIX構文でオプションを指定でき、さらに使用法とヘルプメッセージを生成できます。

簡単なスクリプトで optparse を使用する例を次に示します。

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=True,
                  help="don't print status messages to stdout")

(options, args) = parser.parse_args()

これらの数行のコードで、スクリプトのユーザーはコマンドラインで「通常のこと」を実行できるようになりました。次に例を示します。

<yourscript> --file=outfile -q

optparse は、コマンドラインを解析するときに、ユーザーが指定したコマンドライン値に基づいて、parse_args()によって返されるoptionsオブジェクトの属性を設定します。 parse_args()がこのコマンドラインの解析から戻ると、options.filenameは"outfile"になり、options.verboseはFalseになります。 optparse は、長いオプションと短いオプションの両方をサポートし、短いオプションをマージして、さまざまな方法でオプションを引数に関連付けることができます。したがって、次のコマンドラインはすべて上記の例と同等です。

<yourscript> -f outfile --quiet
<yourscript> --quiet --file outfile
<yourscript> -q -foutfile
<yourscript> -qfoutfile

さらに、ユーザーは次のいずれかを実行できます

<yourscript> -h
<yourscript> --help

optparse は、スクリプトのオプションの簡単な要約を出力します。

Usage: <yourscript> [options]

Options:
  -h, --help            show this help message and exit
  -f FILE, --file=FILE  write report to FILE
  -q, --quiet           don't print status messages to stdout

ここで、 yourscript の値は実行時に決定されます（通常はsys.argv[0]から）。

バックグラウンド

optparse は、単純な従来のコマンドラインインターフェイスを備えたプログラムの作成を促進するように明示的に設計されました。そのために、Unixで従来使用されている最も一般的なコマンドライン構文とセマンティクスのみをサポートします。これらの規則に慣れていない場合は、このセクションを読んでそれらをよく理解してください。

用語

引数

コマンドラインで入力され、シェルからexecl()またはexecv()に渡される文字列。 Pythonでは、引数はsys.argv[1:]の要素です（sys.argv[0]は実行中のプログラムの名前です）。 Unixシェルでも「単語」という用語を使用します。

sys.argv[1:]以外の引数リストに置き換えることが望ましい場合があるため、「argument」は「sys.argv[1:]の要素、またはsys.argv[1:]」。

オプション

プログラムの実行をガイドまたはカスタマイズするための追加情報を提供するために使用される引数。オプションにはさまざまな構文があります。従来のUnix構文は、ハイフン（“-”）の後に1文字が続きます。 -xまたは-F。また、従来のUnix構文では、複数のオプションを1つの引数にマージできます。 -x -Fは-xFと同等です。 GNUプロジェクトは、--の後に、ハイフンで区切られた一連の単語を導入しました。 --fileまたは--dry-run。これらは、 optparse によって提供される唯一の2つのオプション構文です。

世界が見ている他のいくつかのオプション構文は次のとおりです。

ハイフンとそれに続くいくつかの文字、例： -pf（これはではなく、複数のオプションが1つの引数にマージされるのと同じではありません）
ハイフンの後に単語全体が続きます。例： -file（これは技術的には前の構文と同等ですが、通常は同じプログラムでは表示されません）
プラス記号の後に1文字、数文字、または単語が続きます。例： +f、+rgb
スラッシュの後に文字、またはいくつかの文字、または単語が続きます。例： /f、/file

これらのオプション構文は optparse でサポートされておらず、サポートされることはありません。これは意図的なものです。最初の3つはどの環境でも非標準であり、最後の3つは、VMS、MS-DOS、またはWindowsのみを対象としている場合にのみ意味があります。

オプション引数

オプションに続く引数は、そのオプションと密接に関連しており、そのオプションがある場合は引数リストから消費されます。 optparse では、オプション引数はオプションとは別の引数に含めることができます。

-f foo
--file foo

または同じ引数に含まれています：

-ffoo
--file=foo

通常、特定のオプションは引数を取るか、または取りません。多くの人が「オプションのオプション引数」機能を望んでいます。つまり、一部のオプションは、見た場合は引数を取り、見なかった場合は取りません。 -aがオプションの引数を取り、-bが完全に別のオプションである場合、-abをどのように解釈するのでしょうか？このあいまいさのため、 optparse はこの機能をサポートしていません。

位置引数

オプションが解析された後、引数リストに残っているもの、つまりオプションとその引数が解析され、引数リストから削除された後。

必要なオプション

コマンドラインで指定する必要のあるオプション。「必須オプション」というフレーズは、英語では自己矛盾していることに注意してください。 optparse は、必要なオプションの実装を妨げるものではありませんが、それでもあまり役に立ちません。

たとえば、次の架空のコマンドラインについて考えてみます。

prog -v --report report.txt foo bar

-vと--reportはどちらもオプションです。 --reportが1つの引数を取ると仮定すると、report.txtはオプションの引数です。 fooとbarは位置引数です。

オプションは何ですか？

オプションは、プログラムの実行を調整またはカスタマイズするための追加情報を提供するために使用されます。明確でない場合、オプションは通常オプションです。プログラムは、オプションがまったくなくても問題なく実行できるはずです。（UnixまたはGNUツールセットからランダムなプログラムを選択します。オプションなしで実行しても意味がありますか？主な例外は、find、tar、およびddです。これらはすべて、非標準の構文と紛らわしいインターフェイスで正しく批判されているミュータントオッドボールです。）

多くの人々は、自分たちのプログラムに「必要なオプション」を持たせたいと思っています。考えてみてください。必要な場合は、オプションではありません！プログラムを正常に実行するために絶対に必要な情報がある場合、それが位置引数の目的です。

優れたコマンドラインインターフェイスデザインの例として、ファイルをコピーするための控えめなcpユーティリティを検討してください。宛先と少なくとも1つのソースを指定せずにファイルをコピーしようとしても、あまり意味がありません。したがって、cpを引数なしで実行すると、失敗します。ただし、オプションをまったく必要としない柔軟で便利な構文があります。

cp SOURCE DEST
cp SOURCE ... DEST-DIR

あなたはそれだけでかなり遠くまで行くことができます。ほとんどのcp実装には、ファイルのコピー方法を正確に微調整するための多数のオプションが用意されています。モードと変更時間を保持したり、シンボリックリンクをたどらないようにしたり、既存のファイルを壊す前に確認したりできます。しかし、これはいずれも、cpのコアミッションである、あるファイルを別のファイルにコピーすること、または複数のファイルを別のディレクトリにコピーすることを妨げるものではありません。

位置引数は何ですか？

位置引数は、プログラムが絶対に積極的に実行する必要のある情報に対するものです。

優れたユーザーインターフェイスには、絶対的な要件をできるだけ少なくする必要があります。プログラムを正常に実行するために17の異なる情報が必要な場合、ユーザーからその情報をどのように取得するかはそれほど重要ではありません。ほとんどの人は、プログラムを正常に実行する前に諦めて立ち去ります。。これは、ユーザーインターフェイスがコマンドライン、構成ファイル、またはGUIのいずれであっても当てはまります。ユーザーにこれほど多くの要求を行うと、ほとんどのユーザーは単に諦めます。

つまり、ユーザーが絶対に提供する必要のある情報の量を最小限に抑えるようにしてください。可能な限り、適切なデフォルトを使用してください。もちろん、プログラムを適度に柔軟にすることも必要です。それがオプションの目的です。繰り返しになりますが、それらが構成ファイルのエントリ、GUIの[設定]ダイアログのウィジェット、またはコマンドラインオプションであるかどうかは関係ありません。実装するオプションが多いほど、プログラムはより柔軟になり、より複雑になります。その実装はになります。もちろん、柔軟性が高すぎると欠点もあります。オプションが多すぎると、ユーザーを圧倒し、コードの保守が非常に困難になる可能性があります。

チュートリアル

optparse は非常に柔軟で強力ですが、ほとんどの場合、簡単に使用できます。このセクションでは、 optparse ベースのプログラムに共通するコードパターンについて説明します。

まず、OptionParserクラスをインポートする必要があります。次に、メインプログラムの早い段階で、OptionParserインスタンスを作成します。

from optparse import OptionParser
...
parser = OptionParser()

次に、オプションの定義を開始できます。基本的な構文は次のとおりです。

parser.add_option(opt_str, ...,
                  attr=value, ...)

各オプションには、-fや--fileなどの1つ以上のオプション文字列と、 optparse にそのオプションが発生したときに何を期待して何をするかを指示するいくつかのオプション属性があります。コマンドラインで。

通常、各オプションには1つの短いオプション文字列と1つの長いオプション文字列があります。例：

parser.add_option("-f", "--file", ...)

全体に少なくとも1つのオプション文字列がある限り、短いオプション文字列と長いオプション文字列を好きなだけ（ゼロを含めて）自由に定義できます。

OptionParser.add_option（）に渡されるオプション文字列は、事実上、その呼び出しによって定義されたオプションのラベルです。簡潔にするために、コマンドラインでオプションに遭遇することを頻繁に参照します。実際には、 optparse はオプション文字列に遭遇し、それらからオプションを検索します。

すべてのオプションを定義したら、 optparse にプログラムのコマンドラインを解析するように指示します。

(options, args) = parser.parse_args()

（必要に応じて、カスタム引数リストをparse_args()に渡すことができますが、それが必要になることはめったにありません。デフォルトではsys.argv[1:]を使用します。）

parse_args()は2つの値を返します。

options、すべてのオプションの値を含むオブジェクト-例： --fileが単一の文字列引数を取る場合、options.fileはユーザーが指定したファイル名になり、ユーザーがそのオプションを指定しなかった場合はNoneになります。
args、オプションの解析後に残った位置引数のリスト

このチュートリアルセクションでは、アクション、タイプ、宛先（宛先）、およびヘルプの4つの最も重要なオプション属性についてのみ説明します。これらの中で、アクションが最も基本的です。

オプションアクションを理解する

アクションは、 optparse に、コマンドラインでオプションが見つかったときに何をするかを指示します。 optparse にハードコードされた一連の固定アクションがあります。新しいアクションの追加は、セクション optparse の拡張で説明されている高度なトピックです。ほとんどのアクションは、 optparse に値を変数に格納するように指示します。たとえば、コマンドラインから文字列を取得し、それをoptionsの属性に格納します。

オプションアクションを指定しない場合、 optparse はデフォルトでstoreになります。

ストアアクション

最も一般的なオプションアクションはstoreです。これは、 optparse に次の引数（または現在の引数の残り）を取り、それが正しい型であることを確認して、次の場所に格納するように指示します。選択した目的地。

例えば：

parser.add_option("-f", "--file",
                  action="store", type="string", dest="filename")

次に、偽のコマンドラインを作成し、 optparse に解析を依頼しましょう。

args = ["-f", "foo.txt"]
(options, args) = parser.parse_args(args)

optparse がオプション文字列-fを検出すると、次の引数foo.txtを消費し、options.filenameに格納します。したがって、このparse_args()の呼び出しの後、options.filenameは"foo.txt"になります。

optparse でサポートされている他のオプションタイプには、intとfloatがあります。整数の引数を期待するオプションは次のとおりです。

parser.add_option("-n", type="int", dest="num")

このオプションには長いオプション文字列がないことに注意してください。これは完全に受け入れられます。また、デフォルトはstoreであるため、明示的なアクションはありません。

別の偽のコマンドラインを解析してみましょう。今回は、オプションの引数をオプションのすぐ上に詰め込みます。-n42（1つの引数）は-n 42（2つの引数）と同等であるため、コード

(options, args) = parser.parse_args(["-n42"])
print(options.num)

42を印刷します。

タイプを指定しない場合、 optparse はstringと見なされます。デフォルトのアクションがstoreであるという事実と組み合わせると、最初の例ははるかに短くなる可能性があります。

parser.add_option("-f", "--file", dest="filename")

宛先を指定しない場合、 optparse はオプション文字列から適切なデフォルトを判断します。最初の長いオプション文字列が--foo-barの場合、デフォルトの宛先はfoo_barです。 ]。長いオプション文字列がない場合、 optparse は最初の短いオプション文字列を調べます。-fのデフォルトの宛先はfです。

optparse には、組み込みのcomplexタイプも含まれています。タイプの追加については、セクション optparse の拡張で説明しています。

ブール（フラグ）オプションの処理

フラグオプション（特定のオプションが表示されたときに変数をtrueまたはfalseに設定する）は非常に一般的です。 optparse は、store_trueとstore_falseの2つの別々のアクションでそれらをサポートします。たとえば、verboseフラグが-vでオンになり、-qでオフになる場合があります。

parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose")

ここでは、同じ宛先を持つ2つの異なるオプションがありますが、これはまったく問題ありません。（これは、デフォルト値を設定するときに少し注意する必要があることを意味します。以下を参照してください。）

optparse がコマンドラインで-vを検出すると、options.verboseをTrueに設定します。 -qに遭遇すると、options.verboseはFalseに設定されます。

その他のアクション

optparse でサポートされているその他のアクションは次のとおりです。

"store_const": 定数値を格納します
"append": このオプションの引数をリストに追加します
"count": カウンターを1つインクリメントします
"callback": 指定された関数を呼び出す

これらについては、セクションリファレンスガイドおよびセクションオプションコールバックで説明されています。

デフォルト値

上記のすべての例では、特定のコマンドラインオプションが表示されたときに、いくつかの変数（「宛先」）を設定します。これらのオプションが表示されない場合はどうなりますか？デフォルトを指定しなかったため、すべてNoneに設定されています。これは通常は問題ありませんが、より詳細に制御したい場合もあります。 optparse を使用すると、各宛先にデフォルト値を指定できます。これは、コマンドラインが解析される前に割り当てられます。

まず、冗長で静かな例を考えてみましょう。 -qが表示されない限り、 optparse でverboseをTrueに設定する場合は、次のようにします。

parser.add_option("-v", action="store_true", dest="verbose", default=True)
parser.add_option("-q", action="store_false", dest="verbose")

デフォルト値は特定のオプションではなく destination に適用され、これら2つのオプションはたまたま同じ宛先を持っているため、これはまったく同じです。

parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose", default=True)

このことを考慮：

parser.add_option("-v", action="store_true", dest="verbose", default=False)
parser.add_option("-q", action="store_false", dest="verbose", default=True)

この場合も、verboseのデフォルト値はTrueになります。特定の宛先に指定された最後のデフォルト値は、カウントされる値です。

デフォルト値を指定するより明確な方法は、OptionParserのset_defaults()メソッドです。これは、parse_args()を呼び出す前にいつでも呼び出すことができます。

parser.set_defaults(verbose=True)
parser.add_option(...)
(options, args) = parser.parse_args()

前と同じように、特定のオプションの宛先に指定された最後の値がカウントされます。わかりやすくするために、両方ではなく、いずれかの方法でデフォルト値を設定してみてください。

ヘルプの生成

optparse のヘルプと使用法のテキストを自動的に生成する機能は、ユーザーフレンドリーなコマンドラインインターフェイスを作成するのに役立ちます。あなたがしなければならないのは、各オプションの 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()を呼び出すだけの場合、標準出力に次のように出力されます。

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]

（ヘルプ出力がヘルプオプションによってトリガーされた場合、 optparse はヘルプテキストの印刷後に終了します。）

optparse が可能な限り最高のヘルプメッセージを生成するのを助けるために、ここでは多くのことが行われています。

スクリプトは、独自の使用法メッセージを定義します。
```
usage = "usage: %prog [options] arg1 arg2"
```
optparse は、使用法文字列の%progを現在のプログラムの名前に展開します。 os.path.basename(sys.argv[0])。展開された文字列は、詳細なオプションのヘルプの前に出力されます。

使用法の文字列を指定しない場合、 optparse は、当たり障りのないが賢明なデフォルトである"Usage: %prog [options]"を使用します。これは、スクリプトが位置引数をとらない場合は問題ありません。
すべてのオプションはヘルプ文字列を定義し、行の折り返しについて心配する必要はありません。 optparse は行の折り返しを処理し、ヘルプ出力の見栄えを良くします。
値をとるオプションは、自動生成されたヘルプメッセージでこの事実を示します。「モード」オプションの場合：
```
-m MODE, --mode=MODE
```
ここで、「MODE」はメタ変数と呼ばれます。これは、ユーザーが-m / --modeに提供することが期待される引数を表します。デフォルトでは、 optparse は宛先変数名を大文字に変換し、それをメタ変数に使用します。たとえば、--filenameオプションがmetavar="FILE"を明示的に設定すると、この自動生成されたオプションの説明が作成されます。
```
-f FILE, --filename=FILE
```
ただし、これは単にスペースを節約するだけではありません。手動で記述されたヘルプテキストは、メタ変数FILEを使用して、セミフォーマル構文-f FILEと非公式のセマンティック記述「ファイルへの出力の書き込み」。これは、ヘルプテキストをより明確にし、エンドユーザーにとってより便利にするためのシンプルですが効果的な方法です。
デフォルト値を持つオプションは、ヘルプ文字列に%defaultを含めることができます。 optparse は、オプションのデフォルト値の str（）に置き換えます。オプションにデフォルト値がない場合（またはデフォルト値がNoneの場合）、%defaultはnoneに展開されます。

グループ化オプション

多くのオプションを扱う場合、ヘルプ出力を向上させるためにこれらのオプションをグループ化すると便利です。 OptionParser には複数のオプショングループを含めることができ、各グループには複数のオプションを含めることができます。

オプショングループは、クラス OptionGroup を使用して取得されます。

class optparse.OptionGroup(parser, title, description=None): どこ

パーサーは、グループが挿入される OptionParser インスタンスです。 タイトルはグループタイトルです 説明（オプション）は、グループの長い説明です

OptionGroup はOptionContainer（ OptionParser など）を継承するため、add_option()メソッドを使用してグループにオプションを追加できます。

すべてのオプションが宣言されると、 OptionParser メソッドadd_option_group()を使用して、グループが以前に定義されたパーサーに追加されます。

前のセクションで定義したパーサーを続行すると、 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: <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]

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

    -g                  Group option.

もう少し完全な例では、複数のグループを使用する場合があります。前の例を拡張します。

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)

group = OptionGroup(parser, "Debug Options")
group.add_option("-d", "--debug", action="store_true",
                 help="Print debug information")
group.add_option("-s", "--sql", action="store_true",
                 help="Print all SQL statements executed")
group.add_option("-e", action="store_true", help="Print every action done")
parser.add_option_group(group)

その結果、次の出力が得られます。

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]

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

    -g                  Group option.

  Debug Options:
    -d, --debug         Print debug information
    -s, --sql           Print all SQL statements executed
    -e                  Print every action done

特にオプショングループをプログラムで操作する場合のもう1つの興味深い方法は、次のとおりです。

OptionParser.get_option_group(opt_str): 短いまたは長いオプション文字列 opt_str が含まれる OptionGroup を返します（例： '-o'または'--option'）が属します。そのような OptionGroup がない場合は、Noneを返します。

バージョン文字列の印刷

簡単な使用法の文字列と同様に、 optparse もプログラムのバージョン文字列を出力できます。 OptionParserのversion引数として文字列を指定する必要があります。

parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")

%progは、usageと同じように展開されます。それとは別に、versionには好きなものを含めることができます。これを指定すると、 optparse は自動的に--versionオプションをパーサーに追加します。コマンドラインでこのオプションが検出されると、version文字列が展開され（%progを置き換えることにより）、stdoutに出力され、終了します。

たとえば、スクリプトの名前が/usr/bin/fooの場合：

$ /usr/bin/foo --version
foo 1.0

次の2つの方法を使用して、version文字列を印刷および取得できます。

OptionParser.print_version(file=None): 現在のプログラム（self.version）のバージョンメッセージをファイル（デフォルトの標準出力）に出力します。 print_usage（）と同様に、self.versionで%progが出現すると、現在のプログラムの名前に置き換えられます。 self.versionが空または未定義の場合、何もしません。

OptionParser.get_version(): print_version（）と同じですが、バージョン文字列を出力する代わりに返します。

optparse がエラーを処理する方法

optparse が心配しなければならないエラーには、プログラマーエラーとユーザーエラーの2つの大きなクラスがあります。プログラマーエラーは通常、 OptionParser.add_option（）への誤った呼び出しです。無効なオプション文字列、不明なオプション属性、欠落しているオプション属性など。これらは通常の方法で処理されます。例外（optparse.OptionErrorまたは TypeError のいずれか）を発生させ、プログラムをクラッシュさせます。

ユーザーエラーの処理は、コードがどれほど安定していても発生することが保証されているため、はるかに重要です。 optparse は、不正なオプション引数（-n 4xを渡す、-nは整数引数を取る）、引数の欠落（-n atコマンドラインの終わり。-nは任意のタイプの引数を取ります）。また、OptionParser.error()を呼び出して、アプリケーション定義のエラー状態を通知することもできます。

(options, args) = parser.parse_args()
...
if options.a and options.b:
    parser.error("options -a and -b are mutually exclusive")

いずれの場合も、 optparse はエラーを同じ方法で処理します。つまり、プログラムの使用法メッセージとエラーメッセージを標準エラーに出力し、エラーステータス2で終了します。

上記の最初の例を考えてみましょう。ここでは、ユーザーが4xを整数を取るオプションに渡します。

$ /usr/bin/foo -n 4x
Usage: foo [options]

foo: error: option -n: invalid integer value: '4x'

または、ユーザーが値をまったく渡さなかった場合：

$ /usr/bin/foo -n
Usage: foo [options]

foo: error: -n option requires an argument

optparse で生成されたエラーメッセージは、エラーに関係するオプションについて常に言及するように注意します。アプリケーションコードからOptionParser.error()を呼び出すときは、必ず同じことを行ってください。

optparse のデフォルトのエラー処理動作がニーズに合わない場合は、OptionParserをサブクラス化し、そのexit()および/またはerror()メソッドをオーバーライドする必要があります。

すべてを一緒に入れて

optparse ベースのスクリプトは通常次のようになります。

from optparse import OptionParser
...
def main():
    usage = "usage: %prog [options] arg"
    parser = OptionParser(usage)
    parser.add_option("-f", "--file", 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")
    ...
    (options, args) = parser.parse_args()
    if len(args) != 1:
        parser.error("incorrect number of arguments")
    if options.verbose:
        print("reading %s..." % options.filename)
    ...

if __name__ == "__main__":
    main()

リファレンスガイド

パーサーの作成

optparse を使用する最初のステップは、OptionParserインスタンスを作成することです。

class optparse.OptionParser(...): OptionParserコンストラクターには必須の引数はありませんが、いくつかのオプションのキーワード引数があります。常にキーワード引数として渡す必要があります。引数が宣言される順序に依存しないでください。

usage（デフォルト："%prog [options]"） プログラムが正しく実行されなかった場合、またはヘルプオプションを使用した場合に印刷する使用法の概要。 optparse が使用法文字列を出力すると、%progがos.path.basename(sys.argv[0])（または、そのキーワード引数を渡した場合はprog）に展開されます。使用法メッセージを抑制するには、特別な値optparse.SUPPRESS_USAGEを渡します。 option_list（デフォルト：[]） パーサーに入力するOptionオブジェクトのリスト。 option_listのオプションは、standard_option_listのオプション（OptionParserサブクラスによって設定される可能性のあるクラス属性）の後に追加されますが、バージョンまたはヘルプオプションの前に追加されます。非推奨。代わりに、パーサーを作成した後、 add_option（）を使用してください。 option_class（デフォルト：optparse.Option） add_option（）でパーサーにオプションを追加するときに使用するクラス。 version（デフォルト：None） ユーザーがバージョンオプションを指定したときに出力するバージョン文字列。 versionに真の値を指定すると、 optparse は単一のオプション文字列--versionでバージョンオプションを自動的に追加します。サブストリング%progは、usageの場合と同じように展開されます。 conflict_handler（デフォルト："error"） オプション文字列が競合するオプションがパーサーに追加された場合の処理を指定します。セクションオプション間の競合を参照してください。 description（デフォルト：None） プログラムの概要を説明するテキストの段落。 optparse は、この段落を現在の端末幅に合うように再フォーマットし、ユーザーがヘルプを要求したときに（usageの後、オプションのリストの前に）印刷します。 formatter（デフォルト：新しいIndentedHelpFormatter） ヘルプテキストの印刷に使用されるoptparse.HelpFormatterのインスタンス。 optparse は、この目的のために、IndentedHelpFormatterとTitledHelpFormatterの2つの具象クラスを提供します。 add_help_option（デフォルト：True） trueの場合、 optparse はヘルプオプション（オプション文字列-hおよび--helpを含む）をパーサーに追加します。 prog os.path.basename(sys.argv[0])の代わりにusageおよびversionで%progを展開するときに使用する文字列。 epilog（デフォルト：None） オプションヘルプの後に印刷するヘルプテキストの段落。

パーサーへの入力

パーサーにオプションを設定する方法はいくつかあります。推奨される方法は、セクション Tutorial に示すように、 OptionParser.add_option（）を使用することです。 add_option()は、次の2つの方法のいずれかで呼び出すことができます。

オプションインスタンスを渡します（make_option()によって返される）
make_option()（つまり、Optionコンストラクター）に受け入れられる位置引数とキーワード引数の任意の組み合わせを渡すと、Optionインスタンスが作成されます。

もう1つの方法は、次のように、事前に構築されたOptionインスタンスのリストをOptionParserコンストラクターに渡すことです。

option_list = [
    make_option("-f", "--filename",
                action="store", type="string", dest="filename"),
    make_option("-q", "--quiet",
                action="store_false", dest="verbose"),
    ]
parser = OptionParser(option_list=option_list)

（make_option()は、Optionインスタンスを作成するためのファクトリ関数です。現在、Optionコンストラクターのエイリアスです。 optparse の将来のバージョンでは、Optionがいくつかのクラスに分割される可能性があり、make_option()はインスタンス化する適切なクラスを選択します。オプションを直接インスタンス化しないでください。）

オプションの定義

各Optionインスタンスは、同義のコマンドラインオプション文字列のセットを表します。 -fおよび--file。短いオプション文字列または長いオプション文字列はいくつでも指定できますが、少なくとも1つの全体的なオプション文字列を指定する必要があります。

Optionインスタンスを作成する標準的な方法は、 OptionParser のadd_option()メソッドを使用することです。

OptionParser.add_option(option) OptionParser.add_option(*opt_str, attr=value, ...)

短いオプション文字列のみでオプションを定義するには：

parser.add_option("-f", attr=value, ...)

また、長いオプション文字列のみでオプションを定義するには、次のようにします。

parser.add_option("--foo", attr=value, ...)

キーワード引数は、新しいOptionオブジェクトの属性を定義します。最も重要なオプション属性は action であり、他のどの属性が関連しているか、または必要であるかを主に決定します。無関係なオプション属性を渡した場合、または必要な属性を渡さなかった場合、 optparse はOptionError例外を発生させて間違いを説明します。

オプションの action は、コマンドラインでこのオプションが検出されたときに optparse が何をするかを決定します。 optparse にハードコードされた標準オプションアクションは次のとおりです。

"store": このオプションの引数を格納します（デフォルト）
"store_const": 定数値を格納します
"store_true": ストアTrue
"store_false": ストアFalse
"append": このオプションの引数をリストに追加します
"append_const": リストに定数値を追加する
"count": カウンターを1つインクリメントします
"callback": 指定された関数を呼び出す
"help": すべてのオプションとそれらのドキュメントを含む使用法メッセージを印刷します

（アクションを指定しない場合、デフォルトは"store"です。このアクションでは、 type および dest オプション属性を指定することもできます。標準オプションアクションを参照してください。）

ご覧のとおり、ほとんどのアクションには、値をどこかに保存または更新することが含まれます。 optparse は常に、このための特別なオブジェクトを作成します。これは、従来はoptionsと呼ばれていました（たまたまoptparse.Valuesのインスタンスです）。オプション引数（およびその他のさまざまな値）は、 dest （宛先）オプション属性に従って、このオブジェクトの属性として格納されます。

たとえば、あなたが電話するとき

parser.parse_args()

optparse が最初に行うことの1つは、optionsオブジェクトを作成することです。

options = Values()

このパーサーのオプションの1つがで定義されている場合

parser.add_option("-f", "--file", action="store", type="string", dest="filename")

解析されるコマンドラインには、次のいずれかが含まれます。

-ffoo
-f foo
--file=foo
--file foo

次に、 optparse は、このオプションを確認すると、同等の処理を実行します

options.filename = "foo"

type および dest オプション属性は、 action とほぼ同じくらい重要ですが、 action だけがに意味があります。すべてのオプション。

オプション属性

次のオプション属性は、キーワード引数として OptionParser.add_option（）に渡すことができます。特定のオプションに関係のないオプション属性を渡した場合、または必要なオプション属性を渡さなかった場合、 optparse はOptionErrorを発生させます。

Option.action

（デフォルト："store"）

このオプションがコマンドラインに表示されたときの optparse の動作を決定します。使用可能なオプションは、ここに記載されています。

Option.type

（デフォルト："string"）

このオプションで期待される引数の型（例："string"または"int"）。使用可能なオプションタイプは、ここに記載されています。

Option.dest

（デフォルト：オプション文字列から派生）

オプションのアクションが値をどこかに書き込むか変更することを意味する場合、これは optparse に値を書き込む場所を指示します。は、コマンドラインを解析するときにビルドします。

Option.default: オプションがコマンドラインに表示されない場合に、このオプションの宛先に使用する値。 OptionParser.set_defaults（）も参照してください。

Option.nargs

（デフォルト：1）

このオプションが表示された場合、タイプタイプの引数をいくつ消費する必要がありますか。 > 1の場合、 optparse は値のタプルを dest に格納します。

Option.const: 定数値を格納するアクションの場合、格納する定数値。

Option.choices: タイプ"choice"のオプションの場合、ユーザーが選択できる文字列のリスト。

Option.callback: アクション"callback"のあるオプションの場合、このオプションが表示されたときに呼び出す呼び出し可能オブジェクト。呼び出し可能オブジェクトに渡される引数の詳細については、セクションオプションコールバックを参照してください。

Option.callback_args

Option.callback_kwargs

4つの標準コールバック引数の後にcallbackに渡す追加の位置引数とキーワード引数。

Option.help: ユーザーが help オプション（--helpなど）を指定した後、使用可能なすべてのオプションを一覧表示するときに、このオプション用に印刷するヘルプテキスト。ヘルプテキストが提供されていない場合、オプションはヘルプテキストなしでリストされます。このオプションを非表示にするには、特別な値optparse.SUPPRESS_HELPを使用します。

Option.metavar

（デフォルト：オプション文字列から派生）

ヘルプテキストを印刷するときに使用するオプション引数の代用。例については、セクションチュートリアルを参照してください。

標準オプションアクション

さまざまなオプションアクションはすべて、わずかに異なる要件と効果を持っています。ほとんどのアクションには、 optparse の動作をガイドするために指定できるいくつかの関連するオプション属性があります。いくつかには必須の属性があり、そのアクションを使用するオプションには指定する必要があります。

"store" [関連：タイプ、宛先、ナルグ、選択肢]

オプションの後に引数を続ける必要があります。引数は type に従って値に変換され、 dest に格納されます。 nargs > 1の場合、コマンドラインから複数の引数が消費されます。すべてタイプに従って変換され、タプルとして dest に格納されます。標準オプションタイプセクションを参照してください。

choices が指定されている場合（文字列のリストまたはタプル）、タイプはデフォルトで"choice"になります。

type が指定されていない場合、デフォルトで"string"になります。

dest が指定されていない場合、 optparse は最初の長いオプション文字列から宛先を取得します（たとえば、--foo-barはfoo_barを意味します）。長いオプション文字列がない場合、 optparse は最初の短いオプション文字列から宛先を取得します（たとえば、-fはfを意味します）。

例：
```
parser.add_option("-f")
parser.add_option("-p", type="float", nargs=3, dest="point")
```
コマンドラインを解析するとき
```
-f foo.txt -p 1 -3.5 4 -fbar.txt
```
optparse が設定されます
```
options.f = "foo.txt"
options.point = (1.0, -3.5, 4.0)
options.f = "bar.txt"
```

"store_const" [必須： const ; 関連：宛先]

値 const は dest に格納されます。

例：

parser.add_option("-q", "--quiet",
                  action="store_const", const=0, dest="verbose")
parser.add_option("-v", "--verbose",
                  action="store_const", const=1, dest="verbose")
parser.add_option("--noisy",
                  action="store_const", const=2, dest="verbose")

--noisyが表示されている場合、 optparse が設定されます

options.verbose = 2

"store_true" [関連：宛先]

Trueから dest を格納する"store_const"の特殊なケース。

"store_false" [関連：宛先]

"store_true"と同様ですが、Falseを格納します。

例：

parser.add_option("--clobber", action="store_true", dest="clobber")
parser.add_option("--no-clobber", action="store_false", dest="clobber")

"append" [関連：タイプ、宛先、ナルグ、選択肢]

オプションの後には、 dest のリストに追加される引数を続ける必要があります。 dest のデフォルト値が指定されていない場合、 optparse がコマンドラインでこのオプションを最初に検出したときに、空のリストが自動的に作成されます。 nargs > 1の場合、複数の引数が消費され、長さ nargs のタプルが dest に追加されます。

type および dest のデフォルトは、"store"アクションの場合と同じです。

例：
```
parser.add_option("-t", "--tracks", action="append", type="int")
```
-t3がコマンドラインに表示されている場合、 optparse は次と同等の処理を実行します。
```
options.tracks = []
options.tracks.append(int("3"))
```
少し後で、--tracks=4が表示された場合、次のようになります。
```
options.tracks.append(int("4"))
```
appendアクションは、オプションの現在の値に対してappendメソッドを呼び出します。つまり、指定するデフォルト値にはappendメソッドが必要です。また、デフォルト値が空でない場合、デフォルト要素がオプションの解析値に存在し、コマンドラインからの値がそれらのデフォルト値の後に追加されることも意味します。
```
>>> parser.add_option("--files", action="append", default=['~/.mypkg/defaults'])
>>> opts, args = parser.parse_args(['--files', 'overrides.mypkg'])
>>> opts.files
['~/.mypkg/defaults', 'overrides.mypkg']
```
"append_const" [必須： const ; 関連：宛先]

"store_const"と同様ですが、値 const が dest に追加されます。 "append"と同様に、 dest のデフォルトはNoneであり、オプションが最初に検出されたときに空のリストが自動的に作成されます。
"count" [関連：宛先]

dest に格納されている整数をインクリメントします。デフォルト値が指定されていない場合、 dest は、最初にインクリメントされる前にゼロに設定されます。

例：
```
parser.add_option("-v", action="count", dest="verbosity")
```
-vがコマンドラインで初めて表示されるとき、 optparse は次と同等のことを行います。
```
options.verbosity = 0
options.verbosity += 1
```
-vがその後発生するたびに、次のようになります。
```
options.verbosity += 1
```
"callback" [必須：コールバック; 関連： type 、 nargs 、 callback_args 、 callback_kwargs ]

callback で指定された関数を呼び出します。
```
func(option, opt_str, value, parser, *args, **kwargs)
```
詳細については、セクションオプションのコールバックを参照してください。
"help"

現在のオプションパーサーのすべてのオプションの完全なヘルプメッセージを出力します。ヘルプメッセージは、OptionParserのコンストラクターに渡されるusage文字列と、すべてのオプションに渡される help 文字列から構成されます。

オプションに help 文字列が指定されていない場合でも、ヘルプメッセージに表示されます。オプションを完全に省略するには、特別な値optparse.SUPPRESS_HELPを使用します。

optparse は、すべてのOptionParsersに help オプションを自動的に追加するため、通常は作成する必要はありません。

例：
```
from optparse import OptionParser, SUPPRESS_HELP

# usually, a help option is added automatically, but that can
# be suppressed using the add_help_option argument
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")
parser.add_option("--secret", help=SUPPRESS_HELP)
```
optparse がコマンドラインで-hまたは--helpのいずれかを検出すると、次のようなヘルプメッセージがstdoutに出力されます（sys.argv[0]が"foo.py"）：
```
Usage: foo.py [options]

Options:
  -h, --help        Show this help message and exit
  -v                Be moderately verbose
  --file=FILENAME   Input file to read data from
```
ヘルプメッセージを出力した後、 optparse はsys.exit(0)でプロセスを終了します。
"version"

OptionParserに提供されたバージョン番号をstdoutに出力して終了します。バージョン番号は、実際にはOptionParserのprint_version()メソッドによってフォーマットおよび印刷されます。通常、version引数がOptionParserコンストラクターに提供されている場合にのみ関係します。 help オプションと同様に、 optparse は必要に応じて自動的に追加するため、versionオプションを作成することはめったにありません。

標準オプションタイプ

optparse には、"string"、"int"、"choice"、"float"、"complex"の5つの組み込みオプションタイプがあります。新しいオプションタイプを追加する必要がある場合は、セクション optparse の拡張を参照してください。

文字列オプションへの引数は、チェックも変換もされません。コマンドラインのテキストは、そのまま宛先に保存されます（またはコールバックに渡されます）。

整数引数（タイプ"int"）は次のように解析されます。

数値が0xで始まる場合、16進数として解析されます
数値が0で始まる場合、8進数として解析されます
数値が0bで始まる場合、2進数として解析されます
それ以外の場合、数値は10進数として解析されます

変換は、適切な基数（2、8、10、または16）を使用して int（）を呼び出すことによって行われます。これが失敗した場合は、 optparse も失敗しますが、より有用なエラーメッセージが表示されます。

"float"および"complex"オプション引数は、 float（）および complex（）で直接変換され、同様のエラー処理が行われます。

"choice"オプションは、"string"オプションのサブタイプです。 choices オプション属性（文字列のシーケンス）は、許可されるオプション引数のセットを定義します。 optparse.check_choice()は、ユーザー指定のオプション引数をこのマスターリストと比較し、無効な文字列が指定された場合はOptionValueErrorを発生させます。

引数の解析

OptionParserを作成してデータを設定することの全体的なポイントは、そのparse_args()メソッドを呼び出すことです。

(options, args) = parser.parse_args(args=None, values=None)

ここで、入力パラメータは

args: 処理する引数のリスト（デフォルト：sys.argv[1:]）
values: オプション引数を格納するoptparse.Valuesオブジェクト（デフォルト：Valuesの新しいインスタンス）–既存のオブジェクトを指定すると、オプションのデフォルトは初期化されません

戻り値は

options: valuesとして渡されたものと同じオブジェクト、または optparse によって作成されたoptparse.Valuesインスタンス
args: すべてのオプションが処理された後の残りの位置引数

最も一般的な使用法は、どちらのキーワード引数も指定しないことです。 valuesを指定すると、 setattr（）呼び出し（オプションの宛先に格納されているオプション引数ごとに約1回）が繰り返されて変更され、parse_args()によって返されます。

parse_args()が引数リストでエラーを検出すると、適切なエンドユーザーエラーメッセージを使用してOptionParserのerror()メソッドを呼び出します。これにより、最終的にプロセスが終了ステータス2（コマンドラインエラーの従来のUnix終了ステータス）で終了します。

オプションパーサーのクエリと操作

オプションパーサーのデフォルトの動作はわずかにカスタマイズできます。また、オプションパーサーをざっと見て、そこに何があるかを確認することもできます。 OptionParserには、次のような方法があります。

OptionParser.disable_interspersed_args()

最初の非オプションで停止するように解析を設定します。たとえば、-aと-bがどちらも引数をとらない単純なオプションである場合、 optparse は通常次の構文を受け入れます。

prog -a arg1 -b arg2

そしてそれを同等として扱います

prog -a -b arg1 arg2

この機能を無効にするには、 disable_interspersed_args（）を呼び出します。これにより、オプションの解析が最初の非オプション引数で停止する従来のUnix構文が復元されます。

独自のオプションを持つ別のコマンドを実行するコマンドプロセッサがあり、これらのオプションが混乱しないようにする場合は、これを使用します。たとえば、各コマンドには異なるオプションのセットがある場合があります。

OptionParser.enable_interspersed_args(): 最初の非オプションで停止しないように解析を設定し、コマンド引数を使用してスイッチを散在させます。これがデフォルトの動作です。

OptionParser.get_option(opt_str): オプション文字列 opt_str を含むOptionインスタンスを返します。オプション文字列を持つオプションがない場合は、Noneを返します。

OptionParser.has_option(opt_str): OptionParserにオプション文字列 opt_str のオプションがある場合は、Trueを返します（例：-qまたは--verbose）。

OptionParser.remove_option(opt_str): OptionParser に opt_str に対応するオプションがある場合、そのオプションは削除されます。そのオプションが他のオプション文字列を提供した場合、それらのオプション文字列はすべて無効になります。この OptionParser に属するオプションで opt_str が発生しない場合、 ValueError が発生します。

オプション間の競合

注意しないと、オプション文字列が競合するオプションを簡単に定義できます。

parser.add_option("-n", "--dry-run", ...)
...
parser.add_option("-n", "--noisy", ...)

（これは、いくつかの標準オプションを使用して独自のOptionParserサブクラスを定義した場合に特に当てはまります。）

オプションを追加するたびに、 optparse は既存のオプションとの競合をチェックします。何かが見つかった場合は、現在の競合処理メカニズムを呼び出します。コンストラクターで競合処理メカニズムを設定できます。

parser = OptionParser(..., conflict_handler=handler)

または別の呼び出しで：

parser.set_conflict_handler(handler)

使用可能な競合ハンドラーは次のとおりです。

"error"（デフォルト）

オプションの競合がプログラミングエラーであると想定し、OptionConflictErrorを発生させます

"resolve"

オプションの競合をインテリジェントに解決します（以下を参照）

例として、競合をインテリジェントに解決し、競合するオプションを追加する OptionParser を定義しましょう。

parser = OptionParser(conflict_handler="resolve")
parser.add_option("-n", "--dry-run", ..., help="do no harm")
parser.add_option("-n", "--noisy", ..., help="be noisy")

この時点で、 optparse は、以前に追加されたオプションがすでに-nオプション文字列を使用していることを検出します。 conflict_handlerは"resolve"であるため、以前のオプションのオプション文字列のリストから-nを削除することで、この状況を解決します。現在、--dry-runは、ユーザーがそのオプションをアクティブにする唯一の方法です。ユーザーがヘルプを要求すると、ヘルプメッセージには次の内容が反映されます。

Options:
  --dry-run     do no harm
  ...
  -n, --noisy   be noisy

以前に追加されたオプションのオプション文字列がなくなるまで削り取ることは可能であり、ユーザーはコマンドラインからそのオプションを呼び出す方法がありません。その場合、 optparse はそのオプションを完全に削除するため、ヘルプテキストやその他の場所には表示されません。既存のOptionParserを継続します。

parser.add_option("--dry-run", ..., help="new dry-run option")

この時点で、元の-n / --dry-runオプションにアクセスできなくなったため、 optparse はそれを削除し、次のヘルプテキストを残します。

Options:
  ...
  -n, --noisy   be noisy
  --dry-run     new dry-run option

掃除

OptionParserインスタンスには、いくつかの循環参照があります。これはPythonのガベージコレクターにとっては問題にはならないはずですが、終了したらOptionParserでdestroy()を呼び出して、循環参照を明示的に解除することをお勧めします。これは、OptionParserから大きなオブジェクトグラフに到達できる長時間実行アプリケーションで特に役立ちます。

他の方法

OptionParserは、他のいくつかのパブリックメソッドをサポートしています。

OptionParser.set_usage(usage): usageコンストラクタキーワード引数については、上記のルールに従って使用文字列を設定してください。 Noneを渡すと、デフォルトの使用文字列が設定されます。 optparse.SUPPRESS_USAGEを使用して、使用メッセージを抑制します。

OptionParser.print_usage(file=None): 現在のプログラム（self.usage）の使用法メッセージをファイル（デフォルトの標準出力）に出力します。 self.usageに文字列%progが出現すると、現在のプログラムの名前に置き換えられます。 self.usageが空であるか、定義されていない場合は何もしません。

OptionParser.get_usage(): print_usage（）と同じですが、使用法の文字列を出力する代わりに返します。

OptionParser.set_defaults(dest=value, ...)

複数のオプションの宛先に一度にデフォルト値を設定します。 set_defaults（）を使用することは、複数のオプションが同じ宛先を共有できるため、オプションのデフォルト値を設定するための推奨される方法です。たとえば、複数の「モード」オプションがすべて同じ宛先を設定している場合、それらのいずれかがデフォルトを設定でき、最後のオプションが優先されます。

parser.add_option("--advanced", action="store_const",
                  dest="mode", const="advanced",
                  default="novice")    # overridden below
parser.add_option("--novice", action="store_const",
                  dest="mode", const="novice",
                  default="advanced")  # overrides above setting

この混乱を避けるために、 set_defaults（）を使用してください。

parser.set_defaults(mode="advanced")
parser.add_option("--advanced", action="store_const",
                  dest="mode", const="advanced")
parser.add_option("--novice", action="store_const",
                  dest="mode", const="novice")

オプションのコールバック

optparse の組み込みアクションとタイプではニーズが十分でない場合は、 optparse を拡張するか、コールバックオプションを定義するかの2つの選択肢があります。 optparse の拡張はより一般的ですが、多くの単純なケースではやり過ぎです。多くの場合、必要なのは単純なコールバックだけです。

コールバックオプションを定義するには、次の2つの手順があります。

"callback"アクションを使用してオプション自体を定義します
コールバックを書く; これは、以下で説明するように、少なくとも4つの引数を取る関数（またはメソッド）です。

コールバックオプションの定義

いつものように、コールバックオプションを定義する最も簡単な方法は、 OptionParser.add_option（）メソッドを使用することです。 action とは別に、指定する必要がある唯一のオプション属性はcallbackであり、呼び出す関数は次のとおりです。

parser.add_option("-c", action="callback", callback=my_callback)

callbackは関数（または他の呼び出し可能なオブジェクト）であるため、このコールバックオプションを作成するときは、my_callback()をすでに定義しておく必要があります。この単純なケースでは、 optparse は、-cが引数を取るかどうかさえ知りません。これは通常、オプションが引数を取らないことを意味します。つまり、-cがコマンドラインはそれが知る必要があるすべてです。ただし、状況によっては、コールバックで任意の数のコマンドライン引数を使用したい場合があります。これは、コールバックの記述が難しいところです。これについては、このセクションの後半で説明します。

optparse は常に4つの特定の引数をコールバックに渡し、 callback_args および callback_kwargs で指定した場合にのみ追加の引数を渡します。したがって、最小のコールバック関数シグネチャは次のとおりです。

def my_callback(option, opt, value, parser):

コールバックの4つの引数を以下に説明します。

コールバックオプションを定義するときに指定できるオプション属性は他にもいくつかあります。

type: 通常の意味があります。"store"または"append"アクションと同様に、 optparse に1つの引数を消費し、それを type に変換するように指示します。ただし、変換された値をどこかに保存するのではなく、 optparse はそれをコールバック関数に渡します。
nargs: また、通常の意味もあります。指定され、> 1の場合、 optparse は nargs 引数を消費し、各引数は type に変換可能である必要があります。次に、変換された値のタプルをコールバックに渡します。
callback_args: コールバックに渡す追加の位置引数のタプル
callback_kwargs: コールバックに渡す追加のキーワード引数の辞書

コールバックの呼び出し方法

すべてのコールバックは次のように呼び出されます。

func(option, opt_str, value, parser, *args, **kwargs)

どこ

option: コールバックを呼び出しているOptionインスタンスです
opt_str: は、コールバックをトリガーするコマンドラインに表示されるオプション文字列です。（省略されたlongオプションが使用された場合、opt_strは完全な正規のオプション文字列になります。ユーザーがコマンドラインに--foobarの省略形として--fooを入力すると、opt_strは"--foobar"になります。）
value: コマンドラインに表示されるこのオプションの引数です。 optparse は、 type が設定されている場合にのみ引数を期待します。 valueのタイプは、オプションのタイプによって示されるタイプになります。このオプションの type がNone（引数は予期されていません）の場合、valueはNoneになります。 nargs > 1の場合、valueは適切なタイプの値のタプルになります。
parser: 全体を駆動するOptionParserインスタンスです。主に、インスタンス属性を介して他の興味深いデータにアクセスできるため便利です。

parser.largs 残りの引数の現在のリスト、すなわち。消費されたが、オプションでもオプション引数でもない引数。 parser.largsを自由に変更してください。例：それにさらに引数を追加することによって。（このリストはargsになり、parse_args()の2番目の戻り値になります。） parser.rargs 残りの引数の現在のリスト、すなわち。 opt_strとvalue（該当する場合）が削除され、それらに続く引数のみが引き続き存在します。 parser.rargsを自由に変更してください。例：より多くの引数を消費することによって。 parser.values オプション値がデフォルトで保存されるオブジェクト（optparse.OptionValuesのインスタンス）。これにより、コールバックはオプション値を格納するために optparse の残りの部分と同じメカニズムを使用できます。グローバルやクロージャをいじくり回す必要はありません。コマンドラインですでに検出されているオプションの値にアクセスしたり、値を変更したりすることもできます。

args: callback_args オプション属性を介して提供される任意の位置引数のタプルです。
kwargs: callback_kwargs を介して提供される任意のキーワード引数の辞書です。

コールバックでエラーが発生する

オプションまたはその引数に問題がある場合、コールバック関数はOptionValueErrorを発生させる必要があります。 optparse はこれをキャッチしてプログラムを終了し、stderrに提供したエラーメッセージを出力します。あなたのメッセージは明確、簡潔、正確であり、誤りのあるオプションについて言及する必要があります。そうしないと、ユーザーは自分が何を間違えたかを理解するのに苦労します。

コールバックの例1：簡単なコールバック

引数をとらず、オプションが表示されたことを記録するだけのコールバックオプションの例を次に示します。

def record_foo_seen(option, opt_str, value, parser):
    parser.values.saw_foo = True

parser.add_option("--foo", action="callback", callback=record_foo_seen)

もちろん、"store_true"アクションでそれを行うことができます。

コールバックの例2：オプションの順序を確認する

もう少し興味深い例を次に示します。-aが表示されているという事実を記録しますが、コマンドラインで-bの後に表示された場合は爆発します。

def check_order(option, opt_str, 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")

コールバックの例3：オプションの順序を確認する（一般化）

このコールバックをいくつかの同様のオプションに再利用する場合（フラグを設定しますが、-bが既に表示されている場合は爆破します）、エラーメッセージと設定するフラグという少しの作業が必要です。一般化する必要があります。

def check_order(option, opt_str, value, parser):
    if parser.values.b:
        raise OptionValueError("can't use %s after -b" % opt_str)
    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')

コールバックの例4：任意の条件を確認する

もちろん、そこに任意の条件を設定できます。定義済みのオプションの値をチェックすることに限定されません。たとえば、月が満月のときに呼び出されるべきではないオプションがある場合、あなたがしなければならないのはこれだけです：

def check_moon(option, opt_str, value, parser):
    if is_moon_full():
        raise OptionValueError("%s option invalid when moon is full"
                               % opt_str)
    setattr(parser.values, option.dest, 1)
...
parser.add_option("--foo",
                  action="callback", callback=check_moon, dest="foo")

（is_moon_full()の定義は、読者の練習問題として残されています。）

コールバックの例5：固定引数

固定数の引数を取るコールバックオプションを定義すると、状況は少し興味深いものになります。コールバックオプションが引数を取るように指定することは、"store"または"append"オプションを定義することに似ています。 type を定義する場合、オプションはそれに変換可能でなければならない1つの引数を取りますタイプ; nargs をさらに定義すると、オプションは nargs 引数を取ります。

標準の"store"アクションをエミュレートする例を次に示します。

def store_value(option, opt_str, value, parser):
    setattr(parser.values, option.dest, value)
...
parser.add_option("--foo",
                  action="callback", callback=store_value,
                  type="int", nargs=3, dest="foo")

optparse は、3つの引数を消費し、それらを整数に変換する処理を行うことに注意してください。あなたがしなければならないのはそれらを保存することだけです。（または何でも。明らかに、この例ではコールバックは必要ありません。）

コールバックの例6：可変引数

可変数の引数を取るオプションが必要な場合、事態は厄介になります。この場合、 optparse には組み込み機能がないため、コールバックを作成する必要があります。また、 optparse が通常処理する従来のUnixコマンドライン解析の特定の複雑さに対処する必要があります。特に、コールバックは、裸の--および-引数の従来のルールを実装する必要があります。

--または-のいずれかをオプション引数にすることができます
ベア--（一部のオプションの引数でない場合）：コマンドライン処理を停止し、--を破棄します
裸の-（一部のオプションの引数でない場合）：コマンドライン処理を停止しますが、-は保持します（parser.largsに追加します）

可変数の引数を取るオプションが必要な場合は、いくつかの微妙でトリッキーな問題を心配する必要があります。選択する正確な実装は、アプリケーションに対してどのようなトレードオフを行うかによって異なります（そのため、 optparse はこの種のことを直接サポートしていません）。

それでも、可変引数を持つオプションのコールバックでのスタブは次のとおりです。

def vararg_callback(option, opt_str, value, parser):
    assert value is None
    value = []

    def floatable(str):
        try:
            float(str)
            return True
        except ValueError:
            return False

    for arg in parser.rargs:
        # stop on --foo like options
        if arg[:2] == "--" and len(arg) > 2:
            break
        # stop on -a, but not on -3 or -3.0
        if arg[:1] == "-" and len(arg) > 1 and not floatable(arg):
            break
        value.append(arg)

    del parser.rargs[:len(value)]
    setattr(parser.values, option.dest, value)

...
parser.add_option("-c", "--callback", dest="vararg_attr",
                  action="callback", callback=vararg_callback)

optparse の拡張

optparse がコマンドラインオプションを解釈する方法の2つの主要な制御要因は、各オプションのアクションとタイプであるため、拡張の最も可能性の高い方向は、新しいアクションと新しいタイプを追加することです。

新しいタイプの追加

新しい型を追加するには、 optparse のOptionクラスの独自のサブクラスを定義する必要があります。このクラスには、 optparse のタイプを定義するいくつかの属性があります。 TYPES および TYPE_CHECKER です。

Option.TYPES: タイプ名のタプル。サブクラスで、標準のタプルに基づいて構築される新しいタプル TYPES を定義するだけです。

Option.TYPE_CHECKER

タイプ名をタイプチェック関数にマッピングする辞書。タイプチェック関数には、次のシグネチャがあります。

def check_mytype(option, opt, value)

ここで、optionはOptionインスタンス、optはオプション文字列（-fなど）、valueはチェックして目的のタイプに変換する必要があるコマンドライン。 check_mytype()は、仮想タイプmytypeのオブジェクトを返す必要があります。タイプチェック関数によって返される値は、OptionParser.parse_args()によって返されるOptionValuesインスタンスに格納されるか、valueパラメーターとしてコールバックに渡されます。

タイプチェック関数は、問題が発生した場合にOptionValueErrorを発生させる必要があります。 OptionValueErrorは、単一の文字列引数を取り、それをそのまま OptionParser のerror()メソッドに渡します。このメソッドは、プログラム名と文字列 [を付加します。 X168X]そして、プロセスを終了する前に、すべてをstderrに出力します。

これは、コマンドラインでPythonスタイルの複素数を解析するために"complex"オプションタイプを追加することを示すばかげた例です。（ optparse 1.3では複素数の組み込みサポートが追加されたため、これは以前よりもさらに愚かですが、気にしないでください。）

まず、必要なインポート：

from copy import copy
from optparse import Option, OptionValueError

タイプチェッカーは後で参照されるため（Optionサブクラスの TYPE_CHECKER クラス属性で）、最初にタイプチェッカーを定義する必要があります。

def check_complex(option, opt, value):
    try:
        return complex(value)
    except ValueError:
        raise OptionValueError(
            "option %s: invalid complex value: %r" % (opt, value))

最後に、Optionサブクラス：

class MyOption (Option):
    TYPES = Option.TYPES + ("complex",)
    TYPE_CHECKER = copy(Option.TYPE_CHECKER)
    TYPE_CHECKER["complex"] = check_complex

（ Option.TYPE_CHECKER の copy（）を作成しなかった場合、 optparse の TYPE_CHECKER 属性を変更することになります。のオプションクラス。これはPythonであるため、マナーと常識を除いて、それを妨げるものは何もありません。）

それでおしまい！これで、他の optparse ベースのスクリプトと同じように、新しいオプションタイプを使用するスクリプトを記述できます。ただし、Optionの代わりにMyOptionを使用するようにOptionParserに指示する必要があります。

parser = OptionParser(option_class=MyOption)
parser.add_option("-c", type="complex")

または、独自のオプションリストを作成して、OptionParserに渡すこともできます。上記の方法でadd_option()を使用しない場合は、使用するオプションクラスをOptionParserに指示する必要はありません。

option_list = [MyOption("-c", action="store", type="complex", dest="c")]
parser = OptionParser(option_list=option_list)

新しいアクションの追加

optparse にはアクションの分類がいくつかあることを理解する必要があるため、新しいアクションの追加は少し注意が必要です。

「保存」アクション: optparse が現在のOptionValuesインスタンスの属性に値を格納する結果となるアクション。これらのオプションでは、 dest 属性をOptionコンストラクターに提供する必要があります。
「入力された」アクション: コマンドラインから値を取得し、それが特定のタイプであると期待するアクション。むしろ、特定のタイプに変換できる文字列。これらのオプションには、Optionコンストラクターに type 属性が必要です。

これらは重複するセットです。デフォルトの「保存」アクションには、"store"、"store_const"、"append"、および"count"がありますが、デフォルトの「入力済み」アクションは[ X147X] 、"append"、および"callback"。

アクションを追加するときは、Optionの次のクラス属性の少なくとも1つにリストして分類する必要があります（すべて文字列のリストです）。

Option.ACTIONS: すべてのアクションは、ACTIONSにリストされている必要があります。

Option.STORE_ACTIONS: 「ストア」アクションは、ここに追加でリストされています。

Option.TYPED_ACTIONS: 「入力された」アクションは、ここに追加でリストされています。

Option.ALWAYS_TYPED_ACTIONS: 常にタイプをとるアクション（つまり、そのオプションは常に値を取ります）がここに追加でリストされています。これの唯一の効果は、 optparse がデフォルトタイプ"string"を、アクションが ALWAYS_TYPED_ACTIONS にリストされている明示的なタイプのないオプションに割り当てることです。

新しいアクションを実際に実装するには、Optionのtake_action()メソッドをオーバーライドし、アクションを認識するケースを追加する必要があります。

たとえば、"extend"アクションを追加しましょう。これは標準の"append"アクションに似ていますが、コマンドラインから単一の値を取得して既存のリストに追加する代わりに、"extend"は単一のコンマ区切りで複数の値を取得します文字列、および既存のリストをそれらで拡張します。つまり、--namesがタイプ"string"の"extend"オプションである場合、コマンドライン

--names=foo,bar --names blah --names ding,dong

リストになります

["foo", "bar", "blah", "ding", "dong"]

ここでも、Optionのサブクラスを定義します。

class MyOption(Option):

    ACTIONS = Option.ACTIONS + ("extend",)
    STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
    TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
    ALWAYS_TYPED_ACTIONS = Option.ALWAYS_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)

注意の特徴：

"extend"は両方ともコマンドラインで値を期待し、その値をどこかに格納するため、 STORE_ACTIONS と TYPED_ACTIONS の両方に格納されます。
optparse がデフォルトタイプの"string"を"extend"アクションに確実に割り当てるために、"extend"アクションも ALWAYS_TYPED_ACTIONS に配置します。。
MyOption.take_action()は、この1つの新しいアクションのみを実装し、標準の optparse アクションの制御をOption.take_action()に戻します。
valuesはoptparse_parser.Valuesクラスのインスタンスであり、非常に便利なensure_value()メソッドを提供します。 ensure_value()は、基本的に getattr（）であり、安全弁が付いています。それはとして呼ばれます
```
values.ensure_value(attr, value)
```
valuesのattr属性が存在しないか、Noneである場合、ensure_value（）は最初にそれをvalueに設定し、次に '値を返します。これは、"extend"、"append"、"count"などのアクションに非常に便利です。これらはすべて、変数にデータを蓄積し、その変数が特定のタイプ（リスト）であることを期待します。最初の2つは整数、後者は整数）。 ensure_value()を使用すると、アクションを使用するスクリプトは、問題のオプションの宛先にデフォルト値を設定することを心配する必要がなくなります。 Noneとensure_value()が必要なときに正しく処理するため、デフォルトのままにしておくことができます。

optparse —コマンドラインオプションのパーサー—Pythonドキュメント