PythonライブラリAutoPy徹底解説：デスクトップ操作自動化の世界へ 🖱️⌨️

AutoPyは、PythonでGUI（グラフィカルユーザーインターフェース）操作を自動化するための、シンプルでクロスプラットフォームなライブラリです。キーボード入力、マウス操作、画面上の色や画像の検索、アラート表示といった機能を、プラットフォーム（macOS, Windows, Linux/X11）の違いを意識することなく利用できます。

AutoPyはツールキットとして設計されており、複雑なフレームワークとは異なり、シンプルで直感的なAPIを提供します。これにより、開発者はGUIオートメーションの基本的な機能を簡単に組み込むことができます。

主な用途 ✨

• 繰り返し行うGUI操作の自動化
• ソフトウェアの自動テスト
• 簡単なボット作成
• 画面上の特定要素の監視

例えば、「特定のアプリケーションを開いて、テキストを入力し、ボタンをクリックする」といった一連の作業をスクリプト化できます。

AutoPyを利用するには、まずPythonがインストールされている必要があります。Python 3.5以降が推奨されています（Python 2.7もサポートされていましたが、最新の状況ではPython 3系が主流です）。

インストールはpipコマンドを使って簡単に行えます。ターミナルまたはコマンドプロンプトを開き、以下のコマンドを実行してください。

pip install autopy

多くの場合、このコマンドでバイナリホイール（コンパイル済みパッケージ）がインストールされ、すぐに利用できます。

インストール時の注意点 ⚠️

# エラーが出た場合の代替手順 (Rustが必要な場合)
rustup default nightly-2019-10-05
pip install setuptools-rust
pip install autopy

AutoPyの主要な機能は、いくつかのモジュールに分かれています。

1. マウス操作 (`autopy.mouse`) 🖱️

マウスカーソルの移動やクリック、ドラッグなどの操作を行います。

• move(x, y): 指定した座標 (x, y) にマウスカーソルを瞬時に移動します。
• smooth_move(x, y): 指定した座標 (x, y) にマウスカーソルを滑らかに移動します。人間らしい動きに見せたい場合に便利です。
• click(button=LEFT_BUTTON, delay=None): 現在のマウスカーソル位置でクリックします。ボタン（左、右、中央）やクリック後の待機時間を指定できます。
• toggle(down, button=LEFT_BUTTON): マウスボタンを押し下げた状態にする（`down=True`）か、解放する（`down=False`）かを制御します。ドラッグ操作に利用します。
• Button: autopy.mouse.Button.LEFT, .RIGHT, .MIDDLE といった定数でクリックするボタンを指定します。

コード例:

import autopy
import time

# 画面サイズを取得
width, height = autopy.screen.size()
print(f"画面サイズ: {width}x{height}")

# 左上 (10, 10) に瞬間移動
autopy.mouse.move(10, 10)
time.sleep(1)

# 画面中央 (width/2, height/2) に滑らかに移動
autopy.mouse.smooth_move(width / 2, height / 2)
time.sleep(1)

# 現在位置で左クリック
autopy.mouse.click()
time.sleep(1)

# (100, 200) に移動して右クリック
autopy.mouse.move(100, 200)
autopy.mouse.click(autopy.mouse.Button.RIGHT)
time.sleep(1)

# ドラッグ操作 (例: (300, 300) から (500, 500) へドラッグ)
autopy.mouse.move(300, 300)
autopy.mouse.toggle(True) # マウスボタンを押す
autopy.mouse.smooth_move(500, 500)
autopy.mouse.toggle(False) # マウスボタンを離す
print("マウス操作完了 ✅")

2. キーボード操作 (`autopy.key`) ⌨️

キーボードからの文字入力や特殊キーの押下をシミュレートします。

• tap(key, modifier=[]): 指定したキーを一回押して離します（タップ）。Shiftキーなどの修飾キーとの組み合わせも可能です。
• toggle(key, down, modifier=[]): 指定したキーを押し下げた状態にする（`down=True`）か、解放する（`down=False`）かを制御します。
• type_string(string, wpm=0): 指定した文字列をタイプします。`wpm`でタイピング速度（Words Per Minute）を指定できます（0は最速）。
• Code: エンターキー (autopy.key.Code.ENTER)、バックスペース (autopy.key.Code.BACKSPACE)、ファンクションキー (autopy.key.Code.F1 など) といった特殊キーを表す定数です。
• Modifier: 修飾キー (autopy.key.Modifier.SHIFT, .CONTROL, .ALT, .META) を表す定数です。リストで複数指定できます。

コード例:

import autopy
import time

# 少し待機 (他のウィンドウをアクティブにする時間)
time.sleep(3)

# 文字列を入力
autopy.key.type_string("Hello from AutoPy! 👋", wpm=100)
time.sleep(0.5)

# Enterキーをタップ
autopy.key.tap(autopy.key.Code.ENTER)
time.sleep(0.5)

# Shiftキーを押しながら 'a' をタップ (大文字の 'A' を入力)
autopy.key.tap('a', [autopy.key.Modifier.SHIFT])
time.sleep(0.5)

# Ctrl + C (コピー) を実行
autopy.key.tap('c', [autopy.key.Modifier.CONTROL]) # macOSでは autopy.key.Modifier.META を使う場合が多い
print("キーボード操作完了 ✅")

※ CtrlキーはWindows/Linuxでは `CONTROL`、macOSでは `META` (Commandキー) を使うのが一般的です。

3. 画面操作 (`autopy.screen`) 🖥️

画面上の情報を取得したり、特定の色や画像（ビットマップ）を探したりします。

• size(): メインディスプレイの解像度 (幅, 高さ) をタプルで返します。
• scale(): ディスプレイのスケーリング係数（例: Retinaディスプレイなど）を返します。
• get_color(x, y): 指定した座標 (x, y) のピクセルの色を16進数の整数値で返します。
• find_color(color, tolerance=0.0, rect=None): 指定した色（16進数）に一致するピクセルを画面上（または指定した矩形 `rect` 内）で探し、最初に見つかった座標 (x, y) を返します。見つからなければ `None` を返します。`tolerance` で色の許容誤差を指定できます。
• find_bitmap(bitmap, tolerance=0.0, rect=None): 指定したビットマップ画像 (`autopy.bitmap.Bitmap` オブジェクト) が画面上（または指定した矩形 `rect` 内）に現れる場所を探し、最初に見つかった座標 (x, y) を返します。見つからなければ `None` を返します。
• capture(rect=None): 画面全体（または指定した矩形 `rect`）のスクリーンショットを撮り、`autopy.bitmap.Bitmap` オブジェクトとして返します。

コード例:

import autopy

# 画面サイズとスケールを取得
width, height = autopy.screen.size()
scale = autopy.screen.scale()
print(f"画面サイズ: {width}x{height}, スケール: {scale}")

# 座標 (100, 100) の色を取得 (16進数)
hex_color = autopy.screen.get_color(100, 100)
print(f"(100, 100) の色 (16進数): {hex_color:06x}") # 例: 0xffffff (白)

# 16進数をRGBタプルに変換するヘルパー関数
def hex_to_rgb(hex_color):
    if hex_color is None:
        return None
    # 0xFFFFFF のような形式を想定
    blue = hex_color & 255
    green = (hex_color >> 8) & 255
    red = (hex_color >> 16) & 255
    return (red, green, blue)

print(f"(100, 100) の色 (RGB): {hex_to_rgb(hex_color)}")

# 白 (0xffffff) のピクセルを探す
white_pixel_location = autopy.screen.find_color(0xFFFFFF)
if white_pixel_location:
    print(f"白いピクセルが見つかりました: {white_pixel_location}")
    # 見つかった場所をクリック
    # autopy.mouse.move(*white_pixel_location)
    # autopy.mouse.click()
else:
    print("白いピクセルは見つかりませんでした。")

# 画面全体のスクリーンショットを撮って保存
try:
    full_screenshot = autopy.screen.capture()
    full_screenshot.save("full_screenshot.png")
    print("画面全体のスクリーンショットを 'full_screenshot.png' に保存しました。")
except Exception as e:
    print(f"スクリーンショットの保存に失敗しました: {e}")

# 特定の領域 (左上 100x100 ピクセル) のスクリーンショット
try:
    rect_screenshot = autopy.screen.capture(((0, 0), (100, 100)))
    rect_screenshot.save("rect_screenshot.png")
    print("特定領域のスクリーンショットを 'rect_screenshot.png' に保存しました。")
except Exception as e:
    print(f"特定領域のスクリーンショットの保存に失敗しました: {e}")

print("画面操作完了 ✅")

※ `find_bitmap` を使用するには、あらかじめ探したい画像を `autopy.bitmap.Bitmap.open(‘image.png’)` のように読み込んでおく必要があります。

4. ビットマップ操作 (`autopy.bitmap`) 🖼️

画像ファイル（PNGなど）を読み込んだり、画面からキャプチャした画像データを扱ったりします。`autopy.screen.find_bitmap` などで利用されます。

• Bitmap.open(filepath): 指定されたパスの画像ファイルを読み込み、`Bitmap` オブジェクトを返します。
• Bitmap オブジェクトのメソッド:
  • save(filepath): ビットマップを指定したファイルパスに保存します。
  • get_color(x, y): ビットマップ内の指定座標の色を取得します。
  • find_bitmap(other_bitmap, tolerance): 自身のビットマップ内で別のビットマップを探します。
  • width, height: ビットマップの幅と高さを取得します。
  • is_valid(): ビットマップが有効かどうかを返します。

コード例 (画像の読み込みと検索):

import autopy
import time

# 探したい画像ファイル (例: 'button.png') を用意しておく
TARGET_IMAGE_PATH = 'button.png' # このファイルを事前に用意してください

try:
    # 画像をビットマップとして読み込む
    target_bitmap = autopy.bitmap.Bitmap.open(TARGET_IMAGE_PATH)
    print(f"'{TARGET_IMAGE_PATH}' を読み込みました。サイズ: {target_bitmap.width}x{target_bitmap.height}")

    # 画面上でこのビットマップを探す (5秒間試行)
    print("画面上で画像を探しています...")
    found_location = None
    start_time = time.time()
    while time.time() - start_time < 5: # 5秒間探す
        found_location = autopy.screen.find_bitmap(target_bitmap, tolerance=0.1) # toleranceで類似度を許容
        if found_location:
            break
        time.sleep(0.5)

    if found_location:
        print(f"画像が見つかりました！座標: {found_location}")
        # 見つかった画像の中心をクリックする例
        center_x = found_location[0] + target_bitmap.width / 2
        center_y = found_location[1] + target_bitmap.height / 2
        autopy.mouse.smooth_move(center_x, center_y)
        time.sleep(0.5)
        autopy.mouse.click()
        print("画像をクリックしました。")
    else:
        print("画像は見つかりませんでした。")

except FileNotFoundError:
    print(f"エラー: 画像ファイル '{TARGET_IMAGE_PATH}' が見つかりません。")
except Exception as e:
    print(f"エラーが発生しました: {e}")

print("ビットマップ操作完了 ✅")

※ この例を実行するには、`button.png` という名前の画像ファイルをスクリプトと同じディレクトリに配置しておく必要があります。

例1: メモ帳を開いて文字を入力する (Windowsの場合)

Windowsの「メモ帳」を開き、簡単なメッセージを入力して保存する操作を自動化します。

import autopy
import time
import platform

def run_notepad_example():
    if platform.system() != "Windows":
        print("この例はWindows専用です。")
        return

    print("メモ帳を開いて操作します...(5秒後に開始)")
    time.sleep(5)

    # 1. 「ファイル名を指定して実行」(Win + R) を開く
    autopy.key.tap(autopy.key.Code.WINDOWS) # Windowsキーを押す
    time.sleep(0.1)
    autopy.key.tap('r', [autopy.key.Modifier.META]) # Win + R (macOSではCommand+RだがここではWinキーを流用)
    # autopy.key.toggle(autopy.key.Code.WINDOWS, True) # Winキーを押したまま
    # autopy.key.tap('r')
    # autopy.key.toggle(autopy.key.Code.WINDOWS, False) # Winキーを離す
    time.sleep(1) # ダイアログが表示されるのを待つ

    # 2. "notepad" と入力してEnter
    autopy.key.type_string("notepad")
    time.sleep(0.5)
    autopy.key.tap(autopy.key.Code.ENTER)
    time.sleep(2) # メモ帳が起動するのを待つ

    # 3. メモ帳に文字を入力
    autopy.key.type_string("これはAutoPyによる自動入力です。\n")
    time.sleep(0.5)
    autopy.key.type_string("Hello, Automation World! ✨\n")
    time.sleep(1)

    # 4. ファイルを保存 (Ctrl + S)
    autopy.key.tap('s', [autopy.key.Modifier.CONTROL])
    time.sleep(1) # 「名前を付けて保存」ダイアログが表示されるのを待つ

    # 5. ファイル名を入力してEnter
    autopy.key.type_string("autopy_test.txt")
    time.sleep(0.5)
    autopy.key.tap(autopy.key.Code.ENTER)
    time.sleep(1) # 保存されるのを待つ

    # (もしファイルが存在する場合の上書き確認に対応)
    # autopy.key.tap(autopy.key.Code.ENTER) # 必要に応じて追加
    # time.sleep(1)

    # 6. メモ帳を閉じる (Alt + F4)
    autopy.key.toggle(autopy.key.Modifier.ALT, True)
    autopy.key.tap(autopy.key.Code.F4)
    autopy.key.toggle(autopy.key.Modifier.ALT, False)

    print("メモ帳の操作が完了しました。'autopy_test.txt' が保存されたはずです。🎉")

if __name__ == "__main__":
    run_notepad_example()

※ このスクリプトはWindows環境での実行を想定しています。キーの組み合わせや待機時間は環境によって調整が必要な場合があります。

例2: 画面上の特定の画像を見つけてクリックする

前述のビットマップ操作の例と同様ですが、特定のアプリケーションのボタンなど、GUI要素を画像で見つけて操作するシナリオです。

import autopy
import time

# クリックしたいボタンの画像ファイル
BUTTON_IMAGE = 'submit_button.png' # 事前にボタンのスクリーンショットを用意

def find_and_click_image(image_path, timeout=10, tolerance=0.1):
    """指定された画像を画面上で探し、見つかったらクリックする"""
    try:
        target_bitmap = autopy.bitmap.Bitmap.open(image_path)
        print(f"画像 '{image_path}' を探しています (タイムアウト: {timeout}秒)...")

        start_time = time.time()
        location = None
        while time.time() - start_time < timeout:
            location = autopy.screen.find_bitmap(target_bitmap, tolerance=tolerance)
            if location:
                print(f"画像が見つかりました: {location}")
                # 画像の中心座標を計算
                center_x = location[0] + target_bitmap.width / 2
                center_y = location[1] + target_bitmap.height / 2
                
                # マウスを移動してクリック
                autopy.mouse.smooth_move(center_x, center_y)
                time.sleep(0.3) # 移動後に少し待つ
                autopy.mouse.click()
                print(f"座標 ({center_x:.0f}, {center_y:.0f}) をクリックしました。🖱️")
                return True
            time.sleep(0.5) # 0.5秒ごとに再試行

        print("画像が見つかりませんでした。")
        return False

    except FileNotFoundError:
        print(f"エラー: 画像ファイル '{image_path}' が見つかりません。")
        return False
    except Exception as e:
        print(f"エラーが発生しました: {e}")
        return False

if __name__ == "__main__":
    print("画像検索クリックテストを開始します...(3秒後)")
    time.sleep(3) # 準備時間
    
    # 用意したボタン画像を探してクリック
    if find_and_click_image(BUTTON_IMAGE):
        print("処理成功 🎉")
    else:
        print("処理失敗 😥")

※ この例を実行するには、クリックしたいUI要素（例：送信ボタン）のスクリーンショットを撮り、`submit_button.png` という名前で保存しておく必要があります。画像の精度や画面の状態によって `tolerance` の調整が必要になることがあります。

AutoPyには、他のGUI自動化ライブラリと比較していくつかの利点と欠点があります。

AutoPyと同様の機能を提供し、より活発に開発・メンテナンスされているライブラリも存在します。AutoPyで問題が発生した場合や、より高機能なライブラリが必要な場合は、以下の代替案を検討する価値があります。

プロジェクトの要件や使用するOS、必要な機能、メンテナンス状況などを考慮して、最適なライブラリを選択することが重要です。特に新規プロジェクトでは、より活発にメンテナンスされている PyAutoGUI を第一候補として検討することをお勧めします。

AutoPyや他のGUI自動化ツールを使用する際には、以下の点に注意が必要です。

• OSの権限設定: 特にmacOSでは、スクリプトを実行する環境（ターミナル、IDEなど）にアクセシビリティ権限を付与しないと、マウスやキーボードの操作がブロックされます。Windowsでも管理者権限が必要になる場合があります。
• 予期せぬ動作のリスク: 自動化スクリプトは、意図しないタイミングや状況で実行されると、予期せぬ動作（ファイルの削除、誤った情報の送信など）を引き起こす可能性があります。スクリプトの実行中はPCの操作を控える、緊急停止手段を用意するなどの対策が重要です。PyAutoGUIにはフェイルセーフ機能（マウスカーソルを画面隅に移動させると強制停止）がありますが、AutoPyには標準では搭載されていません。
• 画面解像度やレイアウトへの依存: 座標ベースや画像ベースの自動化は、画面の解像度、ウィンドウのサイズや位置、UIのテーマなどが変わると動作しなくなる可能性があります。可能な限り、相対座標を使ったり、画像認識の許容度（tolerance）を調整したりする工夫が必要です。
• タイミングの問題: アプリケーションの応答速度は常に一定ではありません。固定長の `time.sleep()` だけに頼らず、特定の画像が表示されるまで待機する、ウィンドウがアクティブになるまで待つなどの動的な待機処理を実装することが、安定した自動化には不可欠です。
• メンテナンス状況の確認: AutoPyは開発が停滞している可能性があるため、長期的なプロジェクトや最新環境での利用にはリスクが伴います。代替ライブラリの利用も視野に入れましょう。