====== Python モジュール: argparse ======
===== 概要 =====
  * コマンドライン引数を処理するモジュール
  * sys.argv で処理してもいいけど、このモジュールを使うと簡潔に処理を記述できる
  * 同時に -H や --help でヘルプを表示することができる
  * ここでは、先頭に ''-'' が付いたものをオプション、その後に続くものを引数と呼ぶ (''--option argument'')

===== 使い方 =====
==== 基本 ====

  * 手順
    - import で argparse モジュール読み込み
    - parser オブジェクトで、引数を設定
    - parser オブジェクトを解析して、引数オブジェクトに渡す

  * 例: <code python>
import argparse

parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter)
parser.add_argument("foo", help = "positional1")
parser.add_argument("bar", help = "positional2")
parser.add_argument("--input", "-i", metavar = "file", dest = "hoge", nargs = "+", help = "optional")
parser.add_argument("-n", metavar = "number", dest = "number", type = int, help = "number", required = True) 
parser.add_argument("-f", dest = "flag", action = "store_true", help = "flag option")
  :
  :
args = parser.parse_args()
</code>
    * ''parser'': parser オブジェクト
      * ''ArgumentParser()'': パーサーの設定
        * ''formatter_class=argparse.RawTextHelpFormatter'' を指定すると、後述の ''help'' で改行が使える
      * ''.add_argument'': オプションおよび引数の登録
        * ''foo'' or ''bar'': 位置引数
          * 位置で決まる引数 (指定した順番で決まる)
          * この場合、引数は ''foo bar'' の順に与えなければならない
          * また、この引数は必須となる
        * ''--input'' or ''-i'': オプション引数
          * 順不同で指定でき、あってもなくても良い引数 (詳細に指定することで、必須にしたり引数の数を指定したりも可)
          * オプションの前に ''-'' か ''--'' を付けることで指定できる
          * ''add_argument()'' の頭で指定する
        * ''help = "..."'': ヘルプ
          * ヘルプを表示した際に表示される文字列
          * ''ArgumentParser()'' で ''formatter_class=argparse.RawTextHelpFormatter'' を指定していれば、''\n'' で改行もできる
        * ''metavar = "..."'': ヘルプで表示するための引数の対象
          * metavar が指定されない場合、ヘルプには ''--input INPUT, -i INPUT'' とロングオプション (なければ、ショートオプション) を大文字にした文字列がオプションの後に続いてユーザを混乱させる (オプションと引数が一致していれば問題ない) 
          * metavar を指定することによりオプションとは異なる文字列を表示することができる。この場合は、''--input file, -i file'' となり、ファイルを指定すれば良いことがユーザに伝わる
        * ''dest = "..."'': 引数を受け取るための変数名
          * 引数は通常、''args.変数名'' で受け取ることができる
          * この ''変数名'' は dest で指定した変数名 > ロングオプション名 > ショートオプション名の優先順位で決まる
          * ロングオプション、ショートオプション名を変数にしたくない場合に、dest を使って指定する
          * 今回の例では、''args.hoge'' や ''args.number'' で受け取ることができる
        * ''nargs = "..."'': 引数の数を指定
          * 整数を指定した場合、指定した引数の数に満たない時はエラーになる (何も指定しない場合は ''nargs = 1'' になっている)
          * ''?'' を指定した場合、1 つの引数か、ない場合は ''default = "..."'' で指定した引数になる (default を指定しない場合は、''None'' が渡される)
          * ''*'' を指定した場合、0 以上の引数を必要とする (0 以上なのでなくても良い)
          * ''+'' を指定した場合、最低 1 以上の引数を必要とする
          * 整数や ''*''、''+'' を指定した場合は、リストで引数を受け取ることができる
          * 今回の例では、ファイルを 1 つ以上指定しなければならない (-i file1 file2 file3 ...)
        * ''type = ...'': 引数の型を指定
          * 指定することにより、受け取った引数を型変換する
          * 今回の場合は、整数型の引数を変数で受け取ることができる
        * ''required = True'': 必須オプション (True でオプションが必須になる)
        * ''action = "store_true"'': オプションの有無で値を決定する
          * オプションでフラグにするような場合 (引数が不要の場合) に使う
          * ''store_true'' は、オプションが指定された時に変数に ''True'' を代入する
          * ''store_false'' は、指定された時に変数に ''False'' を代入する
    * ''args'': 引数オブジェクト

==== ヘルプ表示の時に引数をグループでまとめる場合 ====
  * ヘルプ表示を分かりやすくするため、引数をグループでまとめる場合は、''add_argument_group()'' を用いる。\\ <code python>
parser = argparse.ArgumentParser(description = "test", formatter_class=argparse.RawTextHelpFormatter)

group_a = parser.add_argument_group("Group A")
group_a.add_argument("foo", help = "help message for foo")
group_a.add_argument("bar", help = "help message for bar")

group_b = parser.add_argument_group("Group B")
group_b.add_argument("hoge", help = "help message for hoge")

args = parser.parse_args()
</code>
    * ''parser'' にグループ (''Group A'' と ''Group B'') を追加した変数 (''group_a'' と ''group_b'') を作成し、それぞれに引数を追加していく。
  * 上記のヘルプを表示した場合、下のように表示される。\\ <code>
$ test.py --help
usage: test.py [-h] foo bar hoge

test

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

Group A:
  foo         help message for foo
  bar         help message for bar

Group B:
  hoge        help message for hoge
</code>

==== いずれかのオプションのみ有効にする場合 ====
  * 引数 A を指定した時は引数 B を無効、あるいはその逆といった引数を指定したい場合は、''add_mutually_exclusive_group()'' を使う。\\ <code python>
parser = argparse.ArgumentParser(description = "test", formatter_class=argparse.RawTextHelpFormatter)

group = parser.add_mutually_exclusive_group()
group.add_argument("--foo", help = "help message for foo")
group.add_argument("--bar", help = "help message for bar")

args = parser.parse_args()
</code>
    * 引数をグループでまとめる ''add_argument_group()'' と同様に、グループ ''group'' を作成し、その中に同時に指定できない引数を加える (加える引数は 2 つ以上でも OK)。
    * 追加する引数はオプション引数であることが必須。
    * いずれかの引数を必須項目にしたい場合は、引数にそれぞれ ''required'' を指定するのではなく、''add_mutually_exclusive_group(required = True)'' にする (引数に ''required'' を付けるとエラーになる)。

===== Tips =====
==== 特定のオプション引数が使用された場合に別のオプションを必須にする ====
  * オプション A が指定された場合に、オプション B を必須にする場合
    * A と B は必須ではない (A、B なし → True)
    * A が指定された時に B が必須になる (A、B → True / A → False)
    * B は単独で利用できる (B → True)
  * コード\\ <code python>
import argparse
import sys
parser = argparse.ArgumentParser(description = "...")
parser.add_argument("-a", required = False, help = "A requires B")
parser.add_argument("-b", required = "-a" in sys.argv, help = "B")
parser.add_argument("-c", help = "C")
args = parser.parse_args()
</code>
    * やっていることは、引数を sys.argv で取ってきて、その引数の中にトリガーとなる ''-a'' が含まれているかを調べて、''True'' か ''False'' を動的に ''required'' に与えているだけ。
  * 参考サイト: [[https://stackoverflow.com/questions/25626109/python-argparse-conditionally-required-arguments | Python Argparse conditionally required arguments - Stack Overflow]]

===== 参考サイト =====
  * [[http://docs.python.jp/2/library/argparse.html | 15.4. argparse — コマンドラインオプション、引数、サブコマンドのパーサー — Python 2.7.x ドキュメント]]


{{tag>プログラミング}}