[python]コマンドライン引数を取得する方法（argparse – 引数設定編）

はじめに

Pythonスクリプトにコマンドライン引数を使用する方法です。
より本格的な標準ライブラリに含まれる argparse を使用します。

argparse は様々なオプションがありますが、その中でも引数設定についての機能を紹介します。
基本的な紹介や、ヘルプ表示の機能紹介についてはこちらをご参照ください。

[python]コマンドライン引数を取得する方法（argparse - 基本編）

コマンドライン引数を取得する方法（argparse - 基本編）はじめにPythonスクリプトにコマンドライン引数を使用する方法です。手軽に使用するには、標準ライブラリに含まれる sys モジュールの argv を使用しますが、今回はより本...

[python]コマンドライン引数を取得する方法（argparse - ヘルプ表示編）

コマンドライン引数を取得する方法（argparse - ヘルプ表示編）はじめにPythonスクリプトにコマンドライン引数を使用する方法です。より本格的な標準ライブラリに含まれる argparse を使用します。argparse は様々なオプ...

開発環境

OS : Windows 11 Pro
Python：3.13.2
使用ライブラリ：なし

説明

引数カスタマイズ

引数の数を増やすには、add_argument() メソッドを追加していきます。
add_argument() メソッドに追加する内容によって、引数をカスタマイズできます。

位置（必須）引数とオプション引数

位置（必須）引数なのかオプション引数なのかは、接頭辞（prefix_chars）[-]があるかないかで判断します。

parser.add_argument('-f', '--foo')      # オプション引数
parser.add_argument('bar')              # 位置（必須）引数

位置（必須）引数を指定しているのに、その引数がない場合はエラーとなります。
オプション引数はなくてもエラーにならず、文字列「None」が入ります。

import argparse
parser = argparse.ArgumentParser(prog='PROG')
parser.add_argument('-f', '--foo')
parser.add_argument('bar')
args = parser.parse_args()
print(f'foo={args.foo}, bar={args.bar}')

> python .\argparse_name_or_flag.py BAR
foo=None, bar=BAR
> python .\argparse_name_or_flag.py BAR --foo FOO
foo=FOO, bar=BAR
> python .\argparse_name_or_flag.py --foo FOO
usage: PROG [-h] [-f FOO] bar
PROG: error: the following arguments are required: bar

アクションカスタマイズ(action)

コマンドライン引数にアクションを割り当てます。このアクションは、割り当てられたコマンドライン引数に関してどんな処理でもできますが、ほとんどのアクションは単に parse_args() が返すオブジェクトに属性を追加するだけです。

store_const

const キーワード引数で指定された値を格納します。
値を指定しようとするとエラーになります。

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', action='store_const', const=42)
args = parser.parse_args()
print(f'foo={args.foo}')

> python .\argparse_action_store_const.py --foo
foo=42

store_true/store_false

store_true 指定時、引数指定があれば True, なければ False が入ります。
store_false 指定時、引数指定があれば False, なければ True が入ります。
値を指定しようとするとエラーになります。

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', action='store_true')
parser.add_argument('--bar', action='store_false')
parser.add_argument('--baz', action='store_false')
args = parser.parse_args()
print(f'foo={args.foo}')
print(f'bar={args.bar}')
print(f'baz={args.baz}')

> python .\argparse_action_store_true_false.py --foo --bar
foo=True
bar=False
baz=True

append

リストを格納し、それぞれの引数として与えられた値をリストに追加します。複数回指定可能なオプション引数に対して有用です。

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', action='append')
args = parser.parse_args()
print(f'foo={args.foo}')

> python .\argparse_action_apend.py --foo 1 --foo 2
foo=['1', '2']

append_const

リストを格納し、それぞれの引数として与えられた値をリストに追加します。複数回指定可能なオプション引数に対して有用です。

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--str', dest='types', action='append_const', const='str')
parser.add_argument('--int', dest='types', action='append_const', const=0)
args = parser.parse_args()
print(f'types={args.types}')

> python .\argparse_action_apend_const.py --str --int --str
types=['str', 0, 'str']

extend

リストを保存し、複数値の引数リストの各項目をそれに追加します。 ‘extend‘ アクションは通常、nargs キーワード引数値 ‘+’ または ‘*’ で使用されます。 nargs が None (デフォルト) または ‘?’ の場合、引数文字列の各文字がリストに追加されることに注意してください。

import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--foo", action="extend", nargs="+", type=str)
args = parser.parse_args()
print(f'foo={args.foo}')

> python .\argparse_action_extend.py --foo f1 --foo f2 f3 f4
foo=['f1', 'f2', 'f3', 'f4']

count

キーワード引数の数を数えます。

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--verbose', '-v', action='count', default=0)
args = parser.parse_args()
print(f'verbose={args.verbose}')

> python .\argparse_action_count.py -vvv
verbose=3

help

help を表示して終了します。

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--showhelp', '-s', action='help', default=0)
args = parser.parse_args()

> python .\argparse_action_help.py -s
usage: argparse_action_help.py [-h] [--showhelp]

options:
  -h, --help      show this help message and exit
  --showhelp, -s

version

指定されたときはバージョン情報を表示して終了します。

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

> python .\argparse_action_version.py --version
PROG 2.0

引数の数を指定(nargs)

`nargs`	説明
`N` (整数)	`N` 個の引数
‘?’	0 or 1 個の引数
‘*’	0 以上の引数
‘+’	1 以上の引数

N (整数)

引数の数を指定します。
指定した引数の数が入力されなかった場合は、エラーとなります。

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', nargs=2)
parser.add_argument('bar', nargs=1)
args = parser.parse_args()
print(f'bar={args.bar} foo={args.foo}')

> python .\argparse_nargs_N.py  c --foo a b
bar=['c'] foo=['a', 'b']

‘?’

引数の数を 0個または 1個に指定します。
指定した引数の数が入力されなかった場合は、エラーとなります。

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', nargs='?', const='c', default='d')
parser.add_argument('bar', nargs='?', default='d')
args = parser.parse_args()
print(f'bar={args.bar} foo={args.foo}')

> python .\argparse_nargs_questionmark.py XX --foo YY
bar=XX foo=YY
> python .\argparse_nargs_questionmark.py XX --foo
bar=XX foo=c
> python .\argparse_nargs_questionmark.py XX
bar=XX foo=d

‘*’

引数の数を 0以上に指定します。
引数を指定しなくてもエラーとなりません。

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', nargs='*')
parser.add_argument('--bar', nargs='*')
parser.add_argument('baz', nargs='*')
args = parser.parse_args()

> python .\argparse_nargs_asterisk.py a b --foo x y --bar 1 2
baz=['a', 'b'] foo=['x', 'y'] bar=['1', '2']

‘+’

引数の数を 1以上に指定します。
0個の場合は、エラーとなります。

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('foo', nargs='+')
args = parser.parse_args()
print(f'foo={args.foo}')

> python .\argparse_nargs_plus.py a b
foo=['a', 'b']

デフォルト値(default)

コマンドライン引数が省略された場合に設定するデフォルト値を指定することができます。
引数は指定されているが、値がない場合はエラーとなります。

import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', default=42)
args = parser.parse_args()
print(f'foo={args.foo}')

> python .\argparse_default.py --foo 2
foo=2
> python .\argparse_default.py
foo=42
> python .\argparse_default.py --foo
usage: argparse_default.py [-h] [--foo FOO]
argparse_default.py: error: argument --foo: expected one argument

データ型指定(type)

デフォルトでは、パーサーはコマンドライン引数を単なる文字列として読み込みます。
type で型指定することにより、必要な型チェックと型変換を行うことができます。
bool をここで指定することは推奨されていません。bool を使用したい場合は、アクションカスタマイズ(action)を使用しましょう。

import argparse
import pathlib

parser = argparse.ArgumentParser(formatter_class=argparse.MetavarTypeHelpFormatter)
parser.add_argument('count', type=int)
parser.add_argument('distance', type=float)
parser.add_argument('street', type=ascii)
parser.add_argument('code_point', type=ord)
parser.add_argument('datapath', type=pathlib.Path)
args = parser.parse_args()

> python .\argparse_type.py --help
usage: argparse_type.py [-h] int float ascii ord Path

positional arguments:
  int
  float
  ascii
  ord
  Path

options:
  -h, --help  show this help message and exit

選択肢(choices)

引数に選択肢を設けることができます。
コマンドラインを解析するとき、引数の値がチェックされ、その値が選択肢の中に含まれていない場合はエラーとなります。

import argparse
parser = argparse.ArgumentParser(prog='game.py')
parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
args = parser.parse_args()
print(f'move={args.move}')

> python .\argparse_choices.py rock
move=rock
> python .\argparse_choices.py fire
usage: game.py [-h] {rock,paper,scissors}
game.py: error: argument move: invalid choice: 'fire' (choose from rock, paper, scissors)