15.4. "argparse" --- コマンドラインオプション、引数、サブコマンドのパーサー
***************************************************************************

バージョン 2.7 で追加.

**ソースコード:** Lib/argparse.py

======================================================================


チュートリアル
^^^^^^^^^^^^^^

このページでは API のリファレンス情報が記載されています。argparse チュ
ートリアル では、コマンドラインの解析についてより優しく説明しています
。

"argparse" モジュールはユーザーフレンドリーなコマンドラインインタフェ
ースの作成を簡単にします。プログラムがどんな引数を必要としているのかを
定義すると、"argparse" が "sys.argv" からそのオプションを解析する部分
の面倒を見ます。"argparse" モジュールは自動的にヘルプと使用方法メッセ
ージを生成し、ユーザーが不正な引数をプログラムに指定したときにエラーを
発生させます。


15.4.1. 例
==========

次のコードは、整数のリストを受け取って合計か最大値を返す Python プログ
ラムです:

   import argparse

   parser = argparse.ArgumentParser(description='Process some integers.')
   parser.add_argument('integers', metavar='N', type=int, nargs='+',
                       help='an integer for the accumulator')
   parser.add_argument('--sum', dest='accumulate', action='store_const',
                       const=sum, default=max,
                       help='sum the integers (default: find the max)')

   args = parser.parse_args()
   print args.accumulate(args.integers)

上の Python コードが "prog.py" という名前のファイルに保存されたと仮定
します。コマンドラインから便利なヘルプメッセージを表示できます:

   $ python prog.py -h
   usage: prog.py [-h] [--sum] N [N ...]

   Process some integers.

   positional arguments:
    N           an integer for the accumulator

   optional arguments:
    -h, --help  show this help message and exit
    --sum       sum the integers (default: find the max)

適切な引数を与えて実行した場合、このプログラムはコマンドライン引数の整
数列の合計か最大値を表示します:

   $ python prog.py 1 2 3 4
   4

   $ python prog.py 1 2 3 4 --sum
   10

不正な引数が与えられた場合、エラーを発生させます:

   $ python prog.py a b c
   usage: prog.py [-h] [--sum] N [N ...]
   prog.py: error: argument N: invalid int value: 'a'

以降の節では、この例をひと通り説明して行きます。


15.4.1.1. パーサーを作る
------------------------

"argparse" を使う時の最初のステップは、"ArgumentParser" オブジェクトを
生成することです:

   >>> parser = argparse.ArgumentParser(description='Process some integers.')

"ArgumentParser" オブジェクトはコマンドラインを解析して Python データ
型にするために必要なすべての情報を保持します。


15.4.1.2. 引数を追加する
------------------------

"ArgumentParser" にプログラム引数の情報を与えるために、
"add_argument()" メソッドを呼び出します。一般的に、このメソッドの呼び
出しは "ArgumentParser" に、コマンドラインの文字列を受け取ってそれをオ
ブジェクトにする方法を教えます。この情報は保存され、"parse_args()" が
呼び出されたときに利用されます。例えば:

   >>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
   ...                     help='an integer for the accumulator')
   >>> parser.add_argument('--sum', dest='accumulate', action='store_const',
   ...                     const=sum, default=max,
   ...                     help='sum the integers (default: find the max)')

あとで "parse_args()" を呼び出すと、"integers" と "accumulate" という2
つの属性を持ったオブジェクトを返します。"integers" 属性は1つ以上の整数
のリストで、"accumulate" 属性はコマンドラインから "--sum" が指定された
場合は "sum()" 関数に、それ以外の場合は "max()" 関数になります。


15.4.1.3. 引数を解析する
------------------------

"ArgumentParser" は引数を "parse_args()" メソッドで解析します。このメ
ソッドはコマンドラインを調べ、各引数を正しい型に変換して、適切なアクシ
ョンを実行します。ほとんどの場合、これはコマンドラインの解析結果から、
シンプルな "Namespace" オブジェクトを構築することを意味します:

   >>> parser.parse_args(['--sum', '7', '-1', '42'])
   Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])

スクリプト内では、"parse_args()" は通常引数なしで呼び出され、
"ArgumentParser" は自動的に "sys.argv" からコマンドライン引数を取得し
ます。


15.4.2. ArgumentParser オブジェクト
===================================

class argparse.ArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True)

   新しい "ArgumentParser" オブジェクトを生成します。すべての引数はキ
   ーワード引数として渡すべきです。各引数についてはあとで詳しく説明し
   ますが、簡単に言うと:

   * prog - プログラム名 (デフォルト: "sys.argv[0]")

   * usage - プログラムの利用方法を記述する文字列 (デフォルト: パー
     サ ーに追加された引数から生成される)

   * description - 引数のヘルプの前に表示されるテキスト (デフォルト:
     none)

   * epilog - 引数のヘルプの後で表示されるテキスト (デフォルト:
     none)

   * parents - "ArgumentParser" オブジェクトのリストで、このオブジェ
     ク トの引数が追加される

   * formatter_class - ヘルプ出力をカスタマイズするためのクラス

   * prefix_chars - オプションの引数の prefix になる文字集合 (デフォ
     ル ト: '-')

   * fromfile_prefix_chars - 追加の引数を読み込むファイルの prefix
     に なる文字集合 (デフォルト: "None")

   * argument_default - 引数のグローバルなデフォルト値 (デフォルト:
     "None")

   * conflict_handler - 衝突するオプションを解決する方法 (通常は不要
     )

   * add_help - "-h/--help" オプションをパーサーに追加する (デフォル
     ト : "True")

以下の節では各オプションの利用方法を説明します。


15.4.2.1. prog
--------------

デフォルトでは、"ArgumentParser" オブジェクトはヘルプメッセージ中に表
示するプログラム名を "sys.argv[0]" から取得します。 このデフォルトの動
作は、プログラムがコマンドライン上の起動方法に合わせてヘルプメッセージ
を作成するため、ほとんどの場合望ましい挙動になります。 例えば、
"myprogram.py" という名前のファイルに次のコードがあるとします:

   import argparse
   parser = argparse.ArgumentParser()
   parser.add_argument('--foo', help='foo help')
   args = parser.parse_args()

このプログラムのヘルプは、プログラム名として (プログラムがどこから起動
されたのかに関わらず) "myprogram.py" を表示します:

   $ python myprogram.py --help
   usage: myprogram.py [-h] [--foo FOO]

   optional arguments:
    -h, --help  show this help message and exit
    --foo FOO   foo help
   $ cd ..
   $ python subdir/myprogram.py --help
   usage: myprogram.py [-h] [--foo FOO]

   optional arguments:
    -h, --help  show this help message and exit
    --foo FOO   foo help

このデフォルトの動作を変更するには、"ArgumentParser" の "prog=" 引数に
他の値を指定します:

   >>> parser = argparse.ArgumentParser(prog='myprogram')
   >>> parser.print_help()
   usage: myprogram [-h]

   optional arguments:
    -h, --help  show this help message and exit

プログラム名は、"sys.argv[0]" から取られた場合でも "prog=" 引数で与え
られた場合でも、ヘルプメッセージ中では "%(prog)s" フォーマット指定子で
利用できます。

   >>> parser = argparse.ArgumentParser(prog='myprogram')
   >>> parser.add_argument('--foo', help='foo of the %(prog)s program')
   >>> parser.print_help()
   usage: myprogram [-h] [--foo FOO]

   optional arguments:
    -h, --help  show this help message and exit
    --foo FOO   foo of the myprogram program


15.4.2.2. usage
---------------

デフォルトでは、 "ArgumentParser" は使用法メッセージを、保持している引
数から生成します:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('--foo', nargs='?', help='foo help')
   >>> parser.add_argument('bar', nargs='+', help='bar help')
   >>> parser.print_help()
   usage: PROG [-h] [--foo [FOO]] bar [bar ...]

   positional arguments:
    bar          bar help

   optional arguments:
    -h, --help   show this help message and exit
    --foo [FOO]  foo help

デフォルトのメッセージは "usage=" キーワード引数で変更できます:

   >>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
   >>> parser.add_argument('--foo', nargs='?', help='foo help')
   >>> parser.add_argument('bar', nargs='+', help='bar help')
   >>> parser.print_help()
   usage: PROG [options]

   positional arguments:
    bar          bar help

   optional arguments:
    -h, --help   show this help message and exit
    --foo [FOO]  foo help

"%(prog)s" フォーマット指定子を、使用法メッセージ内でプログラム名とし
て利用できます。


15.4.2.3. description
---------------------

多くの場合、"ArgumentParser" のコンストラクターを呼び出すときに
"description=" キーワード引数が使用されます。この引数はプログラムが何
をしてどう動くのかについての短い説明になります。ヘルプメッセージで、こ
の説明がコマンドラインの利用法と引数のヘルプメッセージの間に表示されま
す:

   >>> parser = argparse.ArgumentParser(description='A foo that bars')
   >>> parser.print_help()
   usage: argparse.py [-h]

   A foo that bars

   optional arguments:
    -h, --help  show this help message and exit

デフォルトでは、説明は与えられたスペースに合わせて折り返されます。この
挙動を変更するには、formatter_class 引数を参照してください。


15.4.2.4. epilog
----------------

いくつかのプログラムは、プログラムについての追加の説明を引数の説明の後
に表示します。このテキストは "ArgumentParser" の "epilog=" 引数に指定
できます:

   >>> parser = argparse.ArgumentParser(
   ...     description='A foo that bars',
   ...     epilog="And that's how you'd foo a bar")
   >>> parser.print_help()
   usage: argparse.py [-h]

   A foo that bars

   optional arguments:
    -h, --help  show this help message and exit

   And that's how you'd foo a bar

description 引数と同じく、"epilog=" テキストもデフォルトで折り返され、
"ArgumentParser" の formatter_class 引数で動作を調整できます。


15.4.2.5. parents
-----------------

ときどき、いくつかのパーサーが共通の引数セットを共有することがあります
。それらの引数を繰り返し定義する代わりに、すべての共通引数を持ったパー
サーを "ArgumentParser" の "parents=" 引数に渡すことができます。
"parents=" 引数は "ArgumentParser" オブジェクトのリストを受け取り、す
べての位置アクションとオプションのアクションをそれらから集め、そのアク
ションを構築中の "ArgumentParser" オブジェクトに追加します:

   >>> parent_parser = argparse.ArgumentParser(add_help=False)
   >>> parent_parser.add_argument('--parent', type=int)

   >>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
   >>> foo_parser.add_argument('foo')
   >>> foo_parser.parse_args(['--parent', '2', 'XXX'])
   Namespace(foo='XXX', parent=2)

   >>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
   >>> bar_parser.add_argument('--bar')
   >>> bar_parser.parse_args(['--bar', 'YYY'])
   Namespace(bar='YYY', parent=None)

一番親になるパーサーに "add_help=False" を指定していることに注目してく
ださい。こうしないと、"ArgumentParser" は2つの "-h/--help" オプション
を与えられる (1つは親から、もうひとつは子から) ことになり、エラーを発
生します。

注釈: "parents=" に渡す前にパーサーを完全に初期化する必要があります
  。子パ ーサーを作成してから親パーサーを変更した場合、その変更は子パ
  ーサーに 反映されません。


15.4.2.6. formatter_class
-------------------------

"ArgumentParser" オブジェクトは代わりのフォーマットクラスを指定するこ
とでヘルプのフォーマットをカスタマイズできます。現在、3つのフォーマッ
トクラスがあります:

class argparse.RawDescriptionHelpFormatter
class argparse.RawTextHelpFormatter
class argparse.ArgumentDefaultsHelpFormatter

最初の2つは説明のテキストがどう表示されるかについてより制御できるよう
になっており、残りの1つは引数のデフォルト値についての情報を自動的に追
加します。

デフォルトでは "ArgumentParser" オブジェクトはコマンドラインヘルプの中
の description と epilog を折り返して表示します:

   >>> parser = argparse.ArgumentParser(
   ...     prog='PROG',
   ...     description='''this description
   ...         was indented weird
   ...             but that is okay''',
   ...     epilog='''
   ...             likewise for this epilog whose whitespace will
   ...         be cleaned up and whose words will be wrapped
   ...         across a couple lines''')
   >>> parser.print_help()
   usage: PROG [-h]

   this description was indented weird but that is okay

   optional arguments:
    -h, --help  show this help message and exit

   likewise for this epilog whose whitespace will be cleaned up and whose words
   will be wrapped across a couple lines

"formatter_class=" に "RawDescriptionHelpFormatter" を渡した場合、
description と epilog は整形済みとされ改行されません:

   >>> parser = argparse.ArgumentParser(
   ...     prog='PROG',
   ...     formatter_class=argparse.RawDescriptionHelpFormatter,
   ...     description=textwrap.dedent('''\
   ...         Please do not mess up this text!
   ...         --------------------------------
   ...             I have indented it
   ...             exactly the way
   ...             I want it
   ...         '''))
   >>> parser.print_help()
   usage: PROG [-h]

   Please do not mess up this text!
   --------------------------------
      I have indented it
      exactly the way
      I want it

   optional arguments:
    -h, --help  show this help message and exit

"RawTextHelpFormatter" maintains whitespace for all sorts of help
text, including argument descriptions. However, multiple new lines are
replaced with one. If you wish to preserve multiple blank lines, add
spaces between the newlines.

残りの利用できるフォーマットクラスである
"ArgumentDefaultsHelpFormatter" は各引数のデフォルト値を自動的にヘルプ
に追加します:

   >>> parser = argparse.ArgumentParser(
   ...     prog='PROG',
   ...     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
   >>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
   >>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
   >>> parser.print_help()
   usage: PROG [-h] [--foo FOO] [bar [bar ...]]

   positional arguments:
    bar         BAR! (default: [1, 2, 3])

   optional arguments:
    -h, --help  show this help message and exit
    --foo FOO   FOO! (default: 42)


15.4.2.7. prefix_chars
----------------------

ほとんどのコマンドラインオプションは、"-f/--foo" のように接頭辞に "-"
を使います。"+f" や "/foo" のような、他の、あるいは追加の接頭辞文字を
サポートしなければならない場合、ArgumentParser のコンストラクターに
"prefix_chars=" 引数を使って指定します:

   >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
   >>> parser.add_argument('+f')
   >>> parser.add_argument('++bar')
   >>> parser.parse_args('+f X ++bar Y'.split())
   Namespace(bar='Y', f='X')

"prefix_chars=" 引数のデフォルトは "'-'" です。"-" を含まない文字セッ
トを指定すると、"-f/--foo" オプションが使用できなくなります。


15.4.2.8. fromfile_prefix_chars
-------------------------------

ときどき、例えば非常に長い引数リストを扱う場合に、その引数リストを毎回
コマンドラインにタイプする代わりにファイルに置いておきたい場合がありま
す。"ArgumentParser" のコンストラクターに "fromfile_prefix_chars=" 引
数が渡された場合、指定された文字のいずれかで始まる引数はファイルとして
扱われ、そのファイルに含まれる引数リストに置換されます。例えば:

   >>> with open('args.txt', 'w') as fp:
   ...     fp.write('-f\nbar')
   >>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
   >>> parser.add_argument('-f')
   >>> parser.parse_args(['-f', 'foo', '@args.txt'])
   Namespace(f='bar')

ファイルから読み込まれる引数は、デフォルトでは1行に1つ (ただし、
"convert_arg_line_to_args()" も参照してください) で、コマンドライン上
でファイルを参照する引数があった場所にその引数があったものとして扱われ
ます。なので、上の例では、"['-f', 'foo', '@args.txt']" は "['-f',
'foo', '-f', 'bar']" と等価になります。

"fromfile_prefix_chars=" 引数のデフォルト値は "None" で、引数がファイ
ル参照として扱われることが無いことを意味しています。


15.4.2.9. argument_default
--------------------------

一般的には、引数のデフォルト値は "add_argument()" メソッドにデフォルト
値を渡すか、"set_defaults()" メソッドに名前と値のペアを渡すことで指定
します。しかしまれに、1つのパーサー全体に適用されるデフォルト引数が便
利なことがあります。これを行うには、 "ArgumentParser" に
"argument_default=" キーワード引数を渡します。例えば、全体で
"parse_args()" メソッド呼び出しの属性の生成を抑制するには、
"argument_default=SUPPRESS" を指定します:

   >>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
   >>> parser.add_argument('--foo')
   >>> parser.add_argument('bar', nargs='?')
   >>> parser.parse_args(['--foo', '1', 'BAR'])
   Namespace(bar='BAR', foo='1')
   >>> parser.parse_args([])
   Namespace()


15.4.2.10. conflict_handler
---------------------------

"ArgumentParser" オブジェクトは同じオプション文字列に対して複数のアク
ションを許可していません。 デフォルトでは、"ArgumentParser" オブジェク
トは、すでに利用されているオプション文字列を使って新しい引数をつくろう
としたときに例外を送出します:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-f', '--foo', help='old foo help')
   >>> parser.add_argument('--foo', help='new foo help')
   Traceback (most recent call last):
    ..
   ArgumentError: argument --foo: conflicting option string(s): --foo

ときどき (例えば parents を利用する場合など)、古い引数を同じオプション
文字列で上書きするほうが便利な場合があります。この動作をするには、
"ArgumentParser" の "conflict_handler=" 引数に "'resolve'" を渡します:

   >>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
   >>> parser.add_argument('-f', '--foo', help='old foo help')
   >>> parser.add_argument('--foo', help='new foo help')
   >>> parser.print_help()
   usage: PROG [-h] [-f FOO] [--foo FOO]

   optional arguments:
    -h, --help  show this help message and exit
    -f FOO      old foo help
    --foo FOO   new foo help

"ArgumentParser" オブジェクトは、すべてのオプション文字列が上書きされ
た場合にだけアクションを削除することに注目してください。上の例では、 "
--foo" オプション文字列だけが上書きされているので、古い "-f/--foo" ア
クションは "-f" アクションとして残っています。


15.4.2.11. add_help
-------------------

デフォルトでは、ArgumentParser オブジェクトはシンプルにパーサーのヘル
プメッセージを表示するオプションを自動的に追加します。例えば、以下のコ
ードを含む "myprogram.py" ファイルについて考えてください:

   import argparse
   parser = argparse.ArgumentParser()
   parser.add_argument('--foo', help='foo help')
   args = parser.parse_args()

コマンドラインに "-h" か "--help" が指定された場合、ArgumentParser の
help が表示されます:

   $ python myprogram.py --help
   usage: myprogram.py [-h] [--foo FOO]

   optional arguments:
    -h, --help  show this help message and exit
    --foo FOO   foo help

必要に応じて、この help オプションを無効にする場合があります。これは
"ArgumentParser" の "add_help=" 引数に "False" を渡すことで可能です:

   >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
   >>> parser.add_argument('--foo', help='foo help')
   >>> parser.print_help()
   usage: PROG [--foo FOO]

   optional arguments:
    --foo FOO  foo help

ヘルプオプションは通常 "-h/--help" です。例外は "prefix_chars=" が指定
されてその中に "-" が無かった場合で、その場合は "-h" と "--help" は有
効なオプションではありません。この場合、"prefix_chars" の最初の文字が
ヘルプオプションの接頭辞として利用されます:

   >>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
   >>> parser.print_help()
   usage: PROG [+h]

   optional arguments:
     +h, ++help  show this help message and exit


15.4.3. add_argument() メソッド
===============================

ArgumentParser.add_argument(name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest])

   1つのコマンドライン引数がどう解析されるかを定義します。各引数につい
   ての詳細は後述しますが、簡単に言うと:

   * name or flags - 名前か、あるいはオプション文字列のリスト (例:
     "foo" や "-f, --foo")。

   * action - コマンドラインにこの引数があった時のアクション。

   * nargs - 消費すべきコマンドライン引数の数。

   * const - 一部の action と nargs の組み合わせで利用される定数。

   * default - コマンドラインに引数がなかった場合に生成される値。

   * type - コマンドライン引数が変換されるべき型。

   * choices - 引数として許される値のコンテナー。

   * required - コマンドラインオプションが省略可能かどうか (オプショ
     ン 引数のみ)。

   * help - 引数が何なのかを示す簡潔な説明。

   * metavar - 使用法メッセージの中で使われる引数の名前。

   * dest - "parse_args()" が返すオブジェクトに追加される属性名。

以下の節では各オプションの利用方法を説明します。


15.4.3.1. name or flags
-----------------------

"add_argument()" メソッドは、指定されている引数が "-f" や "--foo" のよ
うなオプション引数なのか、ファイル名リストなどの位置引数なのかを知る必
要があります。そのため、"add_argument()" の第1引数は、フラグのリストか
、シンプルな引数名のどちらかになります。例えば、オプション引数は次のよ
うにして作成します:

   >>> parser.add_argument('-f', '--foo')

一方、位置引数は次のように作成します:

   >>> parser.add_argument('bar')

"parse_args()" が呼ばれた時、オプション引数は接頭辞 "-" により識別され
、それ以外の引数は位置引数として扱われます:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-f', '--foo')
   >>> parser.add_argument('bar')
   >>> parser.parse_args(['BAR'])
   Namespace(bar='BAR', foo=None)
   >>> parser.parse_args(['BAR', '--foo', 'FOO'])
   Namespace(bar='BAR', foo='FOO')
   >>> parser.parse_args(['--foo', 'FOO'])
   usage: PROG [-h] [-f FOO] bar
   PROG: error: too few arguments


15.4.3.2. action
----------------

"ArgumentParser" オブジェクトはコマンドライン引数にアクションを割り当
てます。このアクションは、割り当てられたコマンドライン引数に関してどん
な処理でもできますが、ほとんどのアクションは単に "parse_args()" が返す
オブジェクトに属性を追加するだけです。"action" キーワード引数は、コマ
ンドライン引数がどう処理されるかを指定します。提供されているアクション
は:

* "'store'" - これは単に引数の値を格納します。これはデフォルトのアク
  シ ョンです。例えば:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo')
     >>> parser.parse_args('--foo 1'.split())
     Namespace(foo='1')

* "'store_const'" - このアクションは const キーワード引数で指定され
  た 値を格納します。"'store_const'" アクションは、何かの種類のフラグ
  を指 定するオプション引数によく使われます。例えば:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', action='store_const', const=42)
     >>> parser.parse_args(['--foo'])
     Namespace(foo=42)

* "'store_true'", "'store_false'" - これらは "'store_const'" の特別
  版 で、それぞれ "True" と "False" を格納するのに使います。 さらに、
  これ らはデフォルト値をそれぞれ "False" と "True" にします。例えば:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', action='store_true')
     >>> parser.add_argument('--bar', action='store_false')
     >>> parser.add_argument('--baz', action='store_false')
     >>> parser.parse_args('--foo --bar'.split())
     Namespace(bar=False, baz=True, foo=True)

* "'append'" - このアクションはリストを格納して、各引数の値をそのリ
  ス トに追加します。このアクションは複数回指定を許可したいオプション
  に便 利です。利用例:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', action='append')
     >>> parser.parse_args('--foo 1 --foo 2'.split())
     Namespace(foo=['1', '2'])

* "'append_const'" - このアクションはリストを格納して、const キーワ
  ー ド引数に与えられた値をそのリストに追加します (const キーワード引
  数の デフォルト値はあまり役に立たない "None" であることに注意)。
  "'append_const'" アクションは、定数を同じリストに複数回格納する場合
  に便利です。例えば:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--str', dest='types', action='append_const', const=str)
     >>> parser.add_argument('--int', dest='types', action='append_const', const=int)
     >>> parser.parse_args('--str --int'.split())
     Namespace(types=[<type 'str'>, <type 'int'>])

* "'count'" - このアクションはキーワード引数の数を数えます。例えば、
  verboseレベルを上げるのに役立ちます:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--verbose', '-v', action='count')
     >>> parser.parse_args(['-vvv'])
     Namespace(verbose=3)

* "'help'" - このアクションは現在のパーサー中のすべてのオプションの
  ヘ ルプメッセージを表示し、終了します。出力の生成方法の詳細について
  は "ArgumentParser" を参照してください。

* "'version'" - このアクションは "add_argument()" の呼び出しに
  "version=" キーワード引数を期待します。指定されたときはバージョン情
  報を表示して終了します:

     >>> import argparse
     >>> parser = argparse.ArgumentParser(prog='PROG')
     >>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
     >>> parser.parse_args(['--version'])
     PROG 2.0

Action のサブクラスまたは同じインターフェイスを実装したほかのオブジェ
クト渡すことで、任意のアクションを指定することもできます。これをするお
奨めの方法は、 "argparse.Action" を継承して、 "__call__" と、必要であ
れば "__init__" をオーバライドすることです。

カスタムアクションの例です:

   >>> class FooAction(argparse.Action):
   ...     def __init__(self, option_strings, dest, nargs=None, **kwargs):
   ...         if nargs is not None:
   ...             raise ValueError("nargs not allowed")
   ...         super(FooAction, self).__init__(option_strings, dest, **kwargs)
   ...     def __call__(self, parser, namespace, values, option_string=None):
   ...         print '%r %r %r' % (namespace, values, option_string)
   ...         setattr(namespace, self.dest, values)
   ...
   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', action=FooAction)
   >>> parser.add_argument('bar', action=FooAction)
   >>> args = parser.parse_args('1 --foo 2'.split())
   Namespace(bar=None, foo=None) '1' None
   Namespace(bar='1', foo=None) '2' '--foo'
   >>> args
   Namespace(bar='1', foo='2')

詳細は "Action" を参照してください。


15.4.3.3. nargs
---------------

ArgumentParser オブジェクトは通常1つのコマンドライン引数を1つのアクシ
ョンに渡します。"nargs" キーワード引数は1つのアクションにそれ以外の数
のコマンドライン引数を割り当てます。指定できる値は:

* "N" (整数) -- "N" 個の引数がコマンドラインから集められ、リストに格
  納 されます。例えば:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', nargs=2)
     >>> parser.add_argument('bar', nargs=1)
     >>> parser.parse_args('c --foo a b'.split())
     Namespace(bar=['c'], foo=['a', 'b'])

  "nargs=1" は1要素のリストを作ることに注意してください。これはデフォ
  ルトの、要素がそのまま属性になる動作とは異なります。

* "'?'" -- 可能なら1つの引数がコマンドラインから取られ、1つのアイテ
  ム を作ります。コマンドライン引数が存在しない場合、default の値が生
  成さ れます。オプション引数の場合、さらにオプション引数が指定され、
  その後 にコマンドライン引数が無いというケースもありえます。この場合
  は const の値が生成されます。この動作の例です:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', nargs='?', const='c', default='d')
     >>> parser.add_argument('bar', nargs='?', default='d')
     >>> parser.parse_args(['XX', '--foo', 'YY'])
     Namespace(bar='XX', foo='YY')
     >>> parser.parse_args(['XX', '--foo'])
     Namespace(bar='XX', foo='c')
     >>> parser.parse_args([])
     Namespace(bar='d', foo='d')

  "nargs='?'" のよくある利用例の1つは、入出力ファイルの指定オプション
  です:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
     ...                     default=sys.stdin)
     >>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
     ...                     default=sys.stdout)
     >>> parser.parse_args(['input.txt', 'output.txt'])
     Namespace(infile=<open file 'input.txt', mode 'r' at 0x...>,
               outfile=<open file 'output.txt', mode 'w' at 0x...>)
     >>> parser.parse_args([])
     Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>,
               outfile=<open file '<stdout>', mode 'w' at 0x...>)

* "'*'" -- すべてのコマンドライン引数がリストに集められます。複数の
  位 置引数が "nargs='*'" を持つことにあまり意味はありませんが、複数の
  オ プション引数が "nargs='*'" を持つことはありえます。例えば:

     >>> parser = argparse.ArgumentParser()
     >>> parser.add_argument('--foo', nargs='*')
     >>> parser.add_argument('--bar', nargs='*')
     >>> parser.add_argument('baz', nargs='*')
     >>> parser.parse_args('a b --foo x y --bar 1 2'.split())
     Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])

* "'+'" -- "'*'" と同じように、すべてのコマンドライン引数をリストに
  集 めます。加えて、最低でも1つのコマンドライン引数が存在しない場合に
  エ ラーメッセージを生成します。例えば:

     >>> parser = argparse.ArgumentParser(prog='PROG')
     >>> parser.add_argument('foo', nargs='+')
     >>> parser.parse_args(['a', 'b'])
     Namespace(foo=['a', 'b'])
     >>> parser.parse_args([])
     usage: PROG [-h] foo [foo ...]
     PROG: error: too few arguments

* "argparse.REMAINDER" -- コマンドライン引数の残りすべてをリストとし
  て 集めます。これは他のコマンドラインツールに対して処理を渡すような
  ツー ルによく使われます。例えば:

     >>> parser = argparse.ArgumentParser(prog='PROG')
     >>> parser.add_argument('--foo')
     >>> parser.add_argument('command')
     >>> parser.add_argument('args', nargs=argparse.REMAINDER)
     >>> print parser.parse_args('--foo B cmd --arg1 XX ZZ'.split())
     Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')

"nargs" キーワード引数が指定されない場合、消費される引数の数は action
によって決定されます。通常これは、1つのコマンドライン引数は1つのアイテ
ムになる (リストにはならない) ことを意味します。


15.4.3.4. const
---------------

"add_argument()" の "const" 引数は、コマンドライン引数から読み込まれな
いけれども "ArgumentParser" のいくつかのアクションで必要とされる値のた
めに使われます。この引数のよくある2つの使用法は:

* "add_argument()" が "action='store_const'" か
  "action='append_const'" で呼び出された時、これらのアクションは
  "const" の値を "parse_args()" が返すオブジェクトの属性に追加します。
  サンプルは action の説明を参照してください。

* "add_argument()" がオプション文字列 ("-f" や "--foo") と
  "nargs='?'" で呼び出された場合。この場合0個か1つのコマンドライン引数
  を取るオプシ ョン引数が作られます。オプション引数にコマンドライン引
  数が続かなかっ た場合、 "const" の値が代わりに利用されます。サンプル
  は nargs の説明 を参照してください。

"'store_const'" と "'append_const'" アクションでは、 "const" キーワー
ド引数を与える必要があります。他のアクションでは、デフォルトは "None"
になります。


15.4.3.5. default
-----------------

すべてのオプション引数といくつかの位置引数はコマンドライン上で省略され
ることがあります。 "add_argument()" の "default" キーワード引数 (デフ
ォルト: "None") は、コマンドライン引数が存在しなかった場合に利用する値
を指定します。オプション引数では、オプション文字列がコマンドライン上に
存在しなかったときに "default" の値が利用されます:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', default=42)
   >>> parser.parse_args(['--foo', '2'])
   Namespace(foo='2')
   >>> parser.parse_args([])
   Namespace(foo=42)

"default" の値が文字列の場合、パーサーは値をコマンドライン引数のように
解析します。具体的には、パーサーは返り値 "Namespace" の属性を設定する
前に、type 変換引数が与えられていればそれらを適用します。そうでない場
合、パーサーは値をそのまま使用します:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--length', default='10', type=int)
   >>> parser.add_argument('--width', default=10.5, type=int)
   >>> parser.parse_args()
   Namespace(length=10, width=10.5)

nargs が "?" か "*" である位置引数では、コマンドライン引数が指定されな
かった場合 "default" の値が使われます。例えば:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('foo', nargs='?', default=42)
   >>> parser.parse_args(['a'])
   Namespace(foo='a')
   >>> parser.parse_args([])
   Namespace(foo=42)

"default=argparse.SUPPRESS" を渡すと、コマンドライン引数が存在しないと
きに属性の追加をしなくなります。:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', default=argparse.SUPPRESS)
   >>> parser.parse_args([])
   Namespace()
   >>> parser.parse_args(['--foo', '1'])
   Namespace(foo='1')


15.4.3.6. type
--------------

デフォルトでは、"ArgumentParser" オブジェクトはコマンドライン引数を単
なる文字列として読み込みます。しかし、コマンドラインの文字列は
"float", "int" など別の型として扱うべき事がよくあります。
"add_argument()" の "type" キーワード引数により型チェックと型変換を行
うことができます。一般的なビルトインデータ型や関数を "type" 引数の値と
して直接指定できます:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('foo', type=int)
   >>> parser.add_argument('bar', type=file)
   >>> parser.parse_args('2 temp.txt'.split())
   Namespace(bar=<open file 'temp.txt', mode 'r' at 0x...>, foo=2)

"type" 引数がデフォルト引数に適用されている場合の情報は、default キー
ワード引数の節を参照してください。

いろいろな種類のファイルを簡単に扱うために、 argparse モジュールは
"file" オブジェクトの "mode=", "bufsize=" 引数を取る FileType ファクト
リを提供しています。例えば、書き込み可能なファイルを作るために
"FileType('w')" を利用できます:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('bar', type=argparse.FileType('w'))
   >>> parser.parse_args(['out.txt'])
   Namespace(bar=<open file 'out.txt', mode 'w' at 0x...>)

"type=" には1つの文字列を引数に受け取って変換結果を返すような任意の呼
び出し可能オブジェクトを渡すことができます:

   >>> def perfect_square(string):
   ...     value = int(string)
   ...     sqrt = math.sqrt(value)
   ...     if sqrt != int(sqrt):
   ...         msg = "%r is not a perfect square" % string
   ...         raise argparse.ArgumentTypeError(msg)
   ...     return value
   ...
   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('foo', type=perfect_square)
   >>> parser.parse_args(['9'])
   Namespace(foo=9)
   >>> parser.parse_args(['7'])
   usage: PROG [-h] foo
   PROG: error: argument foo: '7' is not a perfect square

さらに、choices キーワード引数を使って、値の範囲をチェックすることもで
きます:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('foo', type=int, choices=xrange(5, 10))
   >>> parser.parse_args(['7'])
   Namespace(foo=7)
   >>> parser.parse_args(['11'])
   usage: PROG [-h] {5,6,7,8,9}
   PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)

詳細は choices 節を参照してください。


15.4.3.7. choices
-----------------

コマンドライン引数をいくつかの選択肢の中から選ばせたい場合があります。
これは "add_argument()" に *choices* キーワード引数を渡すことで可能で
す。コマンドラインを解析する時、引数の値がチェックされ、その値が選択肢
の中に含まれていない場合はエラーメッセージを表示します:

   >>> parser = argparse.ArgumentParser(prog='game.py')
   >>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
   >>> parser.parse_args(['rock'])
   Namespace(move='rock')
   >>> parser.parse_args(['fire'])
   usage: game.py [-h] {rock,paper,scissors}
   game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
   'paper', 'scissors')

*choices* コンテナーに含まれているかどうかのチェックは、type による型
変換が 実行された後であることに注意してください。なので、*choices* に
格納する オブジェクトの型は指定された type にマッチしている必要があり
ます:

   >>> parser = argparse.ArgumentParser(prog='doors.py')
   >>> parser.add_argument('door', type=int, choices=range(1, 4))
   >>> print(parser.parse_args(['3']))
   Namespace(door=3)
   >>> parser.parse_args(['4'])
   usage: doors.py [-h] {1,2,3}
   doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)

"in" 演算をサポートしている任意のオブジェクトを *choices* に渡すことが
できます。 なので、 "dict", "set", その他カスタムコンテナーなどは全て
サポート しています。


15.4.3.8. required
------------------

通常 "argparse" モジュールは、"-f" や "--bar" といったフラグは *任意*
の引数 (オプション引数) だと仮定し、コマンドライン上になくても良いもの
として扱います。フラグの指定を *必須* にするには、"add_argument()" の
"required=" キーワード引数に "True" を指定します:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', required=True)
   >>> parser.parse_args(['--foo', 'BAR'])
   Namespace(foo='BAR')
   >>> parser.parse_args([])
   usage: argparse.py [-h] [--foo FOO]
   argparse.py: error: option --foo is required

上の例のように、引数が "required" と指定されると、"parse_args()" はそ
のフラグがコマンドラインに存在しないときにエラーを表示します。

注釈: ユーザーは、通常 *フラグ* の指定は *任意* であると認識している
  ため、 必須にするのは一般的には悪いやり方で、できる限り避けるべきで
  す。


15.4.3.9. help
--------------

"help" の値はその引数の簡潔な説明を含む文字列です。ユーザーが (コマン
ドライン上で "-h" か "--help" を指定するなどして) ヘルプを要求したとき
、この "help" の説明が各引数に表示されます:

   >>> parser = argparse.ArgumentParser(prog='frobble')
   >>> parser.add_argument('--foo', action='store_true',
   ...                     help='foo the bars before frobbling')
   >>> parser.add_argument('bar', nargs='+',
   ...                     help='one of the bars to be frobbled')
   >>> parser.parse_args(['-h'])
   usage: frobble [-h] [--foo] bar [bar ...]

   positional arguments:
    bar     one of the bars to be frobbled

   optional arguments:
    -h, --help  show this help message and exit
    --foo   foo the bars before frobbling

"help" 文字列には、プログラム名や引数の default などを繰り返し記述する
のを避けるためのフォーマット指定子を含めることができます。利用できる指
定子には、プログラム名 "%(prog)s" と、 "%(default)s" や "%(type)s" な
ど "add_argument()" のキーワード引数の多くが含まれます:

   >>> parser = argparse.ArgumentParser(prog='frobble')
   >>> parser.add_argument('bar', nargs='?', type=int, default=42,
   ...                     help='the bar to %(prog)s (default: %(default)s)')
   >>> parser.print_help()
   usage: frobble [-h] [bar]

   positional arguments:
    bar     the bar to frobble (default: 42)

   optional arguments:
    -h, --help  show this help message and exit

"argparse" は "help" に "argparse.SUPPRESS" を設定することで、特定のオ
プションをヘルプに表示させないことができます:

   >>> parser = argparse.ArgumentParser(prog='frobble')
   >>> parser.add_argument('--foo', help=argparse.SUPPRESS)
   >>> parser.print_help()
   usage: frobble [-h]

   optional arguments:
     -h, --help  show this help message and exit


15.4.3.10. metavar
------------------

"ArgumentParser" がヘルプメッセージを出力する時、各引数に対してなんら
かの 参照方法が必要です。デフォルトでは、 ArgumentParser オブジェクト
は各オブジェクトの "名前" として dest を利用します。デフォルトでは、位
置引数には dest の値をそのまま 利用し、オプション引数については dest
の値を大文字に変換して利用します。 なので、1つの "dest='bar'" である位
置引数は "bar" として参照されます。 1つのオプション引数 "--foo" が1つ
のコマンドライン引数を要求するときは、その引数は "FOO" として参照され
ます。例です:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo')
   >>> parser.add_argument('bar')
   >>> parser.parse_args('X --foo Y'.split())
   Namespace(bar='X', foo='Y')
   >>> parser.print_help()
   usage:  [-h] [--foo FOO] bar

   positional arguments:
    bar

   optional arguments:
    -h, --help  show this help message and exit
    --foo FOO

代わりの名前を、"metavar" として指定できます:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', metavar='YYY')
   >>> parser.add_argument('bar', metavar='XXX')
   >>> parser.parse_args('X --foo Y'.split())
   Namespace(bar='X', foo='Y')
   >>> parser.print_help()
   usage:  [-h] [--foo YYY] XXX

   positional arguments:
    XXX

   optional arguments:
    -h, --help  show this help message and exit
    --foo YYY

"metavar" は *表示される* 名前だけを変更することに注意してください。
"parse_args()" の返すオブジェクトの属性名は dest の値のままです。

"nargs" を指定した場合、metavar が複数回利用されるかもしれません。
"metavar" にタプルを渡すと、各引数に対して異なる名前を指定できます:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-x', nargs=2)
   >>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
   >>> parser.print_help()
   usage: PROG [-h] [-x X X] [--foo bar baz]

   optional arguments:
    -h, --help     show this help message and exit
    -x X X
    --foo bar baz


15.4.3.11. dest
---------------

ほとんどの "ArgumentParser" のアクションは "parse_args()" が返すオブジ
ェクトに対する属性として値を追加します。この属性の名前は
"add_argument()" の "dest" キーワード引数によって決定されます。位置引
数のアクションについては、 "dest" は通常 "add_argument()" の第一引数と
して渡します:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('bar')
   >>> parser.parse_args(['XXX'])
   Namespace(bar='XXX')

オプション引数のアクションについては、 "dest" の値は通常オプション文字
列から生成されます。 "ArgumentParser" は最初の長いオプション文字列を選
択し、先頭の "--" を除去することで "dest" の値を生成します。長いオプシ
ョン文字列が指定されていない場合、最初の短いオプション文字列から先頭の
"-" 文字を除去することで "dest" を生成します。先頭以外のすべての "-"
文字は、妥当な属性名になるように "_" 文字へ変換されます。次の例はこの
動作を示しています:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('-f', '--foo-bar', '--foo')
   >>> parser.add_argument('-x', '-y')
   >>> parser.parse_args('-f 1 -x 2'.split())
   Namespace(foo_bar='1', x='2')
   >>> parser.parse_args('--foo 1 -y 2'.split())
   Namespace(foo_bar='1', x='2')

"dest" にカスタムの属性名を与えることも可能です:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', dest='bar')
   >>> parser.parse_args('--foo XXX'.split())
   Namespace(bar='XXX')


15.4.3.12. Action クラス
------------------------

Acrtion クラスは Action API、すなわちコマンドラインからの引数を処理す
る呼び出し可能オブジェクトを返す呼び出し可能オブジェクトを実装します。
この API に従うあらゆるオブジェクトは "action" 引数として
"add_argument()" に渡すことが出来ます。

class argparse.Action(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Action オブジェクトは、コマンドラインからの一つ以上の文字列から単一の
引数を解析するのに必要とされる情報を表現するために、ArgumentParser に
よって使われます。Action クラス 2 つの位置引数と、 "action" それ自身を
除く "ArgumentParser.add_argument()" に渡される全てのキーワード引数を
受け付けなければなりません。

Action のインスタンス(あるいは "action" パラメータも渡す任意の
callable の返却値)は、属性 "dest", "option_strings", "default",
"type", "required", "help", などを定義しなければなりません。これらの属
性を定義するのを確実にするために最も簡単な方法は、 "Action.__init__"
を呼び出すことです。

Action インスタンスは callable でなければならず、従って、サブクラスは
4つの引数を受け取る "__call__" メソッドをオーバライドしなければなりま
せん:

* "parser" - このアクションを持っている ArgumentParser オブジェクト
  。

* "namespace" - "parse_args()" が返す "Namespace" オブジェクト。ほと
  ん どのアクションはこのオブジェクトに属性を "setattr()" を使って追加
  し ます。

* "values" - 型変換が適用された後の、関連付けられたコマンドライン引
  数 。型変換は "add_argument()" メソッドの type キーワード引数で指定
  され ます。

* "option_string" - このアクションを実行したオプション文字列。
  "option_string" 引数はオプションで、アクションが位置引数に関連付けら
  れた場合は渡されません。

"__call__" メソッドでは任意のアクションを行えますが、 典型的にはそれは
"dest", "values" に基づく "namespace" に属性をセットすることでしょう。


15.4.4. parse_args() メソッド
=============================

ArgumentParser.parse_args(args=None, namespace=None)

   引数の文字列をオブジェクトに変換し、namespace オブジェクトの属性に
   代入します。結果の namespace オブジェクトを返します。

   事前の "add_argument()" メソッドの呼び出しが、どのオブジェクトが生
   成されてどう代入されるかを決定します。詳細は "add_argument()" のド
   キュメントを参照してください。

   * args - List of strings to parse.  The default is taken from
     "sys.argv".

   * namespace - An object to take the attributes.  The default is a
     new empty "Namespace" object.


15.4.4.1. オプション値の文法
----------------------------

"parse_args()" メソッドはオプションの値があればそれを指定する複数の方
法をサポートしています。一番シンプルな方法は、オプションとその値は2つ
の別々の引数として渡されます:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-x')
   >>> parser.add_argument('--foo')
   >>> parser.parse_args(['-x', 'X'])
   Namespace(foo=None, x='X')
   >>> parser.parse_args(['--foo', 'FOO'])
   Namespace(foo='FOO', x=None)

長いオプション (1文字よりも長い名前を持ったオプション) では、オプショ
ンとその値は "=" で区切られた1つのコマンドライン引数として渡すこともで
きます:

   >>> parser.parse_args(['--foo=FOO'])
   Namespace(foo='FOO', x=None)

短いオプション (1文字のオプション) では、オプションとその値は連結して
渡すことができます:

   >>> parser.parse_args(['-xX'])
   Namespace(foo=None, x='X')

複数の短いオプションは、最後の1つ (か、0個) のオプションだけが値を要求
する場合には、1つの接頭辞 "-" だけで連結できます:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-x', action='store_true')
   >>> parser.add_argument('-y', action='store_true')
   >>> parser.add_argument('-z')
   >>> parser.parse_args(['-xyzZ'])
   Namespace(x=True, y=True, z='Z')


15.4.4.2. 不正な引数
--------------------

"parse_args()" は、コマンドラインの解析中に、曖昧なオプション、不正な
型、不正なオプション、位置引数の数の不一致などのエラーを検証します。そ
れらのエラーが発生した場合、エラーメッセージと使用法メッセージを表示し
て終了します:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('--foo', type=int)
   >>> parser.add_argument('bar', nargs='?')

   >>> # invalid type
   >>> parser.parse_args(['--foo', 'spam'])
   usage: PROG [-h] [--foo FOO] [bar]
   PROG: error: argument --foo: invalid int value: 'spam'

   >>> # invalid option
   >>> parser.parse_args(['--bar'])
   usage: PROG [-h] [--foo FOO] [bar]
   PROG: error: no such option: --bar

   >>> # wrong number of arguments
   >>> parser.parse_args(['spam', 'badger'])
   usage: PROG [-h] [--foo FOO] [bar]
   PROG: error: extra arguments found: badger


15.4.4.3. "-" を含む引数
------------------------

"parse_args()" メソッドは、ユーザーが明らかなミスをした場合はエラーを
表示しますが、いくつか本質的に曖昧な場面があります。例えば、コマンドラ
イン引数 "-1" は、オプションの指定かもしれませんし位置引数かもしれませ
ん。"parse_args()" メソッドはこれを次のように扱います: 負の数として解
釈でき、パーサーに負の数のように解釈できるオプションが存在しない場合に
のみ、"-" で始まる位置引数になりえます:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-x')
   >>> parser.add_argument('foo', nargs='?')

   >>> # no negative number options, so -1 is a positional argument
   >>> parser.parse_args(['-x', '-1'])
   Namespace(foo=None, x='-1')

   >>> # no negative number options, so -1 and -5 are positional arguments
   >>> parser.parse_args(['-x', '-1', '-5'])
   Namespace(foo='-5', x='-1')

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-1', dest='one')
   >>> parser.add_argument('foo', nargs='?')

   >>> # negative number options present, so -1 is an option
   >>> parser.parse_args(['-1', 'X'])
   Namespace(foo=None, one='X')

   >>> # negative number options present, so -2 is an option
   >>> parser.parse_args(['-2'])
   usage: PROG [-h] [-1 ONE] [foo]
   PROG: error: no such option: -2

   >>> # negative number options present, so both -1s are options
   >>> parser.parse_args(['-1', '-1'])
   usage: PROG [-h] [-1 ONE] [foo]
   PROG: error: argument -1: expected one argument

"-" で始まる位置引数があって、それが負の数として解釈できない場合、ダミ
ーの引数 "'--'" を挿入して、"parse_args()" にそれ以降のすべてが位置引
数だと教えることができます:

   >>> parser.parse_args(['--', '-f'])
   Namespace(foo='-f', one=None)


15.4.4.4. 引数の短縮形 (先頭文字でのマッチング)
-----------------------------------------------

"parse_args()" メソッドでは長いオプションを曖昧さがない範囲 (先頭の文
字が一意であること) で短縮できます:

   >>> parser = argparse.ArgumentParser(prog='PROG')
   >>> parser.add_argument('-bacon')
   >>> parser.add_argument('-badger')
   >>> parser.parse_args('-bac MMM'.split())
   Namespace(bacon='MMM', badger=None)
   >>> parser.parse_args('-bad WOOD'.split())
   Namespace(bacon=None, badger='WOOD')
   >>> parser.parse_args('-ba BA'.split())
   usage: PROG [-h] [-bacon BACON] [-badger BADGER]
   PROG: error: ambiguous option: -ba could match -badger, -bacon

引数が複数のオプションになり得る場合はエラーになります。


15.4.4.5. "sys.argv" 以外
-------------------------

ArgumentParser が "sys.argv" 以外の引数を解析できると役に立つ場合があ
ります。その場合は文字列のリストを "parse_args()" に渡します。これはイ
ンタラクティブプロンプトからテストするときに便利です:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument(
   ...     'integers', metavar='int', type=int, choices=xrange(10),
   ...     nargs='+', help='an integer in the range 0..9')
   >>> parser.add_argument(
   ...     '--sum', dest='accumulate', action='store_const', const=sum,
   ...     default=max, help='sum the integers (default: find the max)')
   >>> parser.parse_args(['1', '2', '3', '4'])
   Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
   >>> parser.parse_args(['1', '2', '3', '4', '--sum'])
   Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])


15.4.4.6. Namespace オブジェクト
--------------------------------

class argparse.Namespace

   "parse_args()" が属性を格納して返すためのオブジェクトにデフォルトで
   使用されるシンプルなクラスです。

デフォルトでは、 "parse_args()" は "Namespace" の新しいオブジェクトに
必要な属性を設定して返します。このクラスはシンプルに設計されており、単
に読みやすい文字列表現を持った "object" のサブクラスです。もし属性を辞
書のように扱える方が良ければ、標準的な Python のイディオム "vars()" を
利用できます:

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo')
   >>> args = parser.parse_args(['--foo', 'BAR'])
   >>> vars(args)
   {'foo': 'BAR'}

"ArgumentParser" が、新しい "Namespace" オブジェクトではなく、既存のオ
ブジェクトに属性を設定する方が良い場合があります。これは "namespace="
キーワード引数を指定することで可能です:

   >>> class C(object):
   ...     pass
   ...
   >>> c = C()
   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo')
   >>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
   >>> c.foo
   'BAR'


15.4.5. その他のユーティリティ
==============================


15.4.5.1. サブコマンド
----------------------

ArgumentParser.add_subparsers([title][, description][, prog][, parser_class][, action][, option_string][, dest][, help][, metavar])

   多くのプログラムは、その機能をサブコマンドへと分割します。 例えば
   "svn" プログラムは "svn checkout", "svn update", "svn commit" など
   のサブコマンドを利用できます。 機能をサブコマンドに分割するのは、プ
   ログラムがいくつかの異なった機能を持っていて、 それぞれが異なるコマ
   ンドライン引数を必要とする場合には良いアイデアです。
   "ArgumentParser" は "add_subparsers()" メソッドによりサブコマンドを
   サポートしています。 "add_subparsers()" メソッドは通常引数なしに呼
   び出され、 特殊なアクションオブジェクトを返します。このオブジェクト
   には1つのメソッド "add_parser()" があり、コマンド名と
   "ArgumentParser" コンストラクターの任意の引数を受け取り、通常の方法
   で操作できる "ArgumentParser" オブジェクトを返します。

   パラメーターの説明:

   * title - ヘルプ出力でのサブパーサーグループのタイトル; デフォル
     ト は、description が指定されている場合は "subcommands" に、指定
     され ていない場合は位置引数のタイトルになります

   * description - ヘルプ出力に表示されるサブパーサーグループの説明
     で す。デフォルトは "None" になります

   * prog - サブコマンドのヘルプに表示される使用方法の説明です。デフ
     ォ ルトではプログラム名と位置引数の後ろに、サブパーサーの引数が続
     き ます

   * parser_class - サブパーサーのインスタンスを作成する時に使用され
     る クラスです。デフォルトでは現在のパーサーのクラス (例:
     ArgumentParser) になります

   * action - コマンドラインにこの引数があった時の基本のアクション。

   * dest - サブコマンド名を格納する属性の名前です。デフォルトは
     "None" で値は格納されません

   * help - ヘルプ出力に表示されるサブパーサーグループのヘルプです。
     デ フォルトは "None" です

   * metavar - 利用可能なサブコマンドをヘルプ内で表示するための文字
     列 です。デフォルトは "None" で、サブコマンドを {cmd1, cmd2, ..}
     の ような形式で表します

   いくつかの使用例:

      >>> # create the top-level parser
      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> parser.add_argument('--foo', action='store_true', help='foo help')
      >>> subparsers = parser.add_subparsers(help='sub-command help')
      >>>
      >>> # create the parser for the "a" command
      >>> parser_a = subparsers.add_parser('a', help='a help')
      >>> parser_a.add_argument('bar', type=int, help='bar help')
      >>>
      >>> # create the parser for the "b" command
      >>> parser_b = subparsers.add_parser('b', help='b help')
      >>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')
      >>>
      >>> # parse some argument lists
      >>> parser.parse_args(['a', '12'])
      Namespace(bar=12, foo=False)
      >>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
      Namespace(baz='Z', foo=True)

   "parse_args()" が返すオブジェクトにはメインパーサーとコマンドライン
   で選択されたサブパーサーによる属性だけが設定されており、選択されな
   かったサブコマンドのパーサーの属性が設定されていないことに注意して
   ください。なので、上の例では、"a" コマンドが指定されたときは "foo",
   "bar" 属性だけが存在し、"b" コマンドが指定されたときは "foo", "baz"
   属性だけが存在しています。

   同じように、サブパーサーにヘルプメッセージが要求された場合は、その
   パーサーに対するヘルプだけが表示されます。ヘルプメッセージには親パ
   ーサーや兄弟パーサーのヘルプメッセージを表示しません。 (ただし、各
   サブパーサーコマンドのヘルプメッセージは、上の例にもあるように
   "add_parser()" の "help=" 引数によって指定できます)

      >>> parser.parse_args(['--help'])
      usage: PROG [-h] [--foo] {a,b} ...

      positional arguments:
        {a,b}   sub-command help
          a     a help
          b     b help

      optional arguments:
        -h, --help  show this help message and exit
        --foo   foo help

      >>> parser.parse_args(['a', '--help'])
      usage: PROG a [-h] bar

      positional arguments:
        bar     bar help

      optional arguments:
        -h, --help  show this help message and exit

      >>> parser.parse_args(['b', '--help'])
      usage: PROG b [-h] [--baz {X,Y,Z}]

      optional arguments:
        -h, --help     show this help message and exit
        --baz {X,Y,Z}  baz help

   "add_subparsers()" メソッドは "title" と "description" キーワード引
   数もサポートしています。どちらかが存在する場合、サブパーサーのコマ
   ンドはヘルプ出力でそれぞれのグループの中に表示されます。例えば:

      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers(title='subcommands',
      ...                                    description='valid subcommands',
      ...                                    help='additional help')
      >>> subparsers.add_parser('foo')
      >>> subparsers.add_parser('bar')
      >>> parser.parse_args(['-h'])
      usage:  [-h] {foo,bar} ...

      optional arguments:
        -h, --help  show this help message and exit

      subcommands:
        valid subcommands

        {foo,bar}   additional help

   サブコマンドを扱う1つの便利な方法は "add_subparsers()" メソッドと
   "set_defaults()" を組み合わせて、各サブパーサーにどの Python 関数を
   実行するかを教えることです。例えば:

      >>> # sub-command functions
      >>> def foo(args):
      ...     print args.x * args.y
      ...
      >>> def bar(args):
      ...     print '((%s))' % args.z
      ...
      >>> # create the top-level parser
      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers()
      >>>
      >>> # create the parser for the "foo" command
      >>> parser_foo = subparsers.add_parser('foo')
      >>> parser_foo.add_argument('-x', type=int, default=1)
      >>> parser_foo.add_argument('y', type=float)
      >>> parser_foo.set_defaults(func=foo)
      >>>
      >>> # create the parser for the "bar" command
      >>> parser_bar = subparsers.add_parser('bar')
      >>> parser_bar.add_argument('z')
      >>> parser_bar.set_defaults(func=bar)
      >>>
      >>> # parse the args and call whatever function was selected
      >>> args = parser.parse_args('foo 1 -x 2'.split())
      >>> args.func(args)
      2.0
      >>>
      >>> # parse the args and call whatever function was selected
      >>> args = parser.parse_args('bar XYZYX'.split())
      >>> args.func(args)
      ((XYZYX))

   こうすると、 "parse_args()" が引数の解析が終わってから適切な関数を
   呼び出すようになります。このように関数をアクションに関連付けるのは
   大抵サブパーサーごとに異なるアクションを扱う最も簡単な方法です。た
   だし、実行されたサブパーサーの名前を確認する必要がある場合は、
   "add_subparsers()" を呼び出すときに "dest" キーワードを指定できます
   :

      >>> parser = argparse.ArgumentParser()
      >>> subparsers = parser.add_subparsers(dest='subparser_name')
      >>> subparser1 = subparsers.add_parser('1')
      >>> subparser1.add_argument('-x')
      >>> subparser2 = subparsers.add_parser('2')
      >>> subparser2.add_argument('y')
      >>> parser.parse_args(['2', 'frobble'])
      Namespace(subparser_name='2', y='frobble')


15.4.5.2. FileType オブジェクト
-------------------------------

class argparse.FileType(mode='r', bufsize=None)

   "FileType" ファクトリは "ArgumentParser.add_argument()" の type 引
   数に渡すことができるオブジェクトを生成します。 type が "FileType"
   オブジェクトである引数はコマンドライン引数を、指定されたモード、バ
   ッファーサイズでファイルとして開きます:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--output', type=argparse.FileType('wb', 0))
      >>> parser.parse_args(['--output', 'out'])
      Namespace(output=<open file 'out', mode 'wb' at 0x...>)

   FileType オブジェクトは擬似引数 "'-'" を識別し、読み込み用の
   "FileType" であれば "sys.stdin" を、書き込み用の "FileType" であれ
   ば "sys.stdout" に変換します:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('infile', type=argparse.FileType('r'))
      >>> parser.parse_args(['-'])
      Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>)


15.4.5.3. 引数グループ
----------------------

ArgumentParser.add_argument_group(title=None, description=None)

   デフォルトでは、 "ArgumentParser" はヘルプメッセージを表示するとき
   に、コマンドライン引数を "位置引数" と "オプション引数" にグループ
   化します。このデフォルトの動作よりも良い引数のグループ化方法がある
   場合、 "add_argument_group()" メソッドで適切なグループを作成できま
   す:

      >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
      >>> group = parser.add_argument_group('group')
      >>> group.add_argument('--foo', help='foo help')
      >>> group.add_argument('bar', help='bar help')
      >>> parser.print_help()
      usage: PROG [--foo FOO] bar

      group:
        bar    bar help
        --foo FOO  foo help

   "add_argument_group()" メソッドは、通常の "ArgumentParser" と同じよ
   うな "add_argument()" メソッドを持つ引数グループオブジェクトを返し
   ます。引数がグループに追加された時、パーサーはその引数を通常の引数
   のように扱いますが、ヘルプメッセージではその引数を分離されたグルー
   プの中に表示します。 "add_argument_group()" メソッドには、この表示
   をカスタマイズするための *title* と *description* 引数があります:

      >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
      >>> group1 = parser.add_argument_group('group1', 'group1 description')
      >>> group1.add_argument('foo', help='foo help')
      >>> group2 = parser.add_argument_group('group2', 'group2 description')
      >>> group2.add_argument('--bar', help='bar help')
      >>> parser.print_help()
      usage: PROG [--bar BAR] foo

      group1:
        group1 description

        foo    foo help

      group2:
        group2 description

        --bar BAR  bar help

   ユーザー定義グループにないすべての引数は通常の "位置引数" と "オプ
   ション引数" セクションに表示されます。


15.4.5.4. 相互排他
------------------

ArgumentParser.add_mutually_exclusive_group(required=False)

   相互排他グループを作ります。"argparse" は相互排他グループの中でただ
   1つの引数のみが存在することを確認します:

      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> group = parser.add_mutually_exclusive_group()
      >>> group.add_argument('--foo', action='store_true')
      >>> group.add_argument('--bar', action='store_false')
      >>> parser.parse_args(['--foo'])
      Namespace(bar=True, foo=True)
      >>> parser.parse_args(['--bar'])
      Namespace(bar=False, foo=False)
      >>> parser.parse_args(['--foo', '--bar'])
      usage: PROG [-h] [--foo | --bar]
      PROG: error: argument --bar: not allowed with argument --foo

   "add_mutually_exclusive_group()" メソッドの引数 *required* に True
   値を指定すると、その相互排他引数のどれか 1つを選ぶことが要求さます:

      >>> parser = argparse.ArgumentParser(prog='PROG')
      >>> group = parser.add_mutually_exclusive_group(required=True)
      >>> group.add_argument('--foo', action='store_true')
      >>> group.add_argument('--bar', action='store_false')
      >>> parser.parse_args([])
      usage: PROG [-h] (--foo | --bar)
      PROG: error: one of the arguments --foo --bar is required

   現在のところ、相互排他引数グループは "add_argument_group()" の
   *title* と *description* 引数をサポートしていません。


15.4.5.5. パーサーのデフォルト値
--------------------------------

ArgumentParser.set_defaults(**kwargs)

   ほとんどの場合、 "parse_args()" が返すオブジェクトの属性はコマンド
   ライン引数の内容と引数のアクションによってのみ決定されます。
   "set_defaults()" を使うと与えられたコマンドライン引数の内容によらず
   追加の属性を決定することが可能です:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('foo', type=int)
      >>> parser.set_defaults(bar=42, baz='badger')
      >>> parser.parse_args(['736'])
      Namespace(bar=42, baz='badger', foo=736)

   パーサーレベルのデフォルト値は常に引数レベルのデフォルト値を上書き
   します:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', default='bar')
      >>> parser.set_defaults(foo='spam')
      >>> parser.parse_args([])
      Namespace(foo='spam')

   パーサーレベルの default は、複数のパーサーを扱うときに特に便利です
   。このタイプの例については "add_subparsers()" メソッドを参照してく
   ださい。

ArgumentParser.get_default(dest)

   "add_argument()" か "set_defaults()" によって指定された、 namespace
   の属性のデフォルト値を取得します:

      >>> parser = argparse.ArgumentParser()
      >>> parser.add_argument('--foo', default='badger')
      >>> parser.get_default('foo')
      'badger'


15.4.5.6. ヘルプの表示
----------------------

ほとんどの典型的なアプリケーションでは、"parse_args()" が使用法やエラ
ーメッセージのフォーマットと表示について面倒を見ます。しかし、いくつか
のフォーマットメソッドが利用できます:

ArgumentParser.print_usage(file=None)

   "ArgumentParser" がコマンドラインからどう実行されるべきかの短い説明
   を表示します。 *file* が "None" の時は、 "sys.stdout" に出力されま
   す。

ArgumentParser.print_help(file=None)

   プログラムの使用法と "ArgumentParser" に登録された引数についての情
   報を含むヘルプメッセージを表示します。 *file* が "None" の時は、
   "sys.stdout" に出力されます。

これらのメソッドの、表示する代わりにシンプルに文字列を返すバージョンも
あります:

ArgumentParser.format_usage()

   "ArgumentParser" がコマンドラインからどう実行されるべきかの短い説明
   を格納した文字列を返します。

ArgumentParser.format_help()

   プログラムの使用法と "ArgumentParser" に登録された引数についての情
   報を含むヘルプメッセージを格納した文字列を返します。


15.4.5.7. 部分解析
------------------

ArgumentParser.parse_known_args(args=None, namespace=None)

ときどき、スクリプトがコマンドライン引数のいくつかだけを解析し、残りの
引数は別のスクリプトやプログラムに渡すことがあります。こういった場合、
"parse_known_args()" メソッドが便利です。これは "parse_args()" と同じ
ように動作しますが、余分な引数が存在してもエラーを生成しません。代わり
に、評価された namespace オブジェクトと、残りの引数文字列のリストから
なる2要素タプルを返します。

   >>> parser = argparse.ArgumentParser()
   >>> parser.add_argument('--foo', action='store_true')
   >>> parser.add_argument('bar')
   >>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
   (Namespace(bar='BAR', foo=True), ['--badger', 'spam'])

警告: 先頭文字でのマッチング ルールは "parse_known_args()" にも適用
  されま す。パーサーはそれが既知のオプションの先頭文字の一つであった
  場合、そ れを引数リストに残さず 1 個のオプションの消費とする場合があ
  ります。


15.4.5.8. ファイル解析のカスタマイズ
------------------------------------

ArgumentParser.convert_arg_line_to_args(arg_line)

   ファイルから引数を読み込む場合 ("ArgumentParser" コンストラクターの
   *fromfile_prefix_chars* キーワード引数を参照)、1行につき1つの引数を
   読み込みます。 "convert_arg_line_to_args()" を変更することでこの動
   作をカスタマイズできます。

   このメソッドは、引数ファイルから読まれた文字列である1つの引数
   *arg_line* を受け取ります。そしてその文字列を解析した結果の引数のリ
   ストを返します。このメソッドはファイルから1行読みこむごとに、順番に
   呼ばれます。

   このメソッドを上書きする便利な例として、スペースで区切られた単語を
   1 つの引数として扱います:

      def convert_arg_line_to_args(self, arg_line):
          return arg_line.split()


15.4.5.9. 終了メソッド
----------------------

ArgumentParser.exit(status=0, message=None)

   このメソッドは、*message* が指定されていればそれを表示した後、指定
   された終了ステータス *status* でプログラムを終了します。

ArgumentParser.error(message)

   このメソッドは *message* を含む使用法メッセージを標準エラーに表示し
   て、終了ステータス 2 でプログラムを終了します。


15.4.6. optparse からのアップグレード
=====================================

もともと、"argparse" モジュールは "optparse" モジュールとの互換性を保
って開発しようと試みられました。しかし、特に新しい "nargs=" 指定子とよ
り良い使用法メッセージのために必要な変更のために、"optparse" を透過的
に拡張することは難しかったのです。"optparse" のほとんどすべてがコピー
アンドペーストされたりモンキーパッチを当てられたりしたとき、もはや後方
互換性を保とうとすることは現実的ではありませんでした。

"argparse" モジュールは標準ライブラリ "optparse" モジュールを、以下を
含むたくさんの方法で改善しています:

* 位置指定引数を扱う

* サブコマンドのサポート

* "+", "/" のような代替オプションプレフィクスを許容する

* zero-or-more スタイル、one-or-more スタイルの引数を扱う

* より有益な使用方法メッセージの生成

* カスタム "type", カスタム "action" のために遥かに簡単なインターフ
  ェ イスを提供する

"optparse" から "argparse" への現実的なアップグレードパス:

* すべての "optparse.OptionParser.add_option()" の呼び出しを、
  "ArgumentParser.add_argument()" の呼び出しに置き換える。

* Replace "(options, args) = parser.parse_args()" with "args =
  parser.parse_args()" and add additional
  "ArgumentParser.add_argument()" calls for the positional arguments.
  Keep in mind that what was previously called "options", now in the
  "argparse" context is called "args".

* Replace "optparse.OptionParser.disable_interspersed_args()" by
  setting "nargs" of a positional argument to argparse.REMAINDER, or
  use "parse_known_args()" to collect unparsed argument strings in a
  separate list.

* コールバック・アクションと "callback_*" キーワード引数を "type" や
  "action" 引数に置き換える。

* "type" キーワード引数に渡していた文字列の名前を、それに応じたオブ
  ジ ェクト (例: int, float, complex, ...) に置き換える。

* "optparse.Values" を "Namespace" に置き換え、
  "optparse.OptionError" と "optparse.OptionValueError" を
  "ArgumentError" に置き換える。

* "%default" や "%prog" などの暗黙の引数を含む文字列を、
  "%(default)s" や "%(prog)s" などの、通常の Python で辞書を使う場合の
  フォーマット文 字列に置き換える。

* OptionParser のコンストラクターの "version" 引数を、
  "parser.add_argument('--version', action='version', version='<the
  version>')" に置き換える
