停止とフェイルセーフ

プログラムにバグがありキーボードやマウスを使ってシャットダウンできなくなっても、PyAutoGUIのフェイルセーフ機能を使えます。マウスを画面の四隅に向けて素早く動かします。PyAutoGUIの関数は呼び出しごとに0.1秒停止してからアクションを実行するので、マウスを四隅に動かす時間の余裕があります。PyAutoGUIはマウスカーソルが四隅にあればpyautogui.FailSafeException例外を送出します。PyAutoGUI固有の機能です。pyautogui.PAUSEに0.1以外の数値を設定すれば停止秒数を調整することができます。

PyAutoGUIプログラムを停止させる必要があるときは、マウスを画面の四隅に向けて素早く動かして停止させてください。

ログアウト

制御できなくなったGUI自動化プログラムを停止させる最もシンプルな方法はログアウトです。ログアウトすればすべての実行中のプログラムが終了します。WindowsとLinuxではCTRL-ALT-DELを押します。macOSでは-SHIFT-Qを押します。ログアウトしたら保存していない作業は失われますが、コンピュータの再起動より手軽です。

マウスの移動

画面の座標を理解できたのでマウスの移動を説明します。pyautogui.moveTo()関数はマウスカーソルを指定した位置へと瞬時に移動させます。この関数の第一引数はx座標、第二引数はy座標の整数値です。オプションのdurationキーワード引数では、整数または浮動小数点数でマウスの移動時間を秒単位で指定します。このキーワード引数を指定しない場合のデフォルトは0で、瞬時に移動します。（PyAutoGUIの関数のdurationキーワード引数はすべてオプションです。）

>>> import pyautogui
>>> for i in range(10):  # 正方形を描くようにマウスを動かす
...     pyautogui.moveTo(100, 100, duration=0.25)
...     pyautogui.moveTo(200, 100, duration=0.25)
...     pyautogui.moveTo(200, 200, duration=0.25)
...     pyautogui.moveTo(100, 200, duration=0.25)
...

この例では、指定した座標で時計回りに正方形を10回描くようにマウスカーソルを動かします。duration=0.25とキーワード引数を指定しているので、一つの移動に0.25秒かかります。pyautogui.moveTo()呼び出しで第三引数を指定しなければマウスカーソルは瞬間移動します。

pyautogui.move()関数はマウスカーソルを現在の位置から相対的に移動させます。以下の例では先ほどの例と同じようにマウスを移動させますが、コードの実行開始時にマウスがあった位置を出発点とします。

>>> import pyautogui
>>> for i in range(10):
...     pyautogui.move(100, 0, duration=0.25)  # 右
...     pyautogui.move(0, 100, duration=0.25)  # 下
...     pyautogui.move(-100, 0, duration=0.25)  # 左
...     pyautogui.move(0, -100, duration=0.25)  # 上
...

pyautogui.move()関数も3つの引数を取ります。右方向に移動させるピクセル数、下方向に移動させるピクセル数、移動に要する時間（オプション）です。第一引数に負の整数を指定すると左方向に、第二引数に負の整数を指定すると上方向に、それぞれマウスを移動させます。

現在位置の取得

pyautogui.position()関数を呼び出すとマウスの現在位置を取得できます。関数が呼び出されたときにマウスカーソルがあるx座標とy座標のPoint名前付きタプルが返されます。Point名前付きタプルの0と1の整数インデックスかxとyの属性でx座標とy座標にアクセスできます（widthとheightの属性があるSize名前付きタプルと似ています）。対話型シェルに以下の内容を入力してマウスの現在位置を取得してみてください。

>>> pyautogui.position()  # マウスの現在位置の取得
Point(x=311, y=622)
>>> pyautogui.position()  # マウスの現在位置をもう一度取得
Point(x=377, y=481)
>>> p = pyautogui.position()  # さらにもう一度取得
>>> p
Point(x=1536, y=637)
>>> p[0]  # インデックス0はx座標
1536
>>> p.x  # 属性xもx座標
1536

マウスカーソルの位置に応じて実行結果が変わります。

クリック

pyautogui.click()メソッドを呼び出せばバーチャルなマウスクリックをコンピュータに送信できます。デフォルトではマウスの現在位置での左クリックです。オプションの第一引数と第二引数を渡せばx座標とy座標を指定してクリックを送信できます。

マウスのどのボタンをクリックするかはbuttonキーワード引数で'left'、'middle'、'right'のいずれかを指定します。例えば、pyautogui.click(100, 150, button='left')は座標(100, 150)でマウスを左クリックしますし、pyautogui.click(200, 250, button='right')は(200, 250)で右クリックします。

以下の式を対話型シェルに入力してみてください。

>>> import pyautogui
>>> pyautogui.click(10, 5)  # マウスを(10, 5)に移動してクリック

マウスカーソルが画面の左上隅付近に移動して1回左クリックします。「クリック」とはマウスのボタンを押してそのまま動かさずに離す動作です。マウスのボタンを押すpyautogui.mouseDown()を呼び出してからマウスのボタンを離すpyautogui.mouseUp()を呼び出してもクリックする動作になります。これらの関数はclick()と同じ引数を取ります。click()関数はこれら2つの関数を呼び出す便利なラッパーです。

さらに便利なように、pyautogui.doubleClick()関数はマウスの左クリックを2回行います（ダブルクリック）。pyautogui.rightClick()関数で右クリック、pyautogui.middleClick()関数で中クリックを実行できます。

ドラッグ

ドラッグとはマウスのボタンを押しながら移動させる動作のことです。例えば、ファイルをフォルダアイコンにドラッグすればそのフォルダに移動できますし、カレンダーアプリの予定をドラッグで移動させられます。

PyAutoGUIには、マウスカーソルを指定位置までドラッグするpyautogui.dragTo()と、現在位置から相対的に位置を指定して移動させるpyautogui.drag()関数があります。dragTo()とdrag()の引数はmoveTo()とmove()の引数と同じで、x座標（右方向への移動ピクセル数）、y座標（下方向への移動ピクセル数）、オプションの移動時間です。（macOSでは速すぎると正常にドラッグできないので、durationキーワード引数を渡すようにしてください。）

この関数を試してみましょう。WindowsならMS Paint、macOSならPaintbrush、LinuxならGNU Paintなど、描画アプリを開いてください（オンラインのhttps://sumopaint.comでも描画できますので、描画アプリがなければこちらをお使いください）。PyAutoGUIでこれらのアプリに描画します。

描画アプリでキャンバスを開いて鉛筆やブラシを選択した状態で、以下の内容を記載したspiralDraw.pyを実行します。

import pyautogui
❶ pyautogui.sleep(5)
❷ pyautogui.click()  # クリックしてウィンドウをアクティブにする
distance = 300
change = 20
while distance > 0:
  ❸ pyautogui.drag(distance, 0, duration=0.2)  # 右に移動
  ❹ distance = distance - change
  ❺ pyautogui.drag(0, distance, duration=0.2)   # 下に移動
  ❻ pyautogui.drag(-distance, 0, duration=0.2)  # 左に移動
    distance = distance - change
    pyautogui.drag(0, -distance, duration=0.2)  # 上に移動

このプログラムを実行すると5秒間の待機時間があります(❶)。この間にマウスカーソルを鉛筆かブラシを選択した状態で描画アプリのウィンドウに載せてください。PyAutoGUIのsleep()関数はtime.sleep()と全く同じですが、コードにimport timeと書かなくてもすみます。spiralDraw.pyはマウスを制御してクリックすることにより描画アプリのウィンドウをアクティブにします(❷)。アクティブウィンドウとは、キーボードからの入力やマウスのドラッグなどのアクションを受け付けているウィンドウのことです。アクティブウィンドウはフォーカスされたウィンドウや前面のウィンドウと呼ばれることもあります。描画アプリがアクティブなら、spiralDraw.pyは図23-2のような正方形のうず巻きを描画します。

変数distanceはwhileループの初回に300から始まり、最初のdrag()呼び出しが0.2秒でカーソルを300ピクセル右にドラッグします(❸)。それからdistanceを280に減らし(❹)、2回目のdrag()呼び出しがカーソルを280ピクセル下にドラッグさせます(❺)。3回目のdrag()呼び出しはカーソルを280ピクセル左にドラッグさせます(❻)。そしてdistanceを260に減らし、最後のdrag()呼び出しはカーソルを260ピクセル上にドラッグさせます。ループの反復ごとにマウスは右、下、左、上とdistanceを小さくしながらドラッグします。このコードの反復処理により、マウスは正方形のうず巻きを描画します。

第21章で紹介したPillowパッケージでうず巻きを描画することもできますが、マウスを制御してMS Paintで描画すると、図23-2のようにブラシのスタイルを変更できますし、グラデーションや塗りつぶしなどの機能を使うこともできます。ブラシの設定をあらかじめ選択してから（あるいはブラシの設定をするPythonのコードを実行してから）、このうず巻き描画プログラムを実行します。

手でマウスを動かしてこのようなうず巻きを描画することもできますが、正確に描画するにはゆっくりと動かさなければなりません。PyAutoGUIなら数秒で描画できます。

スクロール

最後に紹介するPyAutoGUIのマウスの関数はscroll()です。上下にスクロールさせる量を整数で指定します。OSやアプリケーションによって数値の単位は変わるので、実験して確認する必要があります。スクロールはマウスカーソルの現在位置から始まります。正の整数を渡すと上にスクロールし、負の整数を渡すと下にスクロールします。Muエディタの対話型シェルで以下の内容を実行すると、Muエディタウィンドウでマウスカーソルが上にスクロールします。

>>> pyautogui.scroll(200)

マウスカーソルがテキストフィールドにあればMuが上方にスクロールします。

アクティブウィンドウの取得

アクティブウィンドウとは、画面上で前面に表示されておりキーボード入力を受け付けるウィンドウのことです。Muエディタでコードを書いているところならMuエディタのウィンドウはアクティブウィンドウです。画面上で一つのウィンドウだけがアクティブウィンドウになります。

対話型シェルでpyautogui.getActiveWindow()を呼び出すとWindowオブジェクトを取得できます（Windowsで実行した場合はWin32Windowオブジェクトです）。Windowオブジェクトを取得できれば、サイズ、位置、タイトルなどの属性を取得できます。

left, right, top, bottom そのウィンドウの左端と右端のx座標、上端と下端のy座標を表す整数

topleft, topright, bottomleft, bottomright そのウィンドウの左上、右上、左下、右下の四隅の座標を表すx座標とy座標の2つの整数のPoint名前付きタプル

midleft, midright, midtop, midbottom そのウィンドウの左中央、右中央、上中央、下中央の座標を表すx座標とy座標の2つの整数のPoint名前付きタプル

width, height そのウィンドウの幅と高さをピクセルで表す整数

size そのウィンドウの幅と高さをピクセルで表す2つの整数のSize名前付きタプル

area そのウィンドウの面積をピクセルで表す整数

center そのウィンドウの中央のx座標とy座標を整数で表すPoint名前付きタプル

centerx, centery そのウィンドウの中央のそれぞれx座標とy座標を表す整数

box そのウィンドウの左端、上端、幅、高さを表す4つの整数のBox名前付きタプル

title そのウィンドウの上部に表示されるタイトルバーのテキスト文字列

windowオブジェクトからそのウィンドウの位置、サイズ、タイトルの情報を取得するには、対話型シェルで以下のように入力してください。

>>> import pyautogui
>>> active_win = pyautogui.getActiveWindow()
>>> active_win
Win32Window(hWnd=2034368)
>>> str(active_win)
'<Win32Window left="500", top="300", width="2070", height="1208", title="Mu 1.0.1 – test1.py">'
>>> active_win.title
'Mu 1.0.1 – test1.py'
>>> active_win.size
Size(width=2070, height=1208)
>>> active_win.left, active_win.top, active_win.right, active_win.bottom
(500, 300, 2570, 1508)
>>> active_win.topleft
Point(x=500, y=300)
>>> pyautogui.click(active_win.left + 10, active_win.top + 20)

これらの属性を利用すればウィンドウ内の座標を正確に計算できます。クリックしたいボタンがウィンドウの左上隅から右へ10ピクセル下へ20ピクセルの位置にあることがわかっているとしたら、そのウィンドウの左上隅の画面上の座標が(300, 500)であれば、pyautogui.click(310, 520)を呼び出すとそのボタンをクリックできます。active_winにそのウィンドウのWindowオブジェクトを格納すれば、pyautogui.click(active_win.left + 10, active_win.top + 20でも同じです。この方法であれば、ボタンを見つけるのに遅くて不安定なlocateOnScreen()関数に頼らずにすみます。

他の関数でウィンドウを見つける

getActiveWindow()でその関数を呼び出した時点でのアクティブウィンドウを取得できますが、画面上の別のウィンドウのWindowオブジェクトを取得する必要がある場合もあるでしょう。以下の3つの関数はWindowオブジェクトのリストを返します。ウィンドウを見つけられなければ空のリストを返します。

pyautogui.getAllWindows() 画面上で見えるすべてのウィンドウのWindowオブジェクトのリストを返します。

pyautogui.getWindowsAt(x, y) 点(x, y)を含むすべての見えるウィンドウのWindowオブジェクトのリストを返します。

pyautogui.getWindowsWithTitle(title) タイトルバーに文字列titleを含む、すべての見えるウィンドウのWindowオブジェクトのリストを返します。

PyAutoGUIにはpyautogui.getAllTitles()という関数もあり、すべての見えるウィンドウのタイトル文字列を返します。

ウィンドウの操作

ウィンドウ属性はサイズや位置などの情報を教えてくれるだけではありません。値を設定してウィンドウをリサイズしたり移動したりできます。対話型シェルで次のように入力してみてください。

>>> import pyautogui
>>> active_win = pyautogui.getActiveWindow()
❶ >>> active_win.width  # ウィンドウの幅を取得
1669
❷ >>> active_win.topleft  # ウィンドウの位置を取得
Point(x=174, y=153)
❸ >>> active_win.width = 1000  # ウィンドウのりサイズ
❹ >>> active_win.topleft = (800, 400)  # ウィンドウの移動

まず、Windowオブジェクトの属性からそのウィンドウのサイズ(❶)と位置(❷)の情報を取得します。Muエディタでこれらを実行してアクティブウィンドウであるMuエディタのウィンドウについてサイトと位置の情報を取得してから、図23-5のようにこのウィンドウの幅を狭めて(❸)移動(❹)させます。

ウィンドウの最小化、最大化、アクティブ状態の取得や変更もできます。対話型シェルで次のように入力してみてください。

>>> import pyautogui
>>> active_win = pyautogui.getActiveWindow()
>>> active_win.isMaximized  # ウィンドウが最大化されていればTrueが返される
False
>>> active_win.isMinimized  # ウィンドウが最小化されていればTrueが返される
False
>>> active_win.isActive  # ウィンドウがアクティブであればTrueが返される
True
>>> active_win.maximize()  # ウィンドウの最大化
>>> active_win.isMaximized
True
>>> active_win.restore()  # 最大化／最小化を元に戻す
>>> active_win.minimize()  # ウィンドウの最小化
>>> import time
>>> # 5秒停止してその間に別のウィンドウをアクティブにする
>>> time.sleep(5); active_win.activate()
>>> active_win.close()  # アクティブにしたウィンドウを閉じる

isMaximized、isMinimized、isActive属性にはそのウィンドウが現在最大化されているか、最小化されているか、アクティブであるかを示すブール値が入っています。maximize()、minimize()、activate()、restore()メソッドはウィンドウの状態を変更します。maximize()やminimize()でウィンドウを最大化・最小化した後でrestore()メソッドを呼び出すとそのウィンドウを元のサイズと位置に戻します。

close()メソッドはウィンドウを閉じます。このメソッドでは「本当に終了しますか？」のようなメッセージダイアログを表示せずにアプリケーションを終了してしまうので注意して使ってください。

ウィンドウ機能の詳細についてはPyAutoGUIのドキュメントをご参照ください。

文字列の入力

pyautogui.write()関数でキーボードから文字列を入力できます。入力がどうなるかは、どのウィンドウがアクティブになっていてどのテキストフィールドがフォーカスされているかによって変わります。入力を始める前に目的のテキストフィールドをマウスでクリックしてフォーカスしなければならない場合があります。

簡単な例として、テキストエディタウィンドウにPythonで自動的にHello, world!と入力してみましょう。まず新しいテキストエディタウィンドウを開き、PyAutoGUIで正しくクリックしてフォーカスできるように画面の左上のほうに移動させてください。次に対話型シェルで以下の内容を実行します。

>>> pyautogui.click(100, 200); pyautogui.write('Hello, world!')

セミコロンで区切って2つのコマンドを1行に書いていることに注意してください。こうすれば対話型シェルでコマンドを1つずつ入力せずに一気に実行できます。コマンドを1つずつ入力するとclick()とwrite()の間に対話型シェルをフォーカスしてしまい、うまく動作しません。

このPythonスクリプトは、(100, 200)の座標をマウスでクリックし、テキストエディタウィンドウをフォーカスします。write()を呼び出してHello, world!というテキストをそのウィンドウに送ります。図23-6のようになるはずです。コードから自動的に入力できました。

write()関数はデフォルトで文字列全体を一瞬で入力します。オプションの第二引数で1文字入力するたびに停止する秒数を指定できます。この第二引数は停止する秒数を表す浮動小数点数値です。例えば、pyautogui.write('Hello, world!', 0.25)では、Hを入力してから0.25秒停止し、eを入力してから0.25秒停止し…と続きます。このように段階的に入力すれば、PyAutoGUIのデフォルトでの一瞬の入力についていけない遅いアプリケーションに対応できます。

PyAutoGUIは自動的にSHIFTキーを押してAや!のような文字を入力します。

キーの名前の指定

すべてのキーが一文字で表せるわけではありません。例えば、SHIFTや左矢印キーを一文字で表すことはできません。PyAutoGUIではこうしたキーを短い文字列で表します。'esc'でESCキーを、'enter'でENTERキーを表すといった具合です。

write()には一つの文字列引数を渡すのではなく、キーボードのキーのリストを渡すこともできます。例えば、以下のように呼び出すと、Aキーを入力し、次にBキーを入力し、次に左矢印キーを2回入力し（カーソルをaの前に移動し）、最後にXとYのキーを入力します。

>>> pyautogui.write(['a', 'b', 'left', 'left', 'X', 'Y'])

左矢印キーを押すとカーソルが左に移動しますから、これはXYabという結果になります。PyAutoGUIでwrite()に渡してキー入力をできる文字列を表23-1に一覧で示します。

PyAutoGUIで利用できるキーを表す文字列のリストをpyautogui.KEYBOARD_KEYSで調べることもできます。'shift'という文字列はSHIFTキーを表しますから、'shiftleft'と同じです。同様に、'ctrl'、'alt'、'win'の文字列はすべて左側のキーを表します。

キーを押して離す

mouseDown()とmouseUp()の関数と同じように、pyautogui.keyDown()とpyautogui.keyUp()の関数はキーを押して離します。これらの関数にはキーを表す文字列を引数で渡します（特殊なキーについては表23-1を参照してください）。PyAutoGUIにはこの2つの関数をセットで実行してキーを入力する便利なpyautogui.press()関数があります。

以下のコードを実行すると、ドル記号（$）が入力されます（SHIFTキーを押した状態で4を入力します）。

>>> pyautogui.keyDown('shift'); pyautogui.press('4'); pyautogui.keyUp('shift')

SHIFT,を押し、4を押して離し、SHIFTを離します。テキストフィールドに文字列を入力するならwrite()関数のほうが簡単です。しかしキー入力を受け付けるアプリケーションでは、press()関数のほうが扱いやすいでしょう。

ホットキーの組み合わせ

ホットキーはアプリケーションで何らかの動作を呼び起こすキー入力の組み合わせで、ショートカットと呼ばれることもあります。選択した部分をコピーするのに、WindowsとLinuxではCTRL-C、macOSでは-Cのホットキーがよく使われます。CTRLキーを押したままCキーを押し、Cキーを離してCTRLキーを離します。PyAutoGUIのkeyDown()とkeyUp()の関数でこれを行うなら、以下のように書きます。

pyautogui.keyDown('ctrl')
pyautogui.keyDown('c')
pyautogui.keyUp('c')
pyautogui.keyUp('ctrl')

これは複雑なので、複数のキーを引数に取って順番に押して離してくれるpyautogui.hotkey()関数を使うと便利です。以下のシンプルなコードでCTRL-Cを実行できます。

pyautogui.hotkey('ctrl', 'c')

組み合わせるキーの数が多いホットキーではこの関数の便利さが際立ちます。Wordでは、CTRL-ALT-SHIFT-Sのホットキーの組み合わせでスタイル枠を表示します。8回関数を呼び出すのではなく（keyDown()4回とkeyUp()4回）、hotkey('ctrl', 'alt', 'shift', 's')を1回だけ呼び出せばすみます。

忙しそうに見せる

多くのメッセンジャープログラムでは、一定期間マウスの動きがなければ離席中だと判断されるような仕組みが備わっています。コンピュータから離れても、離席中と表示されて怠けていると思われないようにしたいとします。10秒ごとにマウスカーソルを1ピクセル左右に動かすスクリプトを書いてください。これくらい小さい動きならスクリプトの実行中にコンピュータを操作する邪魔にならないでしょう。

クリップボードを利用したテキストフィールドの読み取り

pyautogui.write()でアプリケーションのテキストフィールドにキー入力をすることができますが、PyAutoGUI単体ではテキストフィールドにすでに入力されているテキストを読み取ることはできません。pyperclipモジュールを利用して、すでに入力されているテキストフィールドを読み取ります。PyAutoGUIでMuやメモ帳などのテキストエディタのウィンドウをクリックして前面に出し、テキストフィールド内をクリックして、CTRL-Aまたは-Aのホットキーですべて選択して、CTRL-Cまたは-Cのホットキーでクリップボードにコピーします。こうすればPythonスクリプトでimport pyperclipとpyperclip.paste()を実行することでクリップボードのテキストを読み取れます。

この手順でウィンドウのテキストフィールドを読み取ってコピーするプログラムを書いてください。pyautogui.getWindowsWithTitle('Notepad')でWindowオブジェクトを取得します（お使いのテキストエディタに応じて'Notepad'の部分を調整してください）。取得したWindowオブジェクトのtopとleftの属性でウィンドウの位置がわかり、activate()メソッドで画面の前面に出すことができます。それからtopとleftの属性に100〜200程度を加えた座標を指定してpyautogui.click()を実行することにより、テキストエディタのテキストフィールドをクリックして、フォーカスしてキー入力を受け付ける状態にします。pyautogui.hotkey('ctrl', 'a')とpyautogui.hotkey('ctrl', 'c')を呼び出してすべて選択してからクリップボードにコピーします。最後に、pyperclip.paste()を呼び出してクリップボードからテキストを取得し、Pythonプログラムに貼り付けます。こうすればこの文字列を好きなように使えます。ここではprint()で表示してみましょう。

PyAutoGUIのウィンドウ関数はPyAutoGUIのバージョン1.0.0現在、macOSとLinuxには対応しておらず、Windowsでしか動作しません。

ゲームをプレイするボットを作成する

Sushi Go Roundという古いFlashゲームがあります。正しい材料のボタンをクリックして客の寿司の注文に応えるゲームです。間違わずに素早く注文に対応できれば高得点が得られます。これはGUI自動化プログラムにうってつけです。ズルをして高得点を目指しましょう。Flashはもうサポートが終了していますが、https://github.com/asweigart/sushigoroundbotにSushi Go Roundをプレイできるサイトを載せています。このGitHubリポジトリには、このゲームをプレイするボットのPythonソースコードもあります。ボットがゲームをプレイする様子はhttps://youtu.be/lfk_T6VKhTEで見られます。