MENU

Pythonスクリプトのコマンドライン実行とオプションの詳解

Python

Pythonは、その柔軟性と使いやすさから、幅広い用途で使用されています。その中でも、コマンドラインからスクリプトを実行する機能は、多くの場面で役立ちます。たとえば、データ処理スクリプトを引数付きで実行したり、自動化タスクの一部として動作させたりすることが可能です。さらに、コマンドライン引数を利用することで、動作を柔軟に切り替えることができ、より汎用性の高いスクリプトを作成できます。本記事では、Pythonを使ったコマンドライン引数の扱い方について、基本的な方法から高度なテクニックまでを徹底的に解説します。

ITtripTOOLS
その「面倒」、無料で解決。 ITtripがつくる、6つの道具。 無料ツール一覧へ すべて無料・追加課金なし
先頭0を守るCSV編集こわさないCSV PDFに直接書き込みかけるPDF 写真＋説明をPDFに写レポ スマホ⇄PCで共有コピペ便 · 文章・写真 みんなの日程を調整日程Fit 匿名質問・投票を集めるKOEQ
目次

コマンドライン引数の基本


Pythonスクリプトをコマンドラインから実行する際に引数を渡すと、スクリプトの動作を制御できます。その基本的な方法が、sys.argvを使用することです。

sys.argvとは


sys.argvは、Python標準ライブラリであるsysモジュールに含まれており、コマンドライン引数をリストとして提供します。このリストの最初の要素（sys.argv[0]）はスクリプトの名前、それ以降の要素が渡された引数になります。

基本的な使用例


以下のスクリプトは、渡された引数をそのまま表示する簡単な例です：

import sys

if __name__ == "__main__":
    print("Script name:", sys.argv[0])
    print("Arguments:", sys.argv[1:])

このスクリプトをpython script.py arg1 arg2のように実行すると、次のような出力が得られます：

Script name: script.py
Arguments: ['arg1', 'arg2']

引数の解析の課題


sys.argvを使えば簡単に引数を取得できますが、次のような問題があります：

  • 引数の数や型の検証が手動で必要。
  • オプション（例: --help）の解析が複雑になる。
  • 長い引数リストを処理する際のコードが煩雑になる。

これらの問題を解決するために、Pythonではargparseなどの専用モジュールが提供されています。次の項目では、argparseの基本的な使い方について解説します。

argparseモジュールの概要


Python標準ライブラリの一部であるargparseモジュールは、コマンドライン引数を簡単に解析するための強力なツールです。このモジュールを使うことで、オプションや引数を容易に定義し、スクリプトの実行時にそれらを解析できます。

argparseの基本構造


argparseを使用する際の基本的な流れは以下の通りです：

  1. ArgumentParserオブジェクトを作成
    引数を解析するためのベースとなるオブジェクトを作成します。
  2. 引数を定義
    スクリプトが受け取る引数やオプションを指定します。
  3. 引数を解析
    コマンドラインから渡された引数を解析し、それを使ってプログラムを制御します。

基本的な使用例


以下のスクリプトは、argparseを使って引数を解析する基本的な例です：

import argparse

if __name__ == "__main__":
    # ArgumentParserの作成
    parser = argparse.ArgumentParser(description="引数解析の基本例")

    # 引数の追加
    parser.add_argument("name", help="ユーザー名を指定してください")
    parser.add_argument("--age", type=int, help="年齢を指定してください")

    # 引数の解析
    args = parser.parse_args()

    # 結果の表示
    print(f"Hello, {args.name}!")
    if args.age:
        print(f"Your age is {args.age}.")

このスクリプトを次のように実行すると：

python script.py Alice --age 30


出力は以下のようになります：

Hello, Alice!  
Your age is 30.

argparseの主な利点

  • 引数の型チェック：数値や文字列などの型を自動で検証できます。
  • デフォルトのヘルプメッセージ：自動で--helpオプションが追加され、使い方を説明するメッセージを生成します。
  • 複雑な引数構成への対応：必須引数、任意引数、フラグ、サブコマンドなど、多様な引数形式に対応可能。

次項では、argparseを使用してオプション引数を設定する方法を詳しく見ていきます。

オプション引数の設定


Pythonのargparseモジュールを使えば、コマンドライン引数を柔軟に設定し、特定のオプションを扱うことができます。オプション引数とは、スクリプトの動作を制御するために任意で指定する引数で、一般的に--または-で始まる形式を取ります。

オプション引数の基本設定


オプション引数は、add_argumentメソッドの引数で--や-を付けた名前を指定することで追加できます。

以下は、オプション引数の基本的な例です：

import argparse

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="オプション引数の基本例")

    # オプション引数の追加
    parser.add_argument("--verbose", action="store_true", help="詳細情報を表示します")
    parser.add_argument("--output", type=str, help="出力ファイル名を指定します")

    args = parser.parse_args()

    if args.verbose:
        print("Verboseモードが有効です")
    if args.output:
        print(f"出力ファイル: {args.output}")

このスクリプトを次のように実行できます：

python script.py --verbose --output result.txt


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

Verboseモードが有効です  
出力ファイル: result.txt

主な設定項目


オプション引数をカスタマイズする際の主な設定項目を以下に示します：

1. 型指定


type引数を使って、受け取る値の型を指定できます。

parser.add_argument("--count", type=int, help="処理回数を指定します")

2. デフォルト値


default引数を指定することで、値が指定されなかった場合のデフォルト値を設定できます。

parser.add_argument("--level", type=int, default=1, help="処理レベルを指定します（デフォルト: 1）")

3. 必須オプション


required=Trueを指定することで、オプション引数を必須にすることができます。

parser.add_argument("--config", required=True, help="設定ファイルを指定してください")

フラグ引数の扱い


オプション引数の中には、値を取らず、指定されるだけで真偽値を切り替えるものがあります。この場合、action="store_true"を使います：

parser.add_argument("--debug", action="store_true", help="デバッグモードを有効にします")


スクリプト実行時に--debugを指定すると、args.debugがTrueになります。

まとめ


argparseを活用すれば、柔軟で使いやすいオプション引数を簡単に設定できます。次の項目では、必須引数やデフォルト値の設定についてさらに詳しく解説します。

必須引数とデフォルト値の活用


Pythonのargparseモジュールでは、コマンドライン引数に必須要件を設けたり、指定されなかった場合に使用するデフォルト値を設定したりすることができます。この機能を利用すれば、より柔軟で堅牢なスクリプトを作成できます。

必須引数の設定


デフォルトでは、オプション引数（--で始まる引数）は指定が任意です。ただし、特定のオプションを必須にしたい場合は、required=Trueを設定します。

使用例


以下の例では、--configオプションを必須にしています：

import argparse

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="必須引数の例")

    # 必須オプションの追加
    parser.add_argument("--config", required=True, help="設定ファイルを指定してください")

    args = parser.parse_args()
    print(f"設定ファイル: {args.config}")

このスクリプトを引数なしで実行すると、エラーが表示されます：

python script.py
usage: script.py --config CONFIG
script.py: error: the following arguments are required: --config


--configオプションを指定して実行すると、正常に動作します：

python script.py --config settings.json
設定ファイル: settings.json

デフォルト値の設定


任意のオプション引数に値が指定されなかった場合に備えて、default引数でデフォルト値を設定することができます。

使用例


以下の例では、--log-levelオプションにデフォルト値を指定しています：

import argparse

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="デフォルト値の例")

    # デフォルト値を持つオプション
    parser.add_argument("--log-level", default="INFO", help="ログの詳細度（デフォルト: INFO）")

    args = parser.parse_args()
    print(f"ログレベル: {args.log_level}")

このスクリプトを引数なしで実行すると、デフォルト値が使用されます：

python script.py
ログレベル: INFO


--log-levelを指定すると、その値が優先されます：

python script.py --log-level DEBUG
ログレベル: DEBUG

必須引数とデフォルト値の組み合わせ


オプション引数ではなく、必須の位置引数でもデフォルト値を指定することが可能です。ただし、通常は位置引数にはデフォルト値を設定せず、ユーザーに値を明示的に指定させることが推奨されます。

使用例

parser.add_argument("filename", help="対象のファイル名を指定してください")


この場合、filenameは必須で、スクリプト実行時に必ず指定する必要があります。

まとめ


必須引数やデフォルト値を適切に設定することで、スクリプトの柔軟性と利便性が向上します。次の項目では、argparseの重要な機能であるヘルプメッセージの自動生成について解説します。

ヘルプメッセージの自動生成


argparseモジュールは、コマンドライン引数のヘルプメッセージを自動生成する機能を備えています。これにより、スクリプトの使い方を直感的にユーザーに伝えることが可能になります。

基本的なヘルプメッセージ


ArgumentParserを作成すると、--helpまたは-hオプションが自動的に追加され、スクリプトの引数に関する説明を表示できます。

例: 自動生成されるヘルプメッセージ


以下のスクリプトを実行してみます：

import argparse

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="ヘルプメッセージの例")
    parser.add_argument("--input", help="入力ファイルを指定します")
    parser.add_argument("--output", help="出力ファイルを指定します")
    parser.add_argument("--verbose", action="store_true", help="詳細モードを有効にします")

    args = parser.parse_args()

コマンドラインで--helpオプションを使用すると、次のようなメッセージが表示されます：

python script.py --help
usage: script.py [-h] [--input INPUT] [--output OUTPUT] [--verbose]

ヘルプメッセージの例

options:
  -h, --help       このヘルプメッセージを表示して終了します
  --input INPUT    入力ファイルを指定します
  --output OUTPUT  出力ファイルを指定します
  --verbose        詳細モードを有効にします

このヘルプメッセージには、引数名やオプションの説明が含まれます。また、-hまたは--helpのいずれを使用しても同じ結果が得られます。

ヘルプメッセージのカスタマイズ


argparseでは、説明や引数の表示をカスタマイズできます。

1. スクリプトの説明を設定


ArgumentParserのdescriptionパラメータを使用して、スクリプトの概要を説明できます：

parser = argparse.ArgumentParser(description="このスクリプトはファイルを処理します")

2. 引数ごとの説明を設定


add_argumentのhelp引数で、各引数の説明を追加します：

parser.add_argument("--input", help="処理対象の入力ファイルを指定します")

3. カスタム使用例の追加


ArgumentParserのepilogパラメータを使用して、追加の使用例や説明を末尾に付加できます：

parser = argparse.ArgumentParser(
    description="ヘルプメッセージ例",
    epilog="例: python script.py --input file.txt --output result.txt"
)

実例: カスタマイズされたヘルプメッセージ

import argparse

if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description="ファイルを処理するスクリプトです",
        epilog="例: python script.py --input in.txt --output out.txt"
    )
    parser.add_argument("--input", required=True, help="入力ファイルを指定してください")
    parser.add_argument("--output", required=True, help="出力ファイルを指定してください")
    parser.add_argument("--verbose", action="store_true", help="詳細情報を表示します")

    args = parser.parse_args()

コマンドラインで--helpを実行すると、以下のようなカスタマイズされたヘルプが表示されます：

usage: script.py [-h] --input INPUT --output OUTPUT [--verbose]

ファイルを処理するスクリプトです

options:
  -h, --help       このヘルプメッセージを表示して終了します
  --input INPUT    入力ファイルを指定してください
  --output OUTPUT  出力ファイルを指定してください
  --verbose        詳細情報を表示します

例: python script.py --input in.txt --output out.txt

ヘルプメッセージの利点

  1. 直感的な操作性：ユーザーはスクリプトの使い方をすぐに理解できます。
  2. 一貫性：全ての引数の説明を統一した形式で表示できます。
  3. 保守性：コード変更に応じてヘルプメッセージが自動で更新されます。

次の項目では、複数の動作を持つスクリプトを実現する「サブコマンド」の導入方法を解説します。

サブコマンドの導入


複数の動作を持つスクリプトでは、特定の機能ごとにコマンドを分けて処理するのが一般的です。これを実現するのが、argparseのサブコマンド機能です。サブコマンドを利用することで、スクリプトを効率的に整理し、使いやすくできます。

サブコマンドの基本構造


サブコマンドを導入する場合、add_subparsersメソッドを使用します。このメソッドでサブコマンドを定義し、それぞれに引数やオプションを設定します。

例: サブコマンドの基本


以下は、addとdeleteという2つのサブコマンドを持つスクリプトの例です：

import argparse

if __name__ == "__main__":
    # メインのArgumentParserを作成
    parser = argparse.ArgumentParser(description="サブコマンドの例")

    # サブコマンドを管理するsubparsersを作成
    subparsers = parser.add_subparsers(dest="command", help="利用可能なコマンド")

    # 'add'サブコマンドを定義
    parser_add = subparsers.add_parser("add", help="項目を追加します")
    parser_add.add_argument("item", help="追加する項目の名前")

    # 'delete'サブコマンドを定義
    parser_delete = subparsers.add_parser("delete", help="項目を削除します")
    parser_delete.add_argument("item", help="削除する項目の名前")

    # 引数の解析
    args = parser.parse_args()

    # サブコマンドごとの処理
    if args.command == "add":
        print(f"項目 '{args.item}' を追加しました")
    elif args.command == "delete":
        print(f"項目 '{args.item}' を削除しました")
    else:
        parser.print_help()

このスクリプトを以下のように実行できます：

python script.py add "Task 1"

出力：

項目 'Task 1' を追加しました
python script.py delete "Task 1"

出力：

項目 'Task 1' を削除しました

サブコマンドの引数やオプション


各サブコマンドには、それぞれ独自の引数やオプションを定義できます。たとえば、addサブコマンドに説明を付けるオプションを追加し、deleteサブコマンドに確認用のフラグを追加することが可能です。

サブコマンドの拡張例

# 'add'サブコマンドに説明を追加するオプション
parser_add.add_argument("--description", help="項目の説明を指定します")

# 'delete'サブコマンドに確認用のフラグ
parser_delete.add_argument("--force", action="store_true", help="確認を省略して削除します")

このスクリプトを次のように実行すると、それぞれの引数が適用されます：

python script.py add "Task 2" --description "This is a new task"
python script.py delete "Task 2" --force

サブコマンド使用時の注意点

  1. destの設定
    サブコマンドの結果は、デフォルトで指定される引数destに格納されます（例: args.command）。
  2. サブコマンドの指定忘れ
    サブコマンドが指定されない場合にエラーを表示するため、適切にprint_help()を呼び出しましょう。
  3. 一貫した設計
    サブコマンドが増えると複雑化するため、コマンド名や引数の設計は一貫性を持たせることが重要です。

まとめ


サブコマンドを利用することで、1つのスクリプトに複数の機能を簡潔に実装できます。特に、タスク管理ツールやAPIクライアントなど、多機能なコマンドラインツールを開発する際に便利です。次項では、さらに柔軟な引数解析を可能にするclickライブラリについて解説します。

clickライブラリによるオプション解析


Python標準ライブラリのargparseは強力ですが、よりシンプルで直感的なコマンドラインツールの作成にはclickライブラリが適しています。clickは、簡潔なコードで直感的な引数解析とヘルプの自動生成を実現します。

clickの基本


clickは関数デコレーターを活用して引数やオプションを定義します。このアプローチにより、コードが読みやすくなり、機能が自然に分離されます。

clickのインストール


まずはライブラリをインストールします：

pip install click

基本的な使用例


以下は、clickを使用してコマンドライン引数を解析する簡単な例です：

import click

@click.command()
@click.option("--name", prompt="Your name", help="ユーザー名を指定します")
@click.option("--age", default=25, help="年齢を指定します (デフォルト: 25)")
def greet(name, age):
    """挨拶メッセージを表示します"""
    click.echo(f"Hello, {name}! You are {age} years old.")

if __name__ == "__main__":
    greet()

このスクリプトを以下のように実行します：

python script.py --name Alice --age 30

出力：

Hello, Alice! You are 30 years old.

--nameや--ageが指定されない場合、プロンプトが表示され、ユーザーに入力を求めます。

複数のコマンドを持つツール


clickは、サブコマンドの設定も簡単です。@click.group()を使えば、複数のコマンドを1つのスクリプトにまとめられます。

例: 複数のコマンド

import click

@click.group()
def cli():
    """複数のコマンドを管理します"""
    pass

@click.command()
@click.argument("item")
def add(item):
    """項目を追加します"""
    click.echo(f"項目 '{item}' を追加しました")

@click.command()
@click.argument("item")
def delete(item):
    """項目を削除します"""
    click.echo(f"項目 '{item}' を削除しました")

cli.add_command(add)
cli.add_command(delete)

if __name__ == "__main__":
    cli()

このスクリプトでは、次のようにコマンドを実行できます：

python script.py add "Task 1"
python script.py delete "Task 1"

出力：

項目 'Task 1' を追加しました  
項目 'Task 1' を削除しました

clickの利点

  1. 簡潔なコード：関数デコレーターにより引数やオプションの定義が直感的。
  2. 自動ヘルプ生成：--helpオプションが自動的に生成される。
  3. 入力プロンプト：promptオプションで、引数が指定されない場合にユーザーからの入力を受け取れる。
  4. 色付けや装飾：click.echo()などで、出力に色や装飾を簡単に付けられる。

カスタムエラーメッセージの例


clickはエラー処理も簡単に行えます。次のようにエラーメッセージをカスタマイズできます：

@click.command()
@click.argument("number", type=int)
def square(number):
    """指定された数値の平方を計算します"""
    if number < 0:
        raise click.BadParameter("正の数を指定してください")
    click.echo(f"{number} の平方は {number**2} です")

if __name__ == "__main__":
    square()

まとめ


clickは、シンプルなコマンドラインツールや複雑なサブコマンド構造を持つアプリケーションのどちらにも対応できる柔軟なライブラリです。次の項目では、コマンドラインツール開発におけるベストプラクティスを解説します。

コマンドラインツール開発のベストプラクティス


Pythonでコマンドラインツールを開発する際、使いやすさや拡張性を意識した設計が重要です。ここでは、効果的なコマンドラインツールを作成するためのベストプラクティスを解説します。

1. 直感的で一貫性のあるインターフェース


利用者が迷わず使えるよう、インターフェースの設計はシンプルかつ一貫性を保つことが重要です。

おすすめポイント

  • コマンド名やオプション名は、短すぎず分かりやすいものを採用する（例: --verbose）。
  • 長いオプション名には略称を設定（例: --help と -h）。
  • サブコマンドやオプションの構造を階層化し、論理的な整理を行う。

例

tool.py add "task name" --priority high
tool.py delete "task name" --force

2. 自動生成されるヘルプの活用


引数やオプションの説明を充実させることで、ヘルプメッセージが詳細になり、利用者がコマンドを理解しやすくなります。

推奨アプローチ

  • 各引数やオプションに適切なhelp文字列を追加する。
  • スクリプト全体の概要や使用例をdescriptionやepilogで補足する。

例: argparseでの設定

parser = argparse.ArgumentParser(
    description="タスク管理ツール",
    epilog="使用例: python tool.py add 'task' --priority high"
)

3. エラー処理の実装


ユーザーが不適切な引数やオプションを指定した場合、明確なエラーメッセージを返すことで、スクリプトの信頼性が向上します。

エラー処理の例

@click.command()
@click.argument("number", type=int)
def square(number):
    if number < 0:
        raise click.BadParameter("負の数はサポートされていません")
    click.echo(f"{number} の平方は {number**2} です")

4. ツールの構造をモジュール化


スクリプトが大規模になる場合、モジュールに分割し、管理を容易にします。

構造例

project/
├── cli.py        # コマンドラインインターフェース
├── commands/
│   ├── add.py    # 'add'コマンド
│   ├── delete.py # 'delete'コマンド
│   └── __init__.py
├── utils.py      # 補助関数
└── main.py       # エントリーポイント

5. ユニットテストの実装


コマンドラインツールにもテストを追加し、ツールの信頼性を向上させます。

テスト例


pytestを使用して、コマンドラインスクリプトをテストします：

from click.testing import CliRunner
from my_tool import cli

def test_add_command():
    runner = CliRunner()
    result = runner.invoke(cli, ["add", "Task 1"])
    assert result.exit_code == 0
    assert "Task 1 を追加しました" in result.output

6. クロスプラットフォーム対応


ツールがWindows、macOS、Linuxのいずれでも動作するように設計します。

考慮点

  • ファイルパスの扱いにはos.pathやpathlibを使用。
  • シェルコマンドや外部プログラムの呼び出しにはsubprocessを利用。

7. 配布とインストールの簡易化


作成したツールを他の環境で簡単に利用できるようにするため、パッケージングやインストールの仕組みを整備します。

推奨方法

  • setuptoolsを使ったPythonパッケージ化。
  • コマンドラインツールとしてインストール可能にするため、entry_pointsを設定。
from setuptools import setup

setup(
    name="my_tool",
    version="1.0",
    py_modules=["tool"],
    install_requires=["click"],
    entry_points={
        "console_scripts": [
            "tool=tool:cli",
        ],
    },
)

まとめ


コマンドラインツール開発では、使いやすさ、拡張性、保守性を重視することが成功の鍵です。ユーザーの視点を取り入れ、スクリプトが直感的で効果的に機能するよう設計しましょう。次項では、これまでの知識を統括し、本記事の総まとめを行います。

まとめ


本記事では、Pythonを使ったコマンドラインツールの作成方法について、基本的な引数の扱いから高度な設計のベストプラクティスまでを解説しました。標準ライブラリであるargparseや、外部ライブラリのclickを活用することで、柔軟で直感的なインターフェースを持つツールを構築できます。

特に、以下のポイントを押さえることで、使いやすさと保守性が向上します：

  • 引数やオプションの構造を整理し、ヘルプメッセージを充実させる。
  • ツールの設計をモジュール化し、大規模なスクリプトにも対応可能にする。
  • ユニットテストやクロスプラットフォーム対応を取り入れ、品質を高める。

これらの知識を実践すれば、ユーザーにとって使いやすいだけでなく、開発者にとっても管理しやすいコマンドラインツールを構築できます。Pythonの柔軟性を活かし、実用的なツール開発に挑戦してみてください。

Python
コマンドライン Python sys.argv

この記事を書いた人

佐藤健司のアバター 佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

関連記事

コメント

コメントする

目次