コツコツさんのブログ | OS | Windows 10 64bit |
| Python | 3.10.2 |
Pythonの標準ライブラリargparseは、スクリプト実行時のオプションをパース(解析)してくれる便利なライブラリです。
スクリプトによっては、実行時にオプションを与えて動作を変化させたいことが多くあります。そんな時に簡単にオプションを解析してくれるのがargparseです。
本記事では、argparseの基本的な使い方をご紹介します。また、位置引数に関しては説明せず、オプションのみを説明します。
argparseを使う基本的な流れは、以下になります。
- argparseのインポート
- ArgumentParser初期化、パーサを作成
- add_argumentでオプションを追加
- parse_argsでオプションをパース
順番にみていきましょう。
まずは、argparseをインポートします。
import argparseArgumentParserは、引数をパースするパーサを作成します。ArgumentParserの初期化を行いパーサを作成します。
parser = argparse.ArgumentParser()ArgumentParserには以下の引数を渡せます。
| 引数 | 説明 | デフォルト |
|---|---|---|
| prog | プログラムのファイル名を指定します。 ヘルプメッセージに表示に使用されます。 | None後に os.path.basename(sys.argv[0]) = 実行ファイル名 |
| usage | ヘルプメッセージの使用方法で使用されます。 usage引数で変更することができます。 | None後にパーサに設定されたオプションから自動生成 |
| description | プログラムの説明文を指定します。 ヘルプメッセージで表示されます。 | None |
| epilog | プログラムの追加の説明を指定します。 プログラムのオプションの説明の後に表示されます。 | None |
| parents | 親となるパーサを指定します。 共通のオプションを共有したい場合に指定します。 渡すパーサは初期化しておく必要があります。 | [] |
| formatter_class | HelpFormatterクラスを指定します。 表示するヘルプメッセージのフォーマットを変更できます。 指定できるHelpFormatterクラスは以下となります。 HelpFormatter RawDescriptionHelpFormatter RawTextHelpFormatter ArgumentDefaultsHelpFormatter MetavarTypeHelpFormatter | HelpFormatterクラス |
| prefix_chars | オプションの接頭辞を指定します。 | '-' |
| fromfile_prefix_chars | ファイルオプションの接頭辞を指定します。 列挙したオプションをファイルで読み込む場合に、 指定した接頭辞のオプションはファイルとして扱われます。 | None |
| argument_default | パーサ全体に共有されるデフォルト値を指定します。 | None |
| allow_abbrev | 短縮されたオプションを認識させるかどうかを指定します。 | True長いオプションでも短縮されたオプションを認識します。 |
| conflict_handler | オプションの衝突に対する動作を指定します。'error'または'resolve'を指定します。'relolve'は衝突したオプションを削除し上書きします。 | 'error'デフォルトはエラーを送出します。 |
| add_help | -hまたは--helpオプションを含めるかどうかを指定します。 | True |
| exit_on_error | 不正な引数の場合、エラーで終了するかどうかを指定します。 | True |
パーサに対してadd_argumentメソッドを使用することで、オプションを追加できます。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt')この場合、オプションとして-o/--optが追加され、実行時に渡された場合はオプションとして認識されます。
add_argumentメソッドではオプション名以外にも以下の引数を指定できます。
| 引数 | 説明 | デフォルト |
|---|---|---|
| action | 渡されたオプション引数に対しての動作を指定します。 | 'store' |
| nargs | オプションに渡す引数の数を指定します。 | 一つのオプション引数を一つの値で生成 |
| const | actionやnargsの一部で使用される引数です。 | None |
| default | デフォルト値を指定します。 オプションを省略した場合、指定したデフォルト値が格納されます。 | None |
| type | オプション引数の型や変換関数を指定します。 | str |
| choices | オプション引数の選択肢を指定します。 渡すオプション引数は指定された選択肢からのみ選択します。 | None |
| required | 必須オプションかどうか指定します。 | False |
| help | オプションの説明を指定します。 | None |
| metavar | ヘルプメッセージに表示するオプション引数を指定します。 | destで指定された値の大文字 |
| dest | パース結果のオブジェクトの属性名を指定します。 | --を除いた先頭のオプション文字列。なければ -を除いた先頭のオプション文字列 |
argparseで重要な部分なのでadd_argumentメソッドの各引数について、もう少し詳しく見ていきます。
action
actionにはオプション引数に対しての動作を文字列で引数で与えます。
'store'
渡されたオプション引数の値をパース結果のオブジェクトに格納します。デフォルトのactionです。'store_const'
add_argumentの引数constに渡された値を、オプション引数に格納します。
以下のコードは、actionに'store_const'を設定し、constに18という値を設定したパーサを作成する例です。
このようにすると、実行時にオプション-oまたは–optを渡されたときに、パース結果のオブジェクトに18が格納されます。
なお、後述するparse_argsメソッドは渡されたオプションを解析するメソッドです。このメソッドの引数にオプション文字列を渡すことで、解析させることもできます。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', action='store_const', const=18) # constに値を設定
args = parser.parse_args(['-o']) # オプションを渡す
# Namespace(opt=18)'store_true', 'store_false''store_true'を設定したオプションが渡された場合はTrueを、'store_false'を設定したオプションが渡された場合はFalseを格納します。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', action='store_true')
args = parser.parse_args(['-o'])
# Namespace(opt=True)'append'
複数回オプションを渡した際にリストに格納するアクションです。
以下のコードは、オプションoptとオプション引数arg_a(arg_b)を2回渡した場合、パース結果オブジェクトoptにリストで、arg_aとarg_bが格納される例です。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', action='append')
args = parser.parse_args('-o arg_a -o arg_b'.split()) # オプションとオプション引数を渡す
# Namespace(opt=['arg_a', 'arg_b'])'append_const'
複数回オプションを渡した際にconstに与えられた値をリストに格納するアクションです。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', action='append_const', const=18)
args = parser.parse_args('-o -o'.split())
# Namespace(opt=[18, 18])別々のオプションの定数を一つのリストに格納したいときに使えます。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o1', '--opt1', dest='opts', action='append_const', const=18)
parser.add_argument('-o2', '--opt2', dest='opts', action='append_const', const=19)
args = parser.parse_args('-o1 -o2'.split())
# Namespace(opts=[18, 19])'count'
オプションの渡された数を格納するアクションです。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', action='count')
args = parser.parse_args('-o -o -o'.split())
# Namespace(opt=3)指定されない場合は、Noneが格納されますのでご注意ください。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', action='count')
args = parser.parse_args()
# Namespace(opt=None)'help'
オプションが渡されるとヘルプメッセージを表示するアクションです。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', action='help')
args = parser.parse_args(['-o'])
# usage: prog.py [-h] [-o]
#
# options:
# -h, --help show this help message and exit
# -o, --opt'version'
オプションが渡されるとversion引数に渡されたバージョンを表示します。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', action='version', version='version 1.0.0')
args = parser.parse_args(['-o'])
# version 1.0.0'extend'
複数回オプションを渡した際にリストを拡張するアクションです。
以下のコードは、複数回オプションのオプション引数を格納したリストを結果オブジェクトoptのリストに拡張する例です。
なお、後述するnargsはオプション引数をリストに集約するadd_argumentの引数です。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', action='extend', nargs='+')
args = parser.parse_args('-o 18 19 -o 20 21'.split())
# Namespace(opt=['18', '19', '20', '21'])nargs
nargsは、オプション引数をいくつ渡すかを指定できます。デフォルトはオプションとオプション引数は1対1です。
N
整数Nを指定された分だけ認識します。
以下のコードはNに2を指定した場合の例です。オプション引数を2つ以外で渡した場合は認識されません。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', nargs=2)
args = parser.parse_args('-o 18 19'.split())
# Namespace(opt=['18', '19'])'?'
0または一つのオプション引数を認識します。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', nargs='?')
args = parser.parse_args('-o 18'.split())
# Namespace(opt='18')上記例でオプション引数を指定しなかった場合はNoneが挿入されます。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', nargs='?')
args = parser.parse_args('-o'.split())
# Namespace(opt=None)'*'
0以上のオプション引数を認識します。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', nargs='*')
args = parser.parse_args('-o 18'.split())
# Namespace(opt=['18'])オプション引数を指定しない場合は空の配列だけ作成されます。
'+'
1つ以上のオプション引数を認識します。一つも指定しない場合はエラーとなります。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', nargs='+')
args = parser.parse_args('-o 18'.split())
# Namespace(opt=['18'])const
constは定数の値を指定します。actionの'store_const'や'append_const'などで使用されます。
default
オプションを指定しない場合、パース結果オブジェクトにデフォルトで挿入される値を指定します。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', default=18)
args = parser.parse_args()
# Namespace(opt=18)type
オプションの型や変換関数を指定します。デフォルトは文字列で認識されます。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', type=float)
args = parser.parse_args('-o 18.5'.split())
print(args, type(args.opt))
# Namespace(opt=18.5) <class 'float'>それ以外にも、例えば渡された文字列を全て小文字にしたいといった場合は以下のようにできます。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', type=str.lower)
args = parser.parse_args('-o Mr.Kotukotu'.split())
# Namespace(opt='mr.kotukotu')choices
オプション引数を選択肢の中から選択させたい場合にリストや任意のコンテナで指定します。選択肢の中にないオプション引数を渡した場合はエラーとなります。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', type=int, choices=[18, 19, 20])
args = parser.parse_args('-o 18'.split())
# Namespace(opt=18)required
必須オプションの場合Trueを指定します。必須オプションが渡されていない場合はエラーとなります。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', required=True)
args = parser.parse_args()
# usage: test.py [-h] -o OPT
# test.py: error: the following arguments are required: -o/--optただし、
注釈: ユーザーは、通常 フラグ の指定は 任意 であると認識しているため、必須にするのは一般的には悪いやり方で、できる限り避けるべきです。
Pythonドキュメント requiredより引用
とある通り、必須オプションとするのはできる限り避けたほうがよさそうです。
help
オプションの簡単な説明を指定します。ヘルプメッセージ表示の際に、指定された説明文を表示します。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', help='オプションです。')
args = parser.parse_args('-h'.split())
# usage: test.py [-h] [-o OPT]
#
# options:
# -h, --help show this help message and exit
# -o OPT, --opt OPT オプションです。また、SUPPRESSを指定することで、ヘルプメッセージにオプションの説明を加えないこともできます。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt', help=argparse.SUPPRESS)
args = parser.parse_args()
# usage: test.py [-h] [-o OPT]
#
# options:
# -h, --help show this help message and exitmetavar
ヘルプメッセージ表示時のオブジェクトの名前を指定します。デフォルトは後述するdestの値の大文字を利用します。
ただし、metavarの指定で変更されるのはヘルプメッセージ上の名前だけということに注意してください。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o1', '--opt1')
parser.add_argument('-o2', '--opt2', metavar='Opt2')
args = parser.parse_args('-h'.split())
# usage: test.py [-h] [-o1 OPT1] [-o2 Opt2]
#
# options:
# -h, --help show this help message and exit
# -o1 OPT1, --opt1 OPT1
# -o2 Opt2, --opt2 Opt2dest
パース結果のオブジェクトの属性名を指定します。デフォルトは、長いオプション--が指定されていれば先頭の--を除いた部分が属性名に、短いオプション-のみ指定されていれば先頭の-を除いた部分が属性名になります。
先頭以外の-は全て_に変換されます。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o1', '--opt-1')
parser.add_argument('-o2', '--opt-2', dest='OPTION2')
args = parser.parse_args('-o1 18 -o2 19'.split())
# Namespace(opt_1='18', OPTION2='19')parse_argsメソッドは、渡されたオプションとオプション引数をパースし、結果をNamespaceオブジェクトに変換します。
Namespaceオブジェクトは辞書に似たオブジェクトでNamespace.属性名で結果を取り出すことができます。
parse_argsメソッドの引数にはargsとnamespaceがあります。argsはパースしたい文字列のリストを渡すことができ、namespaceには任意のNamespaceオブジェクトを渡すことができます。
ここでは端末でスクリプトファイル実行時のparse_argsメソッドの使い方の例です。
test.pyという名前のスクリプトファイルを以下のように作成します。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--opt')
args = parser.parse_args()
print(f'{args.opt=}')最後の行のf'~'はf文字列と呼ばれる標準機能で、文字列中に変数を展開してくれます。詳しくは以下の記事を参照してください。
【便利な表示機能】f文字列の紹介
まずは、オプションを何も指定しないでtest.pyを実行します。
オプションを何も渡していないのでパース結果の属性optにはdefaultのデフォルト値Noneが挿入されています。
> python test.py
args.opt=None次に、オプション引数無しでオプションのみを与えてみましょう。
usageとともにエラーメッセージを表示しました。
> python test.py -o
usage: test.py [-h] [-o OPT]
test.py: error: argument -o/--opt: expected one argumentでは、オプション引数有でオプションを与えてみます。
文字列で'18'という結果が属性optに挿入されました。
> python test.py -o 18
args.opt='18'最後に-hオプションを渡して、ヘルプメッセージを表示してみます。
> python test.py -h
usage: test.py [-h] [-o OPT]
options:
-h, --help show this help message and exit
-o OPT, --opt OPT本記事ではPyhonの標準ライブラリargparseを紹介しました。
作成したPythonファイルの実行オプションをパースしてくれる便利なライブラリです。
個人的に名前がargparse、ArgumentParser、parse_argsなど似ていて少しややこしいのでよく忘れてしまいます。
