《每日论文》pynput Package Documentation

pynput Package Documentation

This library allows you to control and monitor input devices.
这个库允许你控制和监控输入设备。
It contains subpackages for each type of input device supported:
它包含支持的每种类型输入设备的子包:
pynput.mouse
Contains classes for controlling and monitoring a mouse or trackpad.
包含用于控制和监视鼠标或触控板的类。
pynput.keyboard
Contains classes for controlling and monitoring the keyboard.
包含用于控制和监视键盘的类。

All modules mentioned above are automatically imported into the pynput package. To use any of them, import them from the main package:
上面提到的所有模块都会自动导入到pynput包中。要使用其中任何一个，请从主包中导入它们:

from pynput import mouse, keyboard

Forcing a specific backend

强制指定后端

pynput attempts to use the backend suitable for the current platform, but this automatic choice is possible to override.
pynput尝试使用适合当前平台的后端，但是这种自动选择是可以覆盖的。

If the environment variables $PYNPUT_BACKEND_KEYBOARD or $PYNPUT_BACKEND are set, their value will be used as backend name for the keyboard classes, and if $PYNPUT_BACKEND_MOUSE or $PYNPUT_BACKEND are set, their value will be used as backend name for the mouse classes.
如果设置了环境变量“ $PYNPUT_BACKEND_KEYBOARD”或“ $PYNPUT_BACKEND”，它们的值将被用作键盘类的后端名，如果设置了“ $PYNPUT_BACKEND_MOUSE”或“ $PYNPUT_BACKEND”，它们的值将被用作鼠标类的后端名。

Available backends are:
可用的后端:

• darwin, the default for macOS. darwin, macOS的默认值。
• win32, the default for Windows. win32, Windows的默认值。
• uinput, an optional backend for Linux requiring root privileges and supporting only keyboards. uinput, Linux的可选后端，需要root权限，只支持键盘。
• xorg, the default for other operating systems. xorg，其他操作系统的默认值。
• dummy, a non-functional, but importable, backend. This is useful as mouse backend when using the uinput backend. dummy，一个无功能但可导入的后端。当使用uinput后端时，这是非常有用的鼠标后端。

Table of contents

本期目录

Handling the mouse

处理鼠标

The package pynput.mouse contains classes for controlling and monitoring the mouse.
包pynput。包含用于控制和监视鼠标的类。

Controlling the mouse

控制鼠标

Use pynput.mouse.Controller like this:
使用pynput.mouse。控制器是这样的:

from pynput.mouse import Button, Controller

mouse = Controller()

# Read pointer position  读指针位置
print('The current pointer position is {0}'.format(
    mouse.position))

# Set pointer position  设置指针的位置
mouse.position = (10, 20)
print('Now we have moved it to {0}'.format(
    mouse.position))

# Move pointer relative to current position  相对于当前位置移动指针
mouse.move(5, -5)

# Press and release  按下和释放
mouse.press(Button.left)
mouse.release(Button.left)

# Double click; this is different from pressing and releasing  双击;这与按压和释放是不同的
# twice on macOS  两次macOS
mouse.click(Button.left, 2)

# Scroll two steps down  向下滚动两步
mouse.scroll(0, 2)

Monitoring the mouse

监视鼠标

Use pynput.mouse.Listener like this:
使用pynput.mouse。侦听器是这样的:

from pynput import mouse

def on_move(x, y):
    print('Pointer moved to {0}'.format(
        (x, y)))

def on_click(x, y, button, pressed):
    print('{0} at {1}'.format(
        'Pressed' if pressed else 'Released',
        (x, y)))
    if not pressed:
        # Stop listener
        return False

def on_scroll(x, y, dx, dy):
    print('Scrolled {0} at {1}'.format(
        'down' if dy < 0 else 'up',
        (x, y)))

# Collect events until released  收集事件直到发布
with mouse.Listener(
        on_move=on_move,
        on_click=on_click,
        on_scroll=on_scroll) as listener:
    listener.join()

# ...or, in a non-blocking fashion:  …或者，以非阻塞的方式:
listener = mouse.Listener(
    on_move=on_move,
    on_click=on_click,
    on_scroll=on_scroll)
listener.start()

A mouse listener is a threading.Thread, and all callbacks will be invoked from the thread.
鼠标监听器是一个线程。线程，所有的回调函数都将从线程中调用。

Call pynput.mouse.Listener.stop from anywhere, raise StopException or return False from a callback to stop the listener.
从任何地方调用pynput.mouse.Listener.stop，引发StopException或从回调函数中返回False以停止侦听器。

When using the non-blocking version above, the current thread will continue executing. This might be necessary when integrating with other GUI frameworks that incorporate a main-loop, but when run from a script, this will cause the program to terminate immediately.
当使用上面的非阻塞版本时，当前线程将继续执行。当与包含主循环的其他GUI框架集成时，这可能是必要的，但当从脚本运行时，这将导致程序立即终止。

The mouse listener thread

鼠标监听线程

The listener callbacks are invoked directly from an operating thread on some platforms, notably Windows.
监听器回调函数在某些平台上直接从操作线程调用，特别是在Windows上。

This means that long running procedures and blocking operations should not be invoked from the callback, as this risks freezing input for all processes.
这意味着不应该从回调调用长时间运行的过程和阻塞操作，因为这可能会冻结所有进程的输入。

A possible workaround is to just dispatch incoming messages to a queue, and let a separate thread handle them.
一种可能的解决方案是只将传入消息分派到队列，并让单独的线程处理它们。

Handling mouse listener errors

处理鼠标侦听器错误

If a callback handler raises an exception, the listener will be stopped. Since callbacks run in a dedicated thread, the exceptions will not automatically be reraised.
如果回调处理程序引发异常，侦听器将停止。由于回调函数运行在专用线程中，因此异常不会被自动重新引发。

To be notified about callback errors, call Thread.join on the listener instance:
要得到回调错误的通知，请调用Thread.join监听器实例:

from pynput import mouse

class MyException(Exception): pass

def on_click(x, y, button, pressed):
    if button == mouse.Button.left:
        raise MyException(button)

# Collect events until released  收集事件直到发布
with mouse.Listener(
        on_click=on_click) as listener:
    try:
        listener.join()
    except MyException as e:
        print('{0} was clicked'.format(e.args[0]))

Toggling event listening for the mouse listener

切换鼠标监听器的事件监听

Once pynput.mouse.Listener.stop has been called, the listener cannot be restarted, since listeners are instances of threading.Thread.
一旦pynput.mouse.Listener.stop被调用，则无法重新启动侦听器，因为侦听器是threading.Thread的实例。

If your application requires toggling listening events, you must either add an internal flag to ignore events when not required, or create a new listener when resuming listening.
如果您的应用程序需要切换监听事件，您必须添加一个内部标志来忽略不需要的事件，或者在恢复监听时创建一个新的监听器。

Synchronous event listening for the mouse listener

监听鼠标监听器的同步事件

To simplify scripting, synchronous event listening is supported through the utility class pynput.mouse.Events. This class supports reading single events in a non-blocking fashion, as well as iterating over all events.
为了简化脚本编写，通过实用程序类pynput.mouse.Events支持同步事件监听。该类支持以非阻塞方式读取单个事件，以及遍历所有事件。

To read a single event, use the following code:
要读取单个事件，使用以下代码:

from pynput import mouse

# The event listener will be running in this block  事件监听器将在此块中运行
with mouse.Events() as events:
    # Block at most one second  最多阻塞1秒
    event = events.get(1.0)
    if event is None:
        print('You did not interact with the mouse within one second')
    else:
        print('Received event {}'.format(event))

To iterate over mouse events, use the following code:
要遍历鼠标事件，使用以下代码:

from pynput import mouse

# The event listener will be running in this block  事件监听器将在此块中运行
with mouse.Events() as events:
    for event in events:
        if event.button == mouse.Button.right:
            break
        else:
            print('Received event {}'.format(event))

Please note that the iterator method does not support non-blocking operation, so it will wait for at least one mouse event.
请注意，迭代器方法不支持非阻塞操作，因此它将等待至少一个鼠标事件。

The events will be instances of the inner classes found in pynput.mouse.Events.
这些事件将是在pynput.mouse.Events中找到的内部类的实例。

Ensuring consistent coordinates between listener and controller on Windows

确保Windows上的侦听器和控制器之间的协调一致

Recent versions of _ Windows _ support running legacy applications scaled when the system scaling has been increased beyond 100%. This allows old applications to scale, albeit with a blurry look, and avoids tiny, unusable user interfaces.
Windows的最新版本支持在系统扩展超过100%时运行遗留应用程序。这允许旧的应用程序扩展，尽管看起来很模糊，并避免了小的，不可用的用户界面。

This scaling is unfortunately inconsistently applied to a mouse listener and a controller: the listener will receive physical coordinates, but the controller has to work with scaled coordinates.
不幸的是，这种缩放不适用于鼠标侦听器和控制器:侦听器将接收物理坐标，但控制器必须使用缩放的坐标。

This can be worked around by telling Windows that your application is DPI aware. This is a process global setting, so _ pynput _ cannot do it automatically. Do enable DPI awareness, run the following code:
这可以通过告诉Windows你的应用程序是DPI感知的来解决。这是一个进程全局设置，所以_ pynput _不能自动执行。启用DPI感知功能，运行以下代码:

import ctypes


PROCESS_PER_MONITOR_DPI_AWARE = 2

ctypes.windll.shcore.SetProcessDpiAwareness(PROCESS_PER_MONITOR_DPI_AWARE)