کتابخانه pyautogui در پایتون — معرفی و کاربردها

کتابخانه pyautogui یک ابزار سبک و قدرتمند برای اتوماسیون رابط کاربری گرافیکی (GUI) در پایتون است. با pyautogui می‌توانید موس و کیبورد را شبیه‌سازی کنید، از صفحه‌نمایش اسکرین‌شات بگیرید، و المان‌های گرافیکی را با روش‌های مبتنی بر تصویر پیدا کنید. این کتابخانه برای ساخت اسکریپت‌های خودکار، تست‌های رابط کاربری، یا خودکارسازی کارهای تکراری بسیار مناسب است.

ویژگی‌های کلیدی

• حرکت موس و کلیک‌ها (move, click, doubleClick)
• تایپ متن و فشردن کلیدهای ترکیبی (typewrite, hotkey)
• گرفتن اسکرین‌شات و جستجوی تصویر (screenshot, locateOnScreen)
• پشتیبانی از تنظیمات توقف (PAUSE) و مکانیزم Fail-safe
• سازگاری با ویندوز، مک و لینوکس

نصب و وابستگی‌ها

نصب پایه‌ای با pip انجام می‌شود. اگر قصد دارید از قابلیت شناسایی تصویر با دقت (confidence) استفاده کنید، نیاز به نصب OpenCV دارید. همچنین برای اسکرین‌شات‌ها از Pillow استفاده می‌شود که معمولاً به‌صورت وابستگی نصب می‌گردد.

pip install pyautogui
# برای قابلیت confidence:
pip install opencv-python

این دستورات pyautogui و در صورت نیاز opencv را نصب می‌کنند. پس از نصب می‌توانید وارد استفاده سریع شوید.

مفاهیم پایه و مثال‌های عملی

در ادامه چند مثال رایج با توضیح زبانی آورده شده است. همه‌ی کدها باید با احتیاط اجرا شوند زیرا اسکریپت‌ها کنترل موس و کیبورد را می‌گیرند.

import pyautogui
pyautogui.moveTo(100, 200, duration=0.5)  # حرکت موس به مختصات x=100, y=200
pyautogui.click()                          # کلیک چپ در موقعیت فعلی
pyautogui.write('Hello, World!', interval=0.05)  # تایپ متن با تاخیر بین حروف
pyautogui.press('enter')                   # فشردن کلید Enter

در این مثال موس به مختصات معینی منتقل می‌شود، کلیک اجرا می‌گردد، متن تایپ می‌شود و سپس کلید Enter فشار داده می‌شود. آرگومان duration زمان حرکت موس را کنترل می‌کند و interval سرعت تایپ را تعیین می‌کند.

استفاده از کلیدهای ترکیبی و Hotkey

import pyautogui
pyautogui.hotkey('ctrl', 'c')   # شبیه‌سازی Ctrl+C
pyautogui.hotkey('ctrl', 'v')   # شبیه‌سازی Ctrl+V

متد hotkey چندین کلید را پشت‌سرهم و با ترتیب مناسب فشار می‌دهد که برای کپی-پیست یا میانبرهای کیبورد مفید است.

گرفتن اسکرین‌شات و تشخیص تصویر

import pyautogui
s = pyautogui.screenshot()
s.save('screen.png')

# پیدا کردن تصویر روی صفحه (نیاز به opencv برای آرگومان confidence)
location = pyautogui.locateOnScreen('button.png', confidence=0.8)
if location:
    x, y = pyautogui.center(location)
    pyautogui.click(x, y)

کد بالا ابتدا یک اسکرین‌شات کامل می‌گیرد و آن را ذخیره می‌کند. سپس تصویر کوچکی (button.png) را روی صفحه جستجو می‌کند؛ در صورت پیدا شدن، مرکز آن محاسبه شده و کلیک می‌شود. پارامتر confidence برای مقایسه‌ی دقیق‌تر نیاز به OpenCV دارد.

موارد پیشرفته و نکات عملکردی

• پراکندگی یا resolution: مختصات موس بر اساس رزولوشن صفحه است؛ هنگام جابجایی بین مانیتورها یا تغییر رزولوشن مراقب باشید.
• locateAll و locateCenterOnScreen برای یافتن چندین نمونه یا مرکز تصاویر مفیدند.
• برای کار در محیط‌های بدون نمایشگر (مانند سرورها) می‌توانید از Xvfb یا virtual display استفاده کنید.

ایمنی و بهترین شیوه‌ها

pyautogui دارای مکانیسم Fail-safe است: اگر موس را به گوشهٔ بالای سمت چپ صفحه بکشید، pyautogui یک Ausnahme از نوع FailSafeException پرتاب می‌کند تا اسکریپت متوقف شود. همچنین مقدار پیش‌فرض pyautogui.PAUSE بین فراخوانی‌ها مکثی کوتاه می‌گذارد که از رفتارهای خیلی سریع جلوگیری می‌کند.

import pyautogui, time

pyautogui.FAILSAFE = True
pyautogui.PAUSE = 0.1

try:
    for i in range(10):
        pyautogui.click(100 + i*10, 200)
        time.sleep(0.2)
except pyautogui.FailSafeException:
    print("Script stopped by user moving mouse to top-left corner.")

در این اسکریپت تنظیمات Fail-safe فعال است و یک حلقه کلیک با مکث اجرا می‌شود؛ اگر کاربر موس را به گوشهٔ بالا-چپ حرکت دهد، اجرای اسکریپت متوقف و پیام مناسبی چاپ می‌شود.

مثال مقاوم‌تر: پیدا کردن تصویر با تکرار و Timeout

import pyautogui, time

def wait_and_click(image, timeout=10, confidence=0.8):
    start = time.time()
    while time.time() - start < timeout:
        loc = pyautogui.locateOnScreen(image, confidence=confidence)
        if loc:
            pyautogui.click(pyautogui.center(loc))
            return True
        time.sleep(0.5)
    return False

if not wait_and_click('submit.png', timeout=15):
    print('Submit button not found.')

این تابع تا زمان اتمام Timeout تصویر را جستجو می‌کند و در صورت پیدا کردن کلیک می‌کند. این الگو برای اسکریپت‌هایی که با تاخیرهای بارگذاری صفحه مواجه‌اند مفید است و از خطاهای ناگهانی جلوگیری می‌کند.

جدول خلاصه توابع مهم

محدودیت‌ها و هشدارها

pyautogui بر پایه شبیه‌سازی ورودی‌های کاربر کار می‌کند و نمی‌تواند با پنجره‌های بسیار امن یا اجزای محافظت‌شده تعامل عمیق انجام دهد. همچنین تغییر در رابط کاربری (آیکون‌ها، رنگ، مقیاس) ممکن است جستجوی تصویری را ناکارآمد کند. برای کاربردهای حساس به دقت، از ترکیب روش‌های مبتنی بر تصویر و روش‌های API محور استفاده کنید.

جمع‌بندی و نکات نهایی

کتابخانه pyautogui ابزاری ساده، قابل‌فهم و کاربردی برای خودکارسازی تعامل با رابط کاربری است. با رعایت نکات ایمنی (FAILSAFE، PAUSE)، کنترل رزولوشن و به‌کارگیری استراتژی‌هایی مانند retry و timeout می‌توانید اسکریپت‌های پایدار و قابل اتکایی بسازید. برای دقت بالاتر در تشخیص تصاویر از OpenCV استفاده کنید و در محیط‌های بدون رابط گرافیکی از نمایشگرهای مجازی بهره ببرید.

با تمرین و طراحی سناریوهای کوچک می‌توانید این ابزار را در اتوماسیون وظایف روزمره، تست خودکار UI و کاربردهای مشابه به‌خوبی به کار ببرید.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال