argparseを使用してPythonでコマンドラインプログラムを作成する方法

投稿日: 2022-04-20 2022-10-17
タグ: python

序章

Pythonのargparse標準ライブラリモジュールは、Pythonコードを介してコマンドラインインターフェイス（CLI）を作成するのに役立つツールです。あなたはすでにCLIに精通しているかもしれません：次のようなプログラム git, ls, grep、と find すべて、特定の入力とオプションを使用して基になるプログラムを呼び出すことができるコマンドラインインターフェイスを公開しています。 argparse 呼び出す方法と同様のコマンドライン引数を使用して、独自のカスタムPythonコードを呼び出すことができます git, ls, grep、また find コマンドラインを使用します。他の開発者がコマンドラインからコードを実行できるようにする場合は、これが役立つことがあります。

このチュートリアルでは、Pythonで公開されているユーティリティのいくつかを使用します argparse 標準ライブラリモジュール。基になるプログラムの動作を制御するために、位置引数とオプションの引数を受け入れるコマンドラインインターフェイスを記述します。また、CLIを使用している他の開発者に表示できるヘルプテキストを提供することにより、CLIを自己文書化します。

このチュートリアルでは、架空の水族館で魚を追跡するプログラムのコマンドラインインターフェイスを作成します。

前提条件

このチュートリアルを最大限に活用するには、次のものを用意することをお勧めします。

Python3でのプログラミングにある程度精通している。背景知識については、 Python3チュートリアルシリーズでコーディングする方法を確認できます。

位置引数を受け入れるコマンドラインプログラムの作成

あなたは使用することができます argparse 位置引数を受け入れるコマンドラインインターフェイスを作成するモジュール。位置引数（次のセクションで説明するオプションの引数とは対照的に）は、通常、プログラムへの必要な入力を指定するために使用されます。

位置によって識別される水族館の水槽で魚を印刷するCLIの例を考えてみましょう tank 口論。

CLIを作成するには、テキストエディタでファイルを開きます。

nano aquarium.py

次に、次のPythonコードを追加します。

aquarium.py

import argparse

tank_to_fish = {
    "tank_a": "shark, tuna, herring",
    "tank_b": "cod, flounder",
}

parser = argparse.ArgumentParser(description="List fish in aquarium.")
parser.add_argument("tank", type=str)
args = parser.parse_args()

fish = tank_to_fish.get(args.tank, "")
print(fish)

あなたは魚を印刷することができます tank_a 実行することによって：

python3 aquarium.py tank_a

そのコマンドを実行すると、次のような出力が表示されます。

Outputshark, tuna, herring

同様に、あなたが走った場合 aquarium.py 魚を印刷するには tank_b と：

python3 aquarium.py tank_b

次のような出力が表示されます。

Outputcod, flounder

コードを分解してみましょう aquarium.py.

まず、インポートします argparse プログラムで使用できるようにするモジュール。次に、辞書のデータ構造を作成します tank_to_fish 戦車名をマップします（ tank_a と tank_b）それらのタンクに保持されている魚の説明を文字列化する。

のインスタンスをインスタンス化します ArgumentParser クラスとそれをにバインドします parser 変数。あなたは考えることができます parser コマンドラインインターフェイスを構成するための主要なエントリポイントとして。 The description に提供される文字列 parser これは、後で学習するように、によって公開されるCLIの自動生成されたヘルプテキストで使用されます。 aquarium.py.

呼び出し add_argument on parserを使用すると、コマンドラインインターフェイスで受け入れられる引数を追加できます。この場合、次の名前の単一の引数を追加します tank それは文字列型です。呼び出し parser.parse_args() 指示する parser に渡されたコマンドライン入力を処理および検証します aquarium.py （たとえば、 tank_a). アクセスする args によって返される parser.parse_args() 渡された値を取得できます tank 引数、およびそれを使用して print その水槽で魚を出します。

この時点で、コマンドラインインターフェイスを作成し、プログラムを実行して魚を印刷しました。次に、CLIが他の開発者にどのように機能するかを説明する必要があります。 argparse CLIを文書化するためのヘルプテキストを強力にサポートしています。次に、ヘルプテキストについて詳しく説明します。

ヘルプテキストの表示

The aquarium.py 前のセクションで書いたファイルは、実際には特定の水槽で魚を印刷するだけではありません。使用しているので argparse、によって公開されるコマンドラインインターフェイス aquarium.py プログラムの詳細を知るためにユーザーが参照できるヘルプメッセージと使用法メッセージが自動的に含まれます。

たとえば、使用法のメッセージを考えてみましょう aquarium.py コマンドラインで無効な引数を指定すると出力されます。呼び出してみてください aquarium.py 次のコマンドを実行して、コマンドラインで間違った引数を使用します。

python3 aquarium.py --not-a-valid-argument

このコマンドを実行すると、次のような出力が表示されます。

Outputusage: aquarium.py [-h] tank
aquarium.py: error: the following arguments are required: tank

コマンドラインに出力された出力は、実行しようとしてエラーが発生したことを示しています aquarium.py. 出力は、ユーザーが呼び出す必要があることを示しています aquarium.py とともに tank 口論。あなたが気付くかもしれない他の何かは -h 中間 [] 文字。これは、 -h は、同様に提供できるオプションの引数です。

今、あなたはあなたが電話したときに何が起こるかを知るでしょう aquarium.py とともに -h オプション。呼び出してみてください aquarium.py とともに -h 次のコマンドを実行して、コマンドラインで引数を実行します。

python3 aquarium.py -h

このコマンドを実行すると、次のような出力が表示されます。

Outputusage: aquarium.py [-h] tank

List fish in aquarium.

positional arguments:
  tank

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

ご想像のとおり、 -h オプションは「ヘルプ」の略です。ランニング python3 aquarium.py -h （または、同等に、より長いバリアント python3 aquarium.py --help）ヘルプテキストを印刷します。ヘルプテキストは、事実上、無効な引数を指定したときに前の例で出力された使用法テキストの長いバージョンです。特に、ヘルプテキストにはカスタムも含まれています description の文字列 List fish in an aquarium あなたがインスタンス化したこと ArgumentParser このチュートリアルの前半で。

デフォルトでは、を使用してCLIを作成する場合 argparse 他の開発者向けにCLIを文書化するために使用できるヘルプと使用法のテキストが自動的に取得されます。

これまで、必要な位置引数を受け入れるCLIを作成しました。次のセクションでは、インターフェイスにオプションの引数を追加して、その機能を拡張します。

オプションの引数の追加

コマンドラインインターフェイスにオプションの引数を含めると便利な場合があります。これらのオプションには通常、たとえば2つのダッシュ文字がプレフィックスとして付けられます。 --some-option. 書き直そう aquarium.py 次の調整されたコンテンツで --upper-case CLIのオプション：

aquarium.py

import argparse

tank_to_fish = {
    "tank_a": "shark, tuna, herring",
    "tank_b": "cod, flounder",
}

parser = argparse.ArgumentParser(description="List fish in aquarium.")
parser.add_argument("tank", type=str)
parser.add_argument("--upper-case", default=False, action="store_true")
args = parser.parse_args()

fish = tank_to_fish.get(args.tank, "")

if args.upper_case:
    fish = fish.upper()

print(fish)

呼び出してみてください aquarium.py 新しいと --upper-case 以下を実行することによる引数：

python3 aquarium.py --upper-case tank_a

このコマンドを実行すると、次のような出力が表示されます。

OutputSHARK, TUNA, HERRING

の魚 tank_a 大文字で出力されるようになりました。あなたは新しいを追加することによってこれを達成しました --upper-case 電話をかけたときのオプション parser.add_argument("--upper-case", default=False, action="store_true"). The "--upper-case" stringは、追加する引数の名前です。

の場合 --upper-case CLIのユーザーがオプションを提供していません。 default=False その値がに設定されていることを確認します False デフォルトでは。 action="store_true" ときに何が起こるかを制御します --upper-case オプションはCLIユーザーによって提供されます。アクションパラメータでサポートされているさまざまな可能な文字列がいくつかありますが、 "store_true" 値を格納します True コマンドラインで指定されている場合は、引数に追加します。

引数はダッシュで区切られた2つの単語ですが、upper-case), argparse 次のようにコードで利用できるようにします args.upper_case （アンダースコア区切り文字付き）呼び出した後 parser.parse_args(). 一般に、 argparse は、提供された引数のダッシュをアンダースコアに変換します。これにより、呼び出し後に参照できる有効なPython識別子が得られます。 parse_args().

従来通り、 argparse 自動的に作成します --help オプションとコマンドラインインターフェイスを文書化します（ --upper-case 追加したオプション）。

呼び出してみてください aquarium.py とともに --help 更新されたヘルプテキストを受信するためのオプション：

python3 aquarium.py --help

出力は次のようになります。

Outputusage: aquarium.py [-h] [--upper-case] tank

List fish in aquarium.

positional arguments:
  tank

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

argparse 位置を自動的に記録 tank 引数、オプション --upper-case オプション、および組み込み --help オプションも。

このヘルプテキストは便利ですが、ユーザーがプログラムを呼び出す方法をよりよく理解できるように、追加情報を使用して改善することができます。次のセクションでは、ヘルプテキストを拡張する方法について説明します。

追加のヘルプテキストをユーザーに公開する

開発者は、コマンドラインインターフェイスによって提供されるヘルプテキストを使用して、プログラムの機能とその使用方法を理解します。修正しましょう aquarium.py 繰り返しますが、より良いヘルプテキストが含まれています。引数レベルの情報を指定するには、 help の文字列 add_argument 呼び出し：

aquarium.py

import argparse

tank_to_fish = {
    "tank_a": "shark, tuna, herring",
    "tank_b": "cod, flounder",
}

parser = argparse.ArgumentParser(description="List fish in aquarium.")
parser.add_argument("tank", type=str, help="Tank to print fish from.")
parser.add_argument(
    "--upper-case",
    default=False,
    action="store_true",
    help="Upper case the outputted fish.",
)
args = parser.parse_args()

fish = tank_to_fish[args.tank]

if args.upper_case:
    fish = fish.upper()

print(fish)

呼び出してみてください aquarium.py とともに --help 更新されたヘルプテキストを受信するためのオプション：

python3 aquarium.py --help

出力は次のようになります。

Outputusage: aquarium.py [-h] [--upper-case] tank

List fish in aquarium.

positional arguments:
  tank          Tank to print fish from.

optional arguments:
  -h, --help    show this help message and exit
  --upper-case  Upper case the outputted fish.

この最新の出力では、 tank 位置引数と --upper-case オプションの引数には、両方ともカスタムヘルプテキストが含まれます。文字列をに提供することにより、この追加のヘルプテキストを提供しました help 一部の add_argument. （例えば、 parser.add_argument("tank", type=str, help="Tank to print fish from.").) argparse これらの文字列を取得し、ヘルプテキスト出力でレンダリングします。

ヘルプテキストをさらに改善するには、 argparse 定義したデフォルト値を印刷します。

ヘルプテキストでのデフォルト値の表示

カスタムを使用する場合 formatter_class インスタンス化するとき ArgumentParser 実例、 argparse ヘルプテキスト出力にデフォルト値が含まれます。追加してみてください argparse.ArgumentDefaultsHelpFormatter あなたのように ArgumentParser フォーマッタークラス：

aquarium.py

import argparse

tank_to_fish = {
    "tank_a": "shark, tuna, herring",
    "tank_b": "cod, flounder",
}

parser = argparse.ArgumentParser(
    description="List fish in aquarium.",
    formatter_class=argparse.ArgumentDefaultsHelpFormatter,
)
parser.add_argument("tank", type=str, help="Tank to print fish from.")
parser.add_argument(
    "--upper-case",
    default=False,
    action="store_true",
    help="Upper case the outputted fish.",
)
args = parser.parse_args()

fish = tank_to_fish[args.tank]

if args.upper_case:
    fish = fish.upper()

print(fish)

今、呼び出してみてください aquarium.py とともに --help 更新されたヘルプテキストを確認するためのオプション：

python3 aquarium.py --help

このコマンドを実行すると、次のような出力が表示されます。

Outputusage: aquarium.py [-h] [--upper-case] tank

List fish in aquarium.

positional arguments:
  tank          Tank to print fish from.

optional arguments:
  -h, --help    show this help message and exit
  --upper-case  Upper case the outputted fish. (default: False)

この最新の出力では、 --upper-case のデフォルト値の表示で終了します --upper-case オプション（default: False). 含めることによって argparse.ArgumentDefaultsHelpFormatter あなたのformatter_classとして ArgumentParser, argparse ヘルプテキストのデフォルト値情報のレンダリングを自動的に開始しました。

結論

The argparse モジュールはPython標準ライブラリの強力な部分であり、コードのコマンドラインインターフェイスを記述できます。このチュートリアルでは、の基礎を紹介しました argparse：位置引数とオプションの引数を受け入れるコマンドラインインターフェイスを作成し、ヘルプテキストをユーザーに公開しました。

argparse 高度な入力と検証のセットを使用してコマンドラインプログラムを作成するために使用できる、さらに多くの機能をサポートします。ここから、 argparseモジュールのドキュメントを使用して、他の利用可能なクラスとユーティリティについて詳しく知ることができます。

getdocs

13036