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

提供：Dev Guides
移動先:案内、検索

著者はCOVID-19救済基金を選択し、 Write forDOnationsプログラムの一環として寄付を受け取りました。

序章

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

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

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

前提条件

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

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

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

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

位置tank引数で識別される水槽内の魚を印刷するCLIの例を考えてみましょう。

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_aやtank_bなど）をそれらのタンクに保持されている魚の文字列の説明にマップする辞書データ構造tank_to_fishを作成します。

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

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

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

ヘルプテキストの表示

前のセクションで書いた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を実行しようとしてエラーが発生したことを示しています。 出力は、ユーザーがtank引数を指定してaquarium.pyを呼び出す必要があることを示しています。 他に気付くかもしれないのは、[]文字の間の-hです。 これは、-hがオプションの引数であることを示しています。

これで、-hオプションを指定してaquarium.pyを呼び出すとどうなるかがわかります。 次のコマンドを実行して、コマンドラインで-h引数を指定してaquarium.pyを呼び出してみてください。 

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）を実行すると、ヘルプテキストが出力されます。 ヘルプテキストは、事実上、無効な引数を指定したときに前の例で出力された使用法テキストの長いバージョンです。 特に、ヘルプテキストには、このチュートリアルの前半でArgumentParserをインスタンス化したList fish in an aquariumのカスタムdescription文字列も含まれています。

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

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

オプションの引数の追加

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

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)

次のコマンドを実行して、新しい--upper-case引数を使用してaquarium.pyを呼び出してみてください。 

python3 aquarium.py --upper-case tank_a

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

OutputSHARK, TUNA, HERRING

tank_aの魚が大文字で出力されるようになりました。 これは、parser.add_argument("--upper-case", default=False, action="store_true")を呼び出したときに新しい--upper-caseオプションを追加することで実現しました。 "--upper-case"文字列は、追加する引数の名前です。

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

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

以前と同様に、argparseは自動的に--helpオプションを作成し、コマンドラインインターフェイス（追加した--upper-caseオプションを含む）を文書化します。

更新されたヘルプテキストを受け取るには、--helpオプションを指定してaquarium.pyを再度呼び出してみてください。 

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をもう一度改訂して、より適切なヘルプテキストが含まれるようにします。 add_argument呼び出しでhelp文字列を指定することにより、引数レベルの情報を指定できます。

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)

更新されたヘルプテキストを受け取るには、--helpオプションを指定してaquarium.pyを再度呼び出してみてください。 

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オプション引数の両方にカスタムヘルプテキストが含まれていることに注意してください。 add_argumentのhelp部分に文字列を提供することにより、この追加のヘルプテキストを提供しました。 （たとえば、parser.add_argument("tank", type=str, help="Tank to print fish from.")。）argparseはこれらの文字列を受け取り、ヘルプテキスト出力に表示します。

argparseに定義したデフォルト値を出力させることで、ヘルプテキストをさらに改善できます。

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

ArgumentParserインスタンスをインスタンス化するときにカスタムformatter_classを使用する場合、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)

ここで、--helpオプションを指定してaquarium.pyを再度呼び出して、更新されたヘルプテキストを確認してください。 

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をArgumentParserのformatter_classとして含めることにより、argparseはヘルプテキストにデフォルト値情報のレンダリングを自動的に開始しました。

結論

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

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

「https://www.finddevguides.com/index.php?title=Argparseを使用してPythonでコマンドラインプログラムを作成する方法&oldid=104813」から取得
Powered by MediaWiki