کتابخانه keyboard در پایتون — راهنمای کامل

کتابخانه keyboard یک ابزار قدرتمند برای کار با ورودی‌های کیبورد در پایتون است. این کتابخانه امکان شنود رویدادهای کلید، ثبت (record) و پخش (playback) رویدادها، تعریف هات‌کی‌ها، شبیه‌سازی فشار کلید و جلوگیری (suppress) از انتشار رویدادها را فراهم می‌کند. در ادامه به نصب، مثال‌های عملی، نکات پلتفرم، و بهترین روش‌ها می‌پردازیم.

نصب و پیش‌نیازها

برای نصب ساده‌ترین روش استفاده از pip است:

pip install keyboard

توضیح: این دستور بسته keyboard را از PyPI نصب می‌کند. در لینوکس معمولاً نیاز به دسترسی ریشه (sudo) دارید تا بتوانید به دستگاه‌های ورودی دسترسی پیدا کنید. در macOS پشتیبانی محدود یا ناموجود است — در صورت نیاز از pynput یا راه‌حل‌های مخصوص مک استفاده کنید.

مثال پایه — شنود رویداد و نوشتن متن

import keyboard

# نوشتن متن با شبیه‌سازی کیبورد
keyboard.write('سلام دنیا!')

# فشردن و رها کردن کلیدها
keyboard.press_and_release('shift+s')

توضیح: keyboard.write متن را کاراکتر به کاراکتر می‌فرستد. press_and_release یک ترکیب کلیدی را به صورت فشردن و رها کردن شبیه‌سازی می‌کند (مثلاً Shift+S).

تعریف هات‌کی (Hotkey)

import keyboard

def my_action():
    print("هات‌کی فعال شد!")

# تعریف هات‌کی غیرمسدودکننده
keyboard.add_hotkey('ctrl+shift+s', my_action)

# برنامه را تا فشردن کلید ESC اجرا نگه می‌دارد
keyboard.wait('esc')

توضیح: add_hotkey تابع یا کال‌بکی را به ترکیب کلیدی مشخص متصل می‌کند. keyboard.wait به صورت بلاک‌کننده تا زمانی که کلید مشخص فشرده شود، برنامه را نگه می‌دارد.

ضبط و پخش رویدادها

import keyboard

print("برای پایان ضبط Enter را بزنید")
events = keyboard.record(until='enter')
print("در حال پخش...")
keyboard.play(events, speed_factor=1)

توضیح: keyboard.record رویدادهای کلیدی را تا فشردن کلید مشخص ذخیره می‌کند و keyboard.play آن‌ها را دوباره اجرا می‌کند. پارامتر speed_factor برای تغییر سرعت پخش به کار می‌رود.

جلوگیری از انتشار رویداد (suppress) و امنیت

import keyboard

# جلوگیری از انتشار ترکیب Ctrl+Alt+X
keyboard.add_hotkey('ctrl+alt+x', lambda: print("دستکاری شد"), suppress=True)

keyboard.wait('esc')

توضیح: با قرار دادن suppress=True، رویداد به سیستم عامل ارسال نمی‌شود (مثلاً پنجره یا دیگر برنامه‌ها آن کلید را دریافت نمی‌کنند). این قابلیت باید با احتیاط استفاده شود چون می‌تواند تجربه کاربری را مختل کند.

نسخهٔ بهبود یافته: مدیریت پاکسازی و خروج امن

import keyboard
import time

def on_exit():
    print("در حال خروج؛ پاکسازی...")
    keyboard.unhook_all()
    raise SystemExit

keyboard.add_hotkey('ctrl+q', on_exit)

try:
    print("در حال اجرا... از Ctrl+Q برای خروج استفاده کنید")
    while True:
        time.sleep(1)
except KeyboardInterrupt:
    keyboard.unhook_all()

توضیح: این نسخه با استفاده از try/finally یا unhook_all اطمینان می‌دهد که هنگامی که برنامه خاتمه می‌یابد، همه هوک‌ها حذف می‌شوند. این کار از به‌جا ماندن شنونده‌ها در پس‌زمینه جلوگیری می‌کند.

کار با نخ (threading) برای شنود غیرمسدودکننده

import keyboard
import threading

def background_listener():
    keyboard.wait('esc')
    print("ESC فشرده شد؛ خروج از نخ")

t = threading.Thread(target=background_listener, daemon=True)
t.start()

print("برنامه اصلی ادامه می‌دهد...")
# عملیات دیگر برنامه

توضیح: با اجرای شنونده در یک نخ جدا، می‌توان برنامه اصلی را ادامه داد بدون اینکه منتظر کلید خاصی بماند. استفاده از daemon=True باعث می‌شود نخ در زمان خروج برنامه بسته شود.

محدودیت‌ها و نکات پلتفرم

• Windows: این کتابخانه بهترین پشتیبانی را دارد و اکثر امکانات بدون نیاز به دسترسی ویژه کار می‌کنند.
• Linux: معمولاً نیاز به اجرای برنامه با دسترسی ریشه (sudo) یا تنظیم مجوزها برای دسترسی به /dev/input/* دارید.
• macOS: پشتیبانی رسمی محدود است؛ برای کارهای مشابه معمولاً باید از کتابخانه‌هایی مثل pynput یا APIهای مخصوص مک استفاده کنید.

امنیت، حفظ حریم خصوصی و ملاحظات اخلاقی

کتابخانه keyboard می‌تواند برای ساخت ابزارهای مفید مانند میانبرها یا تست‌های اتوماسیون استفاده شود، اما به‌خاطر قابلیت شنود و ثبت کلیدها ممکن است به‌عنوان کیلاگر به‌کار رود. حتماً قوانین محلی و رضایت کاربران را رعایت کنید و از آن در محیط‌های امن و با مجوز استفاده نمایید.

جدول مرجع توابع پرکاربرد

نکات پیشرفته و بهینه‌سازی

• در برنامه‌هایی با رابط کاربری (GUI)، از اجرا در نخ اصلی UI خودداری کنید؛ شنود را در نخ جدا اجرا کنید.
• برای فرایندهای پس‌زمینه که نیاز به دسترسی دائمی دارند، مطمئن شوید که مدیریت خطا و پاکسازی مناسبی دارید.
• اگر نیاز به پشتیبانی کامل macOS دارید از کتابخانه‌هایی مانند pynput استفاده کنید که از Quartz بهره می‌برند.

با این راهنما می‌توانید از کتابخانه keyboard برای ساخت میانبرها، اسکریپت‌های اتوماسیون، ابزارهای تست و نمونه‌های آموزشی استفاده کنید؛ اما همیشه مجوزها و مسائل امنیتی را در نظر داشته باشید.

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

ارسال