Mouse – управление мышью

Введение

Управление мышью — важный аспект автоматизации взаимодействия с интерфейсом пользователя. Во многих задачах, будь то автотесты, скрипты, игровые боты или утилиты автоматизации, требуется программное перемещение указателя, симуляция кликов и перехват действий пользователя. В Python для этого отлично подходит библиотека mouse.

Библиотека mouse предоставляет простой и прямолинейный API для работы с мышью: отслеживание событий, выполнение кликов, запись и воспроизведение движений. Она подходит для кроссплатформенной разработки, проста в установке и используется как в изолированных скриптах, так и в сложных проектах RPA.

Установка и настройка библиотеки mouse

Установка через pip

pip install mouse

Системные требования и разрешения

На Linux и macOS может потребоваться запуск от имени администратора или предоставление разрешений на управление вводом.

Для Linux:

sudo pip install mouse

Для macOS: Необходимо предоставить доступ в настройках Security & Privacy → Accessibility.

Для Windows: Некоторые функции требуют запуска с правами администратора.

Архитектура и принципы работы

Основные компоненты

Библиотека mouse состоит из нескольких ключевых компонентов:

• Controller — управление курсором и эмуляция действий
• Listener — отслеживание событий мыши
• Recorder — запись и воспроизведение макросов
• Event System — система обработки событий

Поддерживаемые платформы

• Windows (через Windows API)
• macOS (через Cocoa)
• Linux (через X11/Wayland)

Основные возможности библиотеки

Эмуляция действий мыши

mouse работает как на стороне захвата пользовательских действий (listener), так и в качестве эмулятора движений и кликов (controller).

Основные функции:

• Отслеживание нажатий и отпусканий кнопок
• Определение позиции курсора
• Программные клики и прокрутка
• Перемещение курсора
• Горячие клавиши мыши
• Запись и воспроизведение макросов

Типы событий

Библиотека обрабатывает следующие типы событий:

• ButtonEvent — нажатие/отпускание кнопок
• MoveEvent — перемещение курсора
• WheelEvent — прокрутка колесика

Управление курсором и позиционирование

Перемещение курсора

import mouse

# Абсолютное позиционирование
mouse.move(100, 200)

# Относительное перемещение
mouse.move(50, 0, absolute=False)

# Плавное перемещение с задержкой
mouse.move(300, 400, duration=1.0)

Получение текущих координат

# Получение позиции курсора
x, y = mouse.get_position()
print(f"Курсор находится в точке: ({x}, {y})")

# Использование в условиях
if mouse.get_position()[0] > 500:
    print("Курсор в правой части экрана")

Эмуляция кликов и действий

Основные виды кликов

# Левый клик
mouse.click('left')
mouse.left_click()

# Правый клик
mouse.click('right')
mouse.right_click()

# Средний клик
mouse.click('middle')
mouse.middle_click()

# Двойной клик
mouse.double_click()

Клики по координатам

# Клик по определенным координатам
mouse.click('left', (300, 400))

# Сохранение позиции перед кликом
original_pos = mouse.get_position()
mouse.click('left', (100, 100))
mouse.move(*original_pos)

Удержание кнопок

# Нажатие и удержание
mouse.press('left')
# Выполнение других действий
mouse.release('left')

# Проверка состояния кнопки
if mouse.is_pressed('left'):
    print("Левая кнопка нажата")

Работа с колесиком прокрутки

Эмуляция прокрутки

# Прокрутка вверх
mouse.wheel(1)

# Прокрутка вниз
mouse.wheel(-1)

# Множественная прокрутка
mouse.wheel(-5)  # Прокрутка на 5 шагов вниз

Горизонтальная прокрутка

# Для систем, поддерживающих горизонтальную прокрутку
mouse.wheel(delta=0, horizontal=True)

Система событий и обработчики

Базовые обработчики

def click_handler(event):
    print(f"Клик: {event.button} в позиции ({event.x}, {event.y})")

# Обработчик всех кликов
mouse.on_click(click_handler)

# Обработчик двойного клика
mouse.on_double_click(lambda e: print("Двойной клик!"))

# Обработчик правого клика
mouse.on_right_click(lambda e: print("Правый клик!"))

Продвинутые обработчики

def button_handler(event):
    if event.event_type == 'down':
        print(f"Нажата кнопка: {event.button}")
    elif event.event_type == 'up':
        print(f"Отпущена кнопка: {event.button}")

# Обработчик нажатий и отпусканий
mouse.on_button(button_handler, buttons=('left', 'right'), types=('down', 'up'))

Глобальные обработчики

def global_handler(event):
    print(f"Событие: {event.event_type}, время: {event.time}")

# Глобальный обработчик всех событий
mouse.hook(global_handler)

# Отключение обработчика
mouse.unhook(global_handler)

# Отключение всех обработчиков
mouse.unhook_all()

Запись и воспроизведение макросов

Запись действий

# Запись до нажатия правой кнопки
print("Начинаю запись. Нажмите правую кнопку для остановки.")
events = mouse.record(button='right')

# Запись с ограничением по времени
import time
import threading

def stop_recording():
    time.sleep(10)  # Запись в течение 10 секунд
    return True

events = mouse.record(button='right')

Воспроизведение макросов

# Воспроизведение с обычной скоростью
mouse.play(events)

# Воспроизведение с измененной скоростью
mouse.play(events, speed_factor=2.0)  # В два раза быстрее
mouse.play(events, speed_factor=0.5)  # В два раза медленнее

# Множественное воспроизведение
for i in range(3):
    mouse.play(events)
    time.sleep(1)

Ожидание событий

Блокирующее ожидание

# Ожидание левого клика
print("Жду левый клик...")
mouse.wait('left')
print("Левый клик произошел!")

# Ожидание конкретного типа события
mouse.wait('right', target_types=('down',))  # Только нажатие
mouse.wait('left', target_types=('up',))     # Только отпускание

Неблокирующее ожидание

import threading

def wait_for_click():
    mouse.wait('left')
    print("Получен клик!")

# Запуск ожидания в отдельном потоке
thread = threading.Thread(target=wait_for_click)
thread.start()

# Основной код продолжает выполняться
print("Программа работает...")

Полная таблица методов и функций

Практические примеры использования

Автоматизация рутинных задач

import mouse
import time

def automate_clicks():
    positions = [(100, 100), (200, 200), (300, 300)]
    
    for pos in positions:
        mouse.move(*pos)
        time.sleep(0.5)
        mouse.click('left')
        time.sleep(0.3)

# Запуск автоматизации через 3 секунды
time.sleep(3)
automate_clicks()

Создание игрового макроса

import mouse
import time

def gaming_macro():
    # Быстрая последовательность кликов
    for _ in range(10):
        mouse.click('left')
        time.sleep(0.1)
    
    # Перемещение и клик
    mouse.move(500, 300)
    mouse.click('right')

# Активация макроса по правому клику
mouse.on_right_click(lambda e: gaming_macro())

Мониторинг активности пользователя

import mouse
import time
from datetime import datetime

click_count = 0
last_activity = time.time()

def activity_monitor(event):
    global click_count, last_activity
    click_count += 1
    last_activity = time.time()
    
    print(f"Клик #{click_count} в {datetime.now().strftime('%H:%M:%S')}")
    print(f"Позиция: ({event.x}, {event.y})")

mouse.on_click(activity_monitor)

# Проверка неактивности
def check_inactivity():
    while True:
        time.sleep(60)  # Проверка каждую минуту
        if time.time() - last_activity > 300:  # 5 минут неактивности
            print("Пользователь неактивен более 5 минут")

import threading
threading.Thread(target=check_inactivity, daemon=True).start()

Интеграция с другими библиотеками

Интеграция с keyboard

import mouse
import keyboard

def mouse_keyboard_combo():
    # Нажать Ctrl и кликнуть
    keyboard.press('ctrl')
    mouse.click('left')
    keyboard.release('ctrl')

# Активация комбинации по горячей клавише
keyboard.add_hotkey('ctrl+shift+m', mouse_keyboard_combo)

Интеграция с PyAutoGUI

import mouse
import pyautogui

def advanced_automation():
    # Скриншот перед действием
    screenshot = pyautogui.screenshot()
    
    # Поиск элемента на экране
    try:
        button_location = pyautogui.locateOnScreen('button.png')
        if button_location:
            center = pyautogui.center(button_location)
            mouse.click('left', center)
    except:
        print("Элемент не найден")

advanced_automation()

Работа с многопоточностью

import mouse
import threading
import time

def background_clicker():
    while True:
        time.sleep(1)
        current_pos = mouse.get_position()
        if current_pos[0] > 1000:  # Если курсор в правой части экрана
            mouse.click('left')

# Запуск в фоновом режиме
clicker_thread = threading.Thread(target=background_clicker, daemon=True)
clicker_thread.start()

# Основная программа продолжает работу
print("Фоновый кликер активен")

Обработка ошибок и отладка

Обработка исключений

import mouse
import time

def safe_mouse_operation():
    try:
        mouse.move(100, 100)
        mouse.click('left')
    except Exception as e:
        print(f"Ошибка выполнения операции: {e}")
    
def safe_event_handler(event):
    try:
        print(f"Обработка события: {event}")
    except Exception as e:
        print(f"Ошибка в обработчике: {e}")

mouse.on_click(safe_event_handler)

Логирование действий

import mouse
import logging
from datetime import datetime

# Настройка логирования
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(message)s')

def log_mouse_events(event):
    logging.info(f"Событие мыши: {event.event_type} - {event.button} в ({event.x}, {event.y})")

mouse.hook(log_mouse_events)

Оптимизация производительности

Минимизация задержек

import mouse
import time

# Быстрые клики без задержек
def fast_clicking():
    for _ in range(100):
        mouse.click('left')
        # Минимальная задержка для стабильности
        time.sleep(0.001)

# Оптимизированное перемещение
def optimized_movement():
    positions = [(100, 100), (200, 200), (300, 300)]
    
    for pos in positions:
        mouse.move(*pos, duration=0.1)  # Быстрое перемещение
        mouse.click('left')

Управление ресурсами

import mouse
import atexit

# Автоматическая очистка при завершении программы
def cleanup():
    mouse.unhook_all()
    print("Все обработчики событий очищены")

atexit.register(cleanup)

Безопасность и ограничения

Защита от бесконечных циклов

import mouse
import time
import keyboard

def emergency_stop():
    print("Аварийная остановка активирована!")
    mouse.unhook_all()
    exit()

# Аварийная остановка по ESC
keyboard.add_hotkey('esc', emergency_stop)

def safe_loop():
    max_iterations = 100
    current_iteration = 0
    
    while current_iteration < max_iterations:
        if keyboard.is_pressed('esc'):
            break
        
        mouse.click('left')
        time.sleep(0.1)
        current_iteration += 1

Контроль доступа

import mouse
import getpass

def check_permissions():
    try:
        # Проверка доступа к управлению мышью
        mouse.get_position()
        return True
    except:
        print("Недостаточно прав для управления мышью")
        return False

if check_permissions():
    print("Доступ к управлению мышью получен")
else:
    print("Запустите программу с правами администратора")

Кроссплатформенная разработка

Учет особенностей операционных систем

import mouse
import platform

def platform_specific_setup():
    system = platform.system()
    
    if system == "Windows":
        # Специфичные настройки для Windows
        print("Настройка для Windows")
    elif system == "Darwin":  # macOS
        print("Настройка для macOS")
        print("Убедитесь, что предоставлен доступ в Accessibility")
    elif system == "Linux":
        print("Настройка для Linux")
        print("Может потребоваться sudo для некоторых операций")

platform_specific_setup()

Сравнение с альтернативными решениями

Часто задаваемые вопросы

Как обеспечить кроссплатформенность моего приложения?

Библиотека mouse автоматически определяет операционную систему и использует соответствующие системные API. Однако следует учитывать различия в требованиях к разрешениям и тестировать код на всех целевых платформах.

Можно ли использовать mouse в многопоточных приложениях?

Да, mouse поддерживает многопоточность. Рекомендуется использовать отдельные потоки для длительных операций и обработчиков событий, чтобы избежать блокировки основного потока.

Как избежать конфликтов с антивирусами?

Некоторые антивирусы могут блокировать программы, использующие mouse. Рекомендуется добавить исключения для вашего приложения или использовать цифровую подпись для исполняемых файлов.

Влияет ли mouse на производительность системы?

При правильном использовании влияние минимально. Избегайте создания слишком частых событий или обработчиков без необходимости. Используйте unhook_all() для очистки ресурсов.

Как тестировать код, использующий mouse?

Рекомендуется создавать тестовые среды с виртуальными экранами или использовать mock-объекты для имитации событий мыши без реального воздействия на систему.

Можно ли записать макрос и сохранить его в файл?

Да, события из mouse.record() можно сериализовать и сохранить в файл с помощью pickle или JSON для последующего воспроизведения.

import pickle
import mouse

# Запись
events = mouse.record()
with open('macro.pkl', 'wb') as f:
    pickle.dump(events, f)

# Воспроизведение
with open('macro.pkl', 'rb') as f:
    events = pickle.load(f)
mouse.play(events)

Заключение

Библиотека mouse представляет собой мощный и универсальный инструмент для программного управления мышью в Python. Благодаря простому и интуитивному API, поддержке событий, возможности записи и воспроизведения макросов, а также кроссплатформенности, она идеально подходит для широкого спектра задач автоматизации.

Основные преимущества библиотеки:

• Минималистичный и понятный API
• Поддержка всех основных операций с мышью
• Система событий для реактивного программирования
• Встроенная поддержка макросов
• Кроссплатформенность
• Активное сообщество и регулярные обновления

Библиотека mouse подходит как для новичков, делающих первые шаги в автоматизации, так и для опытных разработчиков, создающих сложные системы RPA, автотестирования и управления пользовательским интерфейсом.