.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "PYNPUT" "3" "May 26, 2022" "1.7.5" "pynput"
.SH NAME
pynput \- pynput Documentation
.sp
This library allows you to control and monitor input devices.
.sp
It contains subpackages for each type of input device supported:
.INDENT 0.0
.TP
.B \fBpynput.mouse\fP
Contains classes for controlling and monitoring a mouse or trackpad.
.TP
.B \fBpynput.keyboard\fP
Contains classes for controlling and monitoring the keyboard.
.UNINDENT
.sp
All modules mentioned above are automatically imported into the \fBpynput\fP
package. To use any of them, import them from the main package:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from pynput import mouse, keyboard
.ft P
.fi
.UNINDENT
.UNINDENT
.SH FORCING A SPECIFIC BACKEND
.sp
\fIpynput\fP attempts to use the backend suitable for the current platform, but
this automatic choice is possible to override.
.sp
If the environment variables \fB$PYNPUT_BACKEND_KEYBOARD\fP or
\fB$PYNPUT_BACKEND\fP are set, their value will be used as backend name for the
keyboard classes, and if \fB$PYNPUT_BACKEND_MOUSE\fP or \fB$PYNPUT_BACKEND\fP
are set, their value will be used as backend name for the mouse classes.
.sp
Available backends are:
.INDENT 0.0
.IP \(bu 2
\fBdarwin\fP, the default for \fImacOS\fP\&.
.IP \(bu 2
\fBwin32\fP, the default for \fIWindows\fP\&.
.IP \(bu 2
\fBuinput\fP, an optional backend for \fILinux\fP requiring \fIroot\fP privileges and
supporting only keyboards.
.IP \(bu 2
\fBxorg\fP, the default for other operating systems.
.IP \(bu 2
\fBdummy\fP, a non\-functional, but importable, backend. This is useful as
mouse backend when using the \fBuinput\fP backend.
.UNINDENT
.SH TABLE OF CONTENTS
.SS Handling the mouse
.sp
The package \fBpynput.mouse\fP contains classes for controlling and monitoring
the mouse.
.SS Controlling the mouse
.sp
Use \fBpynput.mouse.Controller\fP like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from pynput.mouse import Button, Controller

mouse = Controller()

# Read pointer position
print(\(aqThe current pointer position is {0}\(aq.format(
    mouse.position))

# Set pointer position
mouse.position = (10, 20)
print(\(aqNow we have moved it to {0}\(aq.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
mouse.click(Button.left, 2)

# Scroll two steps down
mouse.scroll(0, 2)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Monitoring the mouse
.sp
Use \fBpynput.mouse.Listener\fP like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from pynput import mouse

def on_move(x, y):
    print(\(aqPointer moved to {0}\(aq.format(
        (x, y)))

def on_click(x, y, button, pressed):
    print(\(aq{0} at {1}\(aq.format(
        \(aqPressed\(aq if pressed else \(aqReleased\(aq,
        (x, y)))
    if not pressed:
        # Stop listener
        return False

def on_scroll(x, y, dx, dy):
    print(\(aqScrolled {0} at {1}\(aq.format(
        \(aqdown\(aq if dy < 0 else \(aqup\(aq,
        (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()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A mouse listener is a \fBthreading.Thread\fP, and all callbacks will be invoked
from the thread.
.sp
Call \fBpynput.mouse.Listener.stop\fP from anywhere, raise \fBStopException\fP or
return \fBFalse\fP from a callback to stop the listener.
.sp
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.
.SS The mouse listener thread
.sp
The listener callbacks are invoked directly from an operating thread on some
platforms, notably \fIWindows\fP\&.
.sp
This means that long running procedures and blocking operations should not be
invoked from the callback, as this risks freezing input for all processes.
.sp
A possible workaround is to just dispatch incoming messages to a queue, and let
a separate thread handle them.
.SS Handling mouse listener errors
.sp
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.
.sp
To be notified about callback errors, call \fBThread.join\fP on the listener
instance:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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(\(aq{0} was clicked\(aq.format(e.args[0]))
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Toggling event listening for the mouse listener
.sp
Once \fBpynput.mouse.Listener.stop\fP has been called, the listener cannot be
restarted, since listeners are instances of \fBthreading.Thread\fP\&.
.sp
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.
.SS Synchronous event listening for the mouse listener
.sp
To simplify scripting, synchronous event listening is supported through the
utility class \fBpynput.mouse.Events\fP\&. This class supports reading single
events in a non\-blocking fashion, as well as iterating over all events.
.sp
To read a single event, use the following code:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from pynput import mouse

# The event listener will be running in this block
with mouse.Events() as events:
    # Block at most one second
    event = events.get(1.0)
    if event is None:
        print(\(aqYou did not interact with the mouse within one second\(aq)
    else:
        print(\(aqReceived event {}\(aq.format(event))
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To iterate over mouse events, use the following code:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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(\(aqReceived event {}\(aq.format(event))
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Please note that the iterator method does not support non\-blocking operation,
so it will wait for at least one mouse event.
.sp
The events will be instances of the inner classes found in
\fBpynput.mouse.Events\fP\&.
.SS Ensuring consistent coordinates between listener and controller on Windows
.sp
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.
.sp
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.
.sp
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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import ctypes


PROCESS_PER_MONITOR_DPI_AWARE = 2

ctypes.windll.shcore.SetProcessDpiAwareness(PROCESS_PER_MONITOR_DPI_AWARE)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Reference
.INDENT 0.0
.TP
.B class  pynput.mouse.Controller
A controller for sending virtual mouse events to the system.
.INDENT 7.0
.TP
.B click(button, count=1)
Emits a button click event at the current position.
.sp
The default implementation sends a series of press and release events.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBbutton\fP (\fIButton\fP) \-\- The button to click.
.IP \(bu 2
\fBcount\fP (\fIint\fP) \-\- The number of clicks to send.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B move(dx, dy)
Moves the mouse pointer a number of pixels from its current
position.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBdx\fP (\fIint\fP) \-\- The horizontal offset.
.IP \(bu 2
\fBdy\fP (\fIint\fP) \-\- The vertical offset.
.UNINDENT
.TP
.B Raises
\fBValueError\fP \-\- if the values are invalid, for example out of
bounds
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B property  position
The current position of the mouse pointer.
.sp
This is the tuple \fB(x, y)\fP, and setting it will move the pointer.
.UNINDENT
.INDENT 7.0
.TP
.B press(button)
Emits a button press event at the current position.
.INDENT 7.0
.TP
.B Parameters
\fBbutton\fP (\fIButton\fP) \-\- The button to press.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B release(button)
Emits a button release event at the current position.
.INDENT 7.0
.TP
.B Parameters
\fBbutton\fP (\fIButton\fP) \-\- The button to release.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B scroll(dx, dy)
Sends scroll events.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBdx\fP (\fIint\fP) \-\- The horizontal scroll. The units of scrolling is
undefined.
.IP \(bu 2
\fBdy\fP (\fIint\fP) \-\- The vertical scroll. The units of scrolling is
undefined.
.UNINDENT
.TP
.B Raises
\fBValueError\fP \-\- if the values are invalid, for example out of
bounds
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class  pynput.mouse.Listener(on_move=None, on_click=None, on_scroll=None, suppress=False, **kwargs)
A listener for mouse events.
.sp
Instances of this class can be used as context managers. This is equivalent
to the following code:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
listener.start()
try:
    listener.wait()
    with_statements()
finally:
    listener.stop()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This class inherits from \fBthreading.Thread\fP and supports all its
methods. It will set \fBdaemon\fP to \fBTrue\fP when created.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBon_move\fP (\fIcallable\fP) \-\- 
.sp
The callback to call when mouse move events occur.
.sp
It will be called with the arguments \fB(x, y)\fP, which is the new
pointer position. If this callback raises \fBStopException\fP or
returns \fBFalse\fP, the listener is stopped.

.IP \(bu 2
\fBon_click\fP (\fIcallable\fP) \-\- 
.sp
The callback to call when a mouse button is
clicked.
.sp
It will be called with the arguments \fB(x, y, button, pressed)\fP,
where \fB(x, y)\fP is the new pointer position, \fBbutton\fP is one of the
\fBButton\fP values and \fBpressed\fP is whether the button was
pressed.
.sp
If this callback raises \fBStopException\fP or returns \fBFalse\fP,
the listener is stopped.

.IP \(bu 2
\fBon_scroll\fP (\fIcallable\fP) \-\- 
.sp
The callback to call when mouse scroll
events occur.
.sp
It will be called with the arguments \fB(x, y, dx, dy)\fP, where
\fB(x, y)\fP is the new pointer position, and \fB(dx, dy)\fP is the scroll
vector.
.sp
If this callback raises \fBStopException\fP or returns \fBFalse\fP,
the listener is stopped.

.IP \(bu 2
\fBsuppress\fP (\fIbool\fP) \-\- Whether to suppress events. Setting this to \fBTrue\fP
will prevent the input events from being passed to the rest of the
system.
.IP \(bu 2
\fBkwargs\fP \-\- 
.sp
Any non\-standard platform dependent options. These should be
prefixed with the platform name thus: \fBdarwin_\fP, \fBxorg_\fP or
\fBwin32_\fP\&.
.sp
Supported values are:
.INDENT 2.0
.TP
.B \fBdarwin_intercept\fP
A callable taking the arguments \fB(event_type, event)\fP, where
\fBevent_type\fP is any mouse related event type constant, and
\fBevent\fP is a \fBCGEventRef\fP\&.
.sp
This callable can freely modify the event using functions like
\fBQuartz.CGEventSetIntegerValueField\fP\&. If this callable does not
return the event, the event is suppressed system wide.
.TP
.B \fBwin32_event_filter\fP
A callable taking the arguments \fB(msg, data)\fP, where \fBmsg\fP is
the current message, and \fBdata\fP associated data as a
\fI\%MSLLHOOKSTRUCT\fP\&.
.sp
If this callback returns \fBFalse\fP, the event will not
be propagated to the listener callback.
.sp
If \fBself.suppress_event()\fP is called, the event is suppressed
system wide.
.UNINDENT

.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B __init__(on_move=None, on_click=None, on_scroll=None, suppress=False, **kwargs)
This constructor should always be called with keyword arguments. Arguments are:
.sp
\fIgroup\fP should be None; reserved for future extension when a ThreadGroup
class is implemented.
.sp
\fItarget\fP is the callable object to be invoked by the run()
method. Defaults to None, meaning nothing is called.
.sp
\fIname\fP is the thread name. By default, a unique name is constructed of
the form "Thread\-N" where N is a small decimal number.
.sp
\fIargs\fP is the argument tuple for the target invocation. Defaults to ().
.sp
\fIkwargs\fP is a dictionary of keyword arguments for the target
invocation. Defaults to {}.
.sp
If a subclass overrides the constructor, it must make sure to invoke
the base class constructor (Thread.__init__()) before doing anything
else to the thread.
.UNINDENT
.INDENT 7.0
.TP
.B property  running
Whether the listener is currently running.
.UNINDENT
.INDENT 7.0
.TP
.B start()
Start the thread\(aqs activity.
.sp
It must be called at most once per thread object. It arranges for the
object\(aqs run() method to be invoked in a separate thread of control.
.sp
This method will raise a RuntimeError if called more than once on the
same thread object.
.UNINDENT
.INDENT 7.0
.TP
.B stop()
Stops listening for events.
.sp
When this method returns, no more events will be delivered. Once this
method has been called, the listener instance cannot be used any more,
since a listener is a \fBthreading.Thread\fP, and once stopped it
cannot be restarted.
.sp
To resume listening for event, a new listener must be created.
.UNINDENT
.INDENT 7.0
.TP
.B wait()
Waits for this listener to become ready.
.UNINDENT
.UNINDENT
.SS Handling the keyboard
.sp
The package \fBpynput.keyboard\fP contains classes for controlling and
monitoring the keyboard.
.SS Controlling the keyboard
.sp
Use \fBpynput.keyboard.Controller\fP like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from pynput.keyboard import Key, Controller

keyboard = Controller()

# Press and release space
keyboard.press(Key.space)
keyboard.release(Key.space)

# Type a lower case A; this will work even if no key on the
# physical keyboard is labelled \(aqA\(aq
keyboard.press(\(aqa\(aq)
keyboard.release(\(aqa\(aq)

# Type two upper case As
keyboard.press(\(aqA\(aq)
keyboard.release(\(aqA\(aq)
with keyboard.pressed(Key.shift):
    keyboard.press(\(aqa\(aq)
    keyboard.release(\(aqa\(aq)

# Type \(aqHello World\(aq using the shortcut type method
keyboard.type(\(aqHello World\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Monitoring the keyboard
.sp
Use \fBpynput.keyboard.Listener\fP like this:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from pynput import keyboard

def on_press(key):
    try:
        print(\(aqalphanumeric key {0} pressed\(aq.format(
            key.char))
    except AttributeError:
        print(\(aqspecial key {0} pressed\(aq.format(
            key))

def on_release(key):
    print(\(aq{0} released\(aq.format(
        key))
    if key == keyboard.Key.esc:
        # Stop listener
        return False

# Collect events until released
with keyboard.Listener(
        on_press=on_press,
        on_release=on_release) as listener:
    listener.join()

# ...or, in a non\-blocking fashion:
listener = keyboard.Listener(
    on_press=on_press,
    on_release=on_release)
listener.start()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A keyboard listener is a \fBthreading.Thread\fP, and all callbacks will be
invoked from the thread.
.sp
Call \fBpynput.keyboard.Listener.stop\fP from anywhere, raise \fBStopException\fP
or return \fBFalse\fP from a callback to stop the listener.
.sp
The \fBkey\fP parameter passed to callbacks is a \fBpynput.keyboard.Key\fP, for
special keys, a \fBpynput.keyboard.KeyCode\fP for normal alphanumeric keys, or
just \fBNone\fP for unknown keys.
.sp
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.
.SS The keyboard listener thread
.sp
The listener callbacks are invoked directly from an operating thread on some
platforms, notably \fIWindows\fP\&.
.sp
This means that long running procedures and blocking operations should not be
invoked from the callback, as this risks freezing input for all processes.
.sp
A possible workaround is to just dispatch incoming messages to a queue, and let
a separate thread handle them.
.SS Handling keyboard listener errors
.sp
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.
.sp
To be notified about callback errors, call \fBThread.join\fP on the listener
instance:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from pynput import keyboard

class MyException(Exception): pass

def on_press(key):
    if key == keyboard.Key.esc:
        raise MyException(key)

# Collect events until released
with keyboard.Listener(
        on_press=on_press) as listener:
    try:
        listener.join()
    except MyException as e:
        print(\(aq{0} was pressed\(aq.format(e.args[0]))
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Toggling event listening for the keyboard listener
.sp
Once \fBpynput.keyboard.Listener.stop\fP has been called, the listener cannot be
restarted, since listeners are instances of \fBthreading.Thread\fP\&.
.sp
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.
.SS Synchronous event listening for the keyboard listener
.sp
To simplify scripting, synchronous event listening is supported through the
utility class \fBpynput.keyboard.Events\fP\&. This class supports reading single
events in a non\-blocking fashion, as well as iterating over all events.
.sp
To read a single event, use the following code:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from pynput import keyboard

# The event listener will be running in this block
with keyboard.Events() as events:
    # Block at most one second
    event = events.get(1.0)
    if event is None:
        print(\(aqYou did not press a key within one second\(aq)
    else:
        print(\(aqReceived event {}\(aq.format(event))
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To iterate over keyboard events, use the following code:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from pynput import keyboard

# The event listener will be running in this block
with keyboard.Events() as events:
    for event in events:
        if event.key == keyboard.Key.esc:
            break
        else:
            print(\(aqReceived event {}\(aq.format(event))
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Please note that the iterator method does not support non\-blocking operation,
so it will wait for at least one keyboard event.
.sp
The events will be instances of the inner classes found in
\fBpynput.keyboard.Events\fP\&.
.SS Global hotkeys
.sp
A common use case for keyboard monitors is reacting to global hotkeys. Since a
listener does not maintain any state, hotkeys involving multiple keys must
store this state somewhere.
.sp
\fIpynput\fP provides the class \fBpynput.keyboard.HotKey\fP for this purpose. It
contains two methods to update the state, designed to be easily interoperable
with a keyboard listener: \fBpynput.keyboard.HotKey.press\fP and
\fBpynput.keyboard.HotKey.release\fP which can be directly passed as listener
callbacks.
.sp
The intended usage is as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from pynput import keyboard

def on_activate():
    print(\(aqGlobal hotkey activated!\(aq)

def for_canonical(f):
    return lambda k: f(l.canonical(k))

hotkey = keyboard.HotKey(
    keyboard.HotKey.parse(\(aq<ctrl>+<alt>+h\(aq),
    on_activate)
with keyboard.Listener(
        on_press=for_canonical(hotkey.press),
        on_release=for_canonical(hotkey.release)) as l:
    l.join()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This will create a hotkey, and then use a listener to update its state. Once
all the specified keys are pressed simultaneously, \fBon_activate\fP will be
invoked.
.sp
Note that keys are passed through \fBpynput.keyboard.Listener.canonical\fP before
being passed to the \fBHotKey\fP instance. This is to remove any modifier state
from the key events, and to normalise modifiers with more than one physical
button.
.sp
The method \fBpynput.keyboard.HotKey.parse\fP is a convenience function to
transform shortcut strings to key collections. Please see its documentation for
more information.
.sp
To register a number of global hotkeys, use the convenience class
\fBpynput.keyboard.GlobalHotKeys\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
from pynput import keyboard

def on_activate_h():
    print(\(aq<ctrl>+<alt>+h pressed\(aq)

def on_activate_i():
    print(\(aq<ctrl>+<alt>+i pressed\(aq)

with keyboard.GlobalHotKeys({
        \(aq<ctrl>+<alt>+h\(aq: on_activate_h,
        \(aq<ctrl>+<alt>+i\(aq: on_activate_i}) as h:
    h.join()
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Reference
.INDENT 0.0
.TP
.B class  pynput.keyboard.Controller
A controller for sending virtual keyboard events to the system.
.INDENT 7.0
.TP
.B exception  InvalidCharacterException
The exception raised when an invalid character is encountered in
the string passed to \fI\%Controller.type()\fP\&.
.sp
Its first argument is the index of the character in the string, and the
second the character.
.UNINDENT
.INDENT 7.0
.TP
.B exception  InvalidKeyException
The exception raised when an invalid \fBkey\fP parameter is passed to
either \fI\%Controller.press()\fP or \fI\%Controller.release()\fP\&.
.sp
Its first argument is the \fBkey\fP parameter.
.UNINDENT
.INDENT 7.0
.TP
.B property  alt_gr_pressed
Whether \fIaltgr\fP is pressed.
.sp
Please note that this reflects only the internal state of this
controller. See \fI\%modifiers\fP for more information.
.UNINDENT
.INDENT 7.0
.TP
.B property  alt_pressed
Whether any \fIalt\fP key is pressed.
.sp
Please note that this reflects only the internal state of this
controller. See \fI\%modifiers\fP for more information.
.UNINDENT
.INDENT 7.0
.TP
.B property  ctrl_pressed
Whether any \fIctrl\fP key is pressed.
.sp
Please note that this reflects only the internal state of this
controller. See \fI\%modifiers\fP for more information.
.UNINDENT
.INDENT 7.0
.TP
.B property  modifiers
The currently pressed modifier keys.
.sp
Please note that this reflects only the internal state of this
controller, and not the state of the operating system keyboard buffer.
This property cannot be used to determine whether a key is physically
pressed.
.sp
Only the generic modifiers will be set; when pressing either
\fI\%Key.shift_l\fP, \fI\%Key.shift_r\fP or \fI\%Key.shift\fP, only
\fI\%Key.shift\fP will be present.
.sp
Use this property within a context block thus:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
with controller.modifiers as modifiers:
    with_block()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This ensures that the modifiers cannot be modified by another thread.
.UNINDENT
.INDENT 7.0
.TP
.B press(key)
Presses a key.
.sp
A key may be either a string of length 1, one of the \fI\%Key\fP
members or a \fI\%KeyCode\fP\&.
.sp
Strings will be transformed to \fI\%KeyCode\fP using
\fBKeyCode.char()\fP\&. Members of \fI\%Key\fP will be translated to
their \fBvalue()\fP\&.
.INDENT 7.0
.TP
.B Parameters
\fBkey\fP \-\- The key to press.
.TP
.B Raises
.INDENT 7.0
.IP \(bu 2
\fI\%InvalidKeyException\fP \-\- if the key is invalid
.IP \(bu 2
\fBValueError\fP \-\- if \fBkey\fP is a string, but its length is not \fB1\fP
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B pressed(*args)
Executes a block with some keys pressed.
.INDENT 7.0
.TP
.B Parameters
\fBkeys\fP \-\- The keys to keep pressed.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B release(key)
Releases a key.
.sp
A key may be either a string of length 1, one of the \fI\%Key\fP
members or a \fI\%KeyCode\fP\&.
.sp
Strings will be transformed to \fI\%KeyCode\fP using
\fBKeyCode.char()\fP\&. Members of \fI\%Key\fP will be translated to
their \fBvalue()\fP\&.
.INDENT 7.0
.TP
.B Parameters
\fBkey\fP \-\- The key to release. If this is a string, it is passed to
\fBtouches()\fP and the returned releases are used.
.TP
.B Raises
.INDENT 7.0
.IP \(bu 2
\fI\%InvalidKeyException\fP \-\- if the key is invalid
.IP \(bu 2
\fBValueError\fP \-\- if \fBkey\fP is a string, but its length is not \fB1\fP
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B property  shift_pressed
Whether any \fIshift\fP key is pressed, or \fIcaps lock\fP is toggled.
.sp
Please note that this reflects only the internal state of this
controller. See \fI\%modifiers\fP for more information.
.UNINDENT
.INDENT 7.0
.TP
.B tap(key)
Presses and releases a key.
.sp
This is equivalent to the following code:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
controller.press(key)
controller.release(key)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B Parameters
\fBkey\fP \-\- The key to press.
.TP
.B Raises
.INDENT 7.0
.IP \(bu 2
\fI\%InvalidKeyException\fP \-\- if the key is invalid
.IP \(bu 2
\fBValueError\fP \-\- if \fBkey\fP is a string, but its length is not \fB1\fP
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B touch(key, is_press)
Calls either \fI\%press()\fP or \fI\%release()\fP depending on the value
of \fBis_press\fP\&.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBkey\fP \-\- The key to press or release.
.IP \(bu 2
\fBis_press\fP (\fIbool\fP) \-\- Whether to press the key.
.UNINDENT
.TP
.B Raises
\fI\%InvalidKeyException\fP \-\- if the key is invalid
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B type(string)
Types a string.
.sp
This method will send all key presses and releases necessary to type
all characters in the string.
.INDENT 7.0
.TP
.B Parameters
\fBstring\fP (\fIstr\fP) \-\- The string to type.
.TP
.B Raises
\fI\%InvalidCharacterException\fP \-\- if an untypable character is
encountered
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class  pynput.keyboard.Listener(on_press=None, on_release=None, suppress=False, **kwargs)
A listener for keyboard events.
.sp
Instances of this class can be used as context managers. This is equivalent
to the following code:
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
listener.start()
try:
    listener.wait()
    with_statements()
finally:
    listener.stop()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This class inherits from \fBthreading.Thread\fP and supports all its
methods. It will set \fBdaemon\fP to \fBTrue\fP when created.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBon_press\fP (\fIcallable\fP) \-\- 
.sp
The callback to call when a button is pressed.
.sp
It will be called with the argument \fB(key)\fP, where \fBkey\fP is a
\fI\%KeyCode\fP, a \fI\%Key\fP or \fBNone\fP if the key is unknown.

.IP \(bu 2
\fBon_release\fP (\fIcallable\fP) \-\- 
.sp
The callback to call when a button is released.
.sp
It will be called with the argument \fB(key)\fP, where \fBkey\fP is a
\fI\%KeyCode\fP, a \fI\%Key\fP or \fBNone\fP if the key is unknown.

.IP \(bu 2
\fBsuppress\fP (\fIbool\fP) \-\- Whether to suppress events. Setting this to \fBTrue\fP
will prevent the input events from being passed to the rest of the
system.
.IP \(bu 2
\fBkwargs\fP \-\- 
.sp
Any non\-standard platform dependent options. These should be
prefixed with the platform name thus: \fBdarwin_\fP, \fBxorg_\fP or
\fBwin32_\fP\&.
.sp
Supported values are:
.INDENT 2.0
.TP
.B \fBdarwin_intercept\fP
A callable taking the arguments \fB(event_type, event)\fP, where
\fBevent_type\fP is \fBQuartz.kCGEventKeyDown\fP or
\fBQuartz.kCGEventKeyDown\fP, and \fBevent\fP is a \fBCGEventRef\fP\&.
.sp
This callable can freely modify the event using functions like
\fBQuartz.CGEventSetIntegerValueField\fP\&. If this callable does not
return the event, the event is suppressed system wide.
.TP
.B \fBwin32_event_filter\fP
A callable taking the arguments \fB(msg, data)\fP, where \fBmsg\fP is
the current message, and \fBdata\fP associated data as a
\fI\%KBDLLHOOKSTRUCT\fP\&.
.sp
If this callback returns \fBFalse\fP, the event will not be
propagated to the listener callback.
.sp
If \fBself.suppress_event()\fP is called, the event is suppressed
system wide.
.UNINDENT

.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B __init__(on_press=None, on_release=None, suppress=False, **kwargs)
This constructor should always be called with keyword arguments. Arguments are:
.sp
\fIgroup\fP should be None; reserved for future extension when a ThreadGroup
class is implemented.
.sp
\fItarget\fP is the callable object to be invoked by the run()
method. Defaults to None, meaning nothing is called.
.sp
\fIname\fP is the thread name. By default, a unique name is constructed of
the form "Thread\-N" where N is a small decimal number.
.sp
\fIargs\fP is the argument tuple for the target invocation. Defaults to ().
.sp
\fIkwargs\fP is a dictionary of keyword arguments for the target
invocation. Defaults to {}.
.sp
If a subclass overrides the constructor, it must make sure to invoke
the base class constructor (Thread.__init__()) before doing anything
else to the thread.
.UNINDENT
.INDENT 7.0
.TP
.B property  running
Whether the listener is currently running.
.UNINDENT
.INDENT 7.0
.TP
.B start()
Start the thread\(aqs activity.
.sp
It must be called at most once per thread object. It arranges for the
object\(aqs run() method to be invoked in a separate thread of control.
.sp
This method will raise a RuntimeError if called more than once on the
same thread object.
.UNINDENT
.INDENT 7.0
.TP
.B stop()
Stops listening for events.
.sp
When this method returns, no more events will be delivered. Once this
method has been called, the listener instance cannot be used any more,
since a listener is a \fBthreading.Thread\fP, and once stopped it
cannot be restarted.
.sp
To resume listening for event, a new listener must be created.
.UNINDENT
.INDENT 7.0
.TP
.B wait()
Waits for this listener to become ready.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class  pynput.keyboard.Key(value)
A class representing various buttons that may not correspond to
letters. This includes modifier keys and function keys.
.sp
The actual values for these items differ between platforms. Some platforms
may have additional buttons, but these are guaranteed to be present
everywhere.
.INDENT 7.0
.TP
.B alt  =  0
A generic Alt key. This is a modifier.
.UNINDENT
.INDENT 7.0
.TP
.B alt_gr  =  0
The AltGr key. This is a modifier.
.UNINDENT
.INDENT 7.0
.TP
.B alt_l  =  0
The left Alt key. This is a modifier.
.UNINDENT
.INDENT 7.0
.TP
.B alt_r  =  0
The right Alt key. This is a modifier.
.UNINDENT
.INDENT 7.0
.TP
.B backspace  =  0
The Backspace key.
.UNINDENT
.INDENT 7.0
.TP
.B caps_lock  =  0
The CapsLock key.
.UNINDENT
.INDENT 7.0
.TP
.B cmd  =  0
A generic command button. On \fIPC\fP platforms, this corresponds to the
Super key or Windows key, and on \fIMac\fP it corresponds to the Command
key. This may be a modifier.
.UNINDENT
.INDENT 7.0
.TP
.B cmd_l  =  0
The left command button. On \fIPC\fP platforms, this corresponds to the
Super key or Windows key, and on \fIMac\fP it corresponds to the Command
key. This may be a modifier.
.UNINDENT
.INDENT 7.0
.TP
.B cmd_r  =  0
The right command button. On \fIPC\fP platforms, this corresponds to the
Super key or Windows key, and on \fIMac\fP it corresponds to the Command
key. This may be a modifier.
.UNINDENT
.INDENT 7.0
.TP
.B ctrl  =  0
A generic Ctrl key. This is a modifier.
.UNINDENT
.INDENT 7.0
.TP
.B ctrl_l  =  0
The left Ctrl key. This is a modifier.
.UNINDENT
.INDENT 7.0
.TP
.B ctrl_r  =  0
The right Ctrl key. This is a modifier.
.UNINDENT
.INDENT 7.0
.TP
.B delete  =  0
The Delete key.
.UNINDENT
.INDENT 7.0
.TP
.B down  =  0
A down arrow key.
.UNINDENT
.INDENT 7.0
.TP
.B end  =  0
The End key.
.UNINDENT
.INDENT 7.0
.TP
.B enter  =  0
The Enter or Return key.
.UNINDENT
.INDENT 7.0
.TP
.B esc  =  0
The Esc key.
.UNINDENT
.INDENT 7.0
.TP
.B f1  =  0
The function keys. F1 to F20 are defined.
.UNINDENT
.INDENT 7.0
.TP
.B home  =  0
The Home key.
.UNINDENT
.INDENT 7.0
.TP
.B insert  =  0
The Insert key. This may be undefined for some platforms.
.UNINDENT
.INDENT 7.0
.TP
.B left  =  0
A left arrow key.
.UNINDENT
.INDENT 7.0
.TP
.B media_next  =  0
The next track button.
.UNINDENT
.INDENT 7.0
.TP
.B media_play_pause  =  0
The play/pause toggle.
.UNINDENT
.INDENT 7.0
.TP
.B media_previous  =  0
The previous track button.
.UNINDENT
.INDENT 7.0
.TP
.B media_volume_down  =  0
The volume down button.
.UNINDENT
.INDENT 7.0
.TP
.B media_volume_mute  =  0
The volume mute button.
.UNINDENT
.INDENT 7.0
.TP
.B media_volume_up  =  0
The volume up button.
.UNINDENT
.INDENT 7.0
.TP
.B menu  =  0
The Menu key. This may be undefined for some platforms.
.UNINDENT
.INDENT 7.0
.TP
.B num_lock  =  0
The NumLock key. This may be undefined for some platforms.
.UNINDENT
.INDENT 7.0
.TP
.B page_down  =  0
The PageDown key.
.UNINDENT
.INDENT 7.0
.TP
.B page_up  =  0
The PageUp key.
.UNINDENT
.INDENT 7.0
.TP
.B pause  =  0
The Pause/Break key. This may be undefined for some platforms.
.UNINDENT
.INDENT 7.0
.TP
.B print_screen  =  0
The PrintScreen key. This may be undefined for some platforms.
.UNINDENT
.INDENT 7.0
.TP
.B right  =  0
A right arrow key.
.UNINDENT
.INDENT 7.0
.TP
.B scroll_lock  =  0
The ScrollLock key. This may be undefined for some platforms.
.UNINDENT
.INDENT 7.0
.TP
.B shift  =  0
A generic Shift key. This is a modifier.
.UNINDENT
.INDENT 7.0
.TP
.B shift_l  =  0
The left Shift key. This is a modifier.
.UNINDENT
.INDENT 7.0
.TP
.B shift_r  =  0
The right Shift key. This is a modifier.
.UNINDENT
.INDENT 7.0
.TP
.B space  =  0
The Space key.
.UNINDENT
.INDENT 7.0
.TP
.B tab  =  0
The Tab key.
.UNINDENT
.INDENT 7.0
.TP
.B up  =  0
An up arrow key.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class  pynput.keyboard.KeyCode(vk=None, char=None, is_dead=False, **kwargs)
A \fI\%KeyCode\fP represents the description of a key code used by the
operating system.
.INDENT 7.0
.TP
.B classmethod  from_char(char, **kwargs)
Creates a key from a character.
.INDENT 7.0
.TP
.B Parameters
\fBchar\fP (\fIstr\fP) \-\- The character.
.TP
.B Returns
a key code
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B classmethod  from_dead(char, **kwargs)
Creates a dead key.
.INDENT 7.0
.TP
.B Parameters
\fBchar\fP \-\- The dead key. This should be the unicode character
representing the stand alone character, such as \fB\(aq~\(aq\fP for
\fICOMBINING TILDE\fP\&.
.TP
.B Returns
a key code
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B classmethod  from_vk(vk, **kwargs)
Creates a key from a virtual key code.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBvk\fP \-\- The virtual key code.
.IP \(bu 2
\fBkwargs\fP \-\- Any other parameters to pass.
.UNINDENT
.TP
.B Returns
a key code
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B join(key)
Applies this dead key to another key and returns the result.
.sp
Joining a dead key with space (\fB\(aq \(aq\fP) or itself yields the non\-dead
version of this key, if one exists; for example,
\fBKeyCode.from_dead(\(aq~\(aq).join(KeyCode.from_char(\(aq \(aq))\fP equals
\fBKeyCode.from_char(\(aq~\(aq)\fP and
\fBKeyCode.from_dead(\(aq~\(aq).join(KeyCode.from_dead(\(aq~\(aq))\fP\&.
.INDENT 7.0
.TP
.B Parameters
\fBkey\fP (\fI\%KeyCode\fP) \-\- The key to join with this key.
.TP
.B Returns
a key code
.TP
.B Raises
\fBValueError\fP \-\- if the keys cannot be joined
.UNINDENT
.UNINDENT
.UNINDENT
.SS Frequently asked question
.SS How do I suppress specific events only?
.sp
Passing the \fBsuppress=True\fP flag to listeners will suppress all events
system\-wide. If this is not what you want, you will have to employ different
solutions for different backends.
.sp
If your backend of choice is not listed below, it does not support suppression
of specific events.
.SS macOS
.sp
For \fImacOS\fP, pass the named argument \fBdarwin_intercept\fP to the listener
constructor. This argument should be a callable taking the arguments
\fB(event_type, event)\fP, where \fBevent_type\fP is any mouse related event type
constant, and \fBevent\fP is a \fI\%CGEventRef\fP\&. The \fBevent\fP argument can be
manipulated by the functions found on the \fI\%Apple documentation\fP\&.
.sp
If the interceptor function determines that the event should be suppressed,
return \fBNone\fP, otherwise return the \fBevent\fP, which you may modify.
.sp
Here is a keyboard example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
def darwin_intercept(event_type, event):
    import Quartz
    length, chars = Quartz.CGEventKeyboardGetUnicodeString(
        event, 100, None, None)
    if length > 0 and chars == \(aqx\(aq:
        # Suppress x
        return None
    elif length > 0 and chars == \(aqa\(aq:
        # Transform a to b
        Quartz.CGEventKeyboardSetUnicodeString(event, 1, \(aqb\(aq)
    else:
        return event
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Windows
.sp
For \fIWindows\fP, pass the argument named \fBwin32_event_filter\fP to the listener
constructor. This argument should be a callable taking the arguments
\fB(msg, data)\fP, where \fBmsg\fP is the current message, and \fBdata\fP associated
data as a \fI\%MSLLHOOKSTRUCT\fP or a \fIKBDLLHOOKSTRUCT\fP, depending on whether you
are creating a mouse or keyboard listener.
.sp
If the filter function determines that the event should be suppressed, call
\fBsuppress_event\fP on the listener. If you return \fBFalse\fP, the event will be
hidden from other listener callbacks.
.sp
Here is a keyboard example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Values for MSLLHOOKSTRUCT.vkCode can be found here:
# https://docs.microsoft.com/en\-us/windows/win32/inputdev/virtual\-key\-codes
def win32_event_filter(msg, data):
    if data.vkCode == 0x58:
        # Suppress x
        listener.suppress_event()
.ft P
.fi
.UNINDENT
.UNINDENT
.SS When using a packager I get an \fBImportError\fP on startup
.sp
This happens when using a packager, such as \fIPyInstaller\fP, to package your
application.
.sp
The reason for the error is that the packager attempts to build a dependency
tree of the modules used by inspecting \fBimport\fP statements, and \fIpynput\fP
finds the platform dependent backend modules at runtime using \fBimportlib\fP\&.
.sp
To solve this problem, please consult the documentation of your tool to find
how to explicitly add modules.
.sp
Which modules to add depends on your distribution platform. The backend modules
are those starting with an underscore (\fB\(aq_\(aq\fP) in the \fBpynput.keyboard\fP and
\fBpynput.mouse\fP packages. Additionally, you will need modules with
corresponding names from the \fBpynput._util\fP package.
.SS Platform limitations
.sp
\fIpynput\fP aims at providing a unified \fIAPI\fP for all supported platforms. In some
cases, however, that is not entirely possible.
.SS Linux
.sp
On \fILinux\fP, \fIpynput\fP uses \fIX\fP, so the following must be true:
.INDENT 0.0
.IP \(bu 2
An \fIX server\fP must be running.
.IP \(bu 2
The environment variable \fB$DISPLAY\fP must be set.
.UNINDENT
.sp
The latter requirement means that running \fIpynput\fP over \fISSH\fP generally will not
work. To work around that, make sure to set \fB$DISPLAY\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ DISPLAY=:0 python \-c \(aqimport pynput\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Please note that the value \fBDISPLAY=:0\fP is just an example. To find the
actual value, please launch a terminal application from your desktop
environment and issue the command \fBecho $DISPLAY\fP\&.
.SS macOS
.sp
Recent versions of \fImacOS\fP restrict monitoring of the keyboard for security
reasons. For that reason, one of the following must be true:
.INDENT 0.0
.IP \(bu 2
The process must run as root.
.IP \(bu 2
Your application must be white listed under \fIEnable access for assistive
devices\fP\&. Note that this might require that you package your application,
since otherwise the entire \fIPython\fP installation must be white listed.
.IP \(bu 2
On versions after \fIMojave\fP, you may also need to whitelist your terminal
application if running your script from a terminal.
.UNINDENT
.sp
Please note that this does not apply to monitoring of the mouse or trackpad.
.sp
All listener classes have the additional attribute \fBIS_TRUSTED\fP, which is
\fBTrue\fP if no permissions are lacking.
.SS Windows
.sp
On \fIWindows\fP, virtual events sent by \fIother\fP processes may not be received.
This library takes precautions, however, to dispatch any virtual events
generated to all currently running listeners of the current process.
.sp
Furthermore, sending key press events will properly propagate to the rest of
the system, but the operating system does not consider the buttons to be truly
\fIpressed\fP\&. This means that key press events will not be continuously emitted as
when holding down a physical key, and certain key sequences, such as \fIshift\fP
pressed while pressing arrow keys, do not work as expected.
.INDENT 0.0
.IP \(bu 2
\fI\%Index\fP
.UNINDENT
.SH AUTHOR
Moses Palmér
.SH COPYRIGHT
2015-2022, Moses Palmér
.\" Generated by docutils manpage writer.
.