Private pynput API

This is the internal pynput API. It is used internally by pynput, and its interface is not stable.

This documentation will contain only the modules used on the current platform.

Utility Modules

class pynput._util.AbstractListener(**kwargs)

A class implementing the basic behaviour for event listeners.

Instances of this class can be used as context managers. This is equivalent to the following code:

listener.start()
listener.wait()
try:
    with_statements()
finally:
    listener.stop()

Parameters:kwargs –

A mapping from callback attribute to callback handler. All handlers will be wrapped in a function reading the return value of the callback, and if it is False, raising StopException.

Any callback that is falsy will be ignored.

exception StopException

If an event listener callback raises this exception, the current listener is stopped.

Its first argument must be set to the AbstractListener to stop.

__weakref__

list of weak references to the object (if defined)

classmethod AbstractListener._emitter(f)

A decorator to mark a method as the one emitting the callbacks.

This decorator will wrap the method and catch StopException. If this exception is caught, the listener will be stopped.

AbstractListener._mark_ready()

Marks this listener as ready to receive events.

This method must be called from _run(). wait() will block until this method is called.

AbstractListener._run()

The implementation of the run() method.

This is a platform dependent implementation.

AbstractListener._stop()

The implementation of the stop() method.

This is a platform dependent implementation.

AbstractListener.run()

The thread runner method.

AbstractListener.running

Whether the listener is currently running.

AbstractListener.stop()

Stops listening for mouse events.

When this method returns, no more events will be delivered.

AbstractListener.wait()

Waits for this listener to become ready.

class pynput._util.NotifierMixin

A mixin for notifiers of fake events.

This mixin can be used for controllers on platforms where sending fake events does not cause a listener to receive a notification.

__weakref__

list of weak references to the object (if defined)

classmethod _add_listener(listener)

Adds a listener to the set of running listeners.

Parameters:listener – The listener for fake events.

_emit(action, *args)

Sends a notification to all registered listeners.

This method will ensure that listeners that raise StopException are stopped.

Parameters:

• action (str) – The name of the notification.
• args – The arguments to pass.

classmethod _listeners()

Iterates over the set of running listeners.

This method will quit without acquiring the lock if the set is empty, so there is potential for race conditions. This is an optimisation, since Controller will need to call this method for every control event.

classmethod _receiver(listener_class)

A decorator to make a class able to receive fake events from a controller.

This decorator will add the method _receive to the decorated class.

This method is a context manager which ensures that all calls to _emit() will invoke the named method in the listener instance while the block is active.

classmethod _remove_listener(listener)

Removes this listener from the set of running listeners.

Parameters:listener – The listener for fake events.

class pynput._util.xorg.ListenerMixin

A mixin for X event listeners.

Subclasses should set a value for _EVENTS and implement _handle().

exception _WrappedException

Raised by the handler wrapper when an exception is raised in the handler, or when the listener is stopped to escape the recording.

In the former case, the root exception is passed as the first argument to the constructor, and in the latter case no arguments are passed.

__weakref__

list of weak references to the object (if defined)

ListenerMixin.__weakref__

list of weak references to the object (if defined)

ListenerMixin._handle(display, event)

The device specific callback handler.

This method calls the appropriate callback registered when this listener was created based on the event.

Parameters:

• display – The display being used.
• event – The event.

ListenerMixin._handler(*args, **kwargs)

The callback registered with X for mouse events.

This method will parse the response and call the callbacks registered on initialisation.

Parameters:events – The events passed by X. This is a binary block parsable by _EVENT_PARSER.

ListenerMixin._initialize(display)

Initialises this listener.

This method is called immediately before the event loop, from the handler thread.

Parameters:display – The display being used.

exception pynput._util.xorg.X11Error

An error that is thrown at the end of a code block managed by a display_manager() if an X11 error occurred.

__weakref__

list of weak references to the object (if defined)

pynput._util.xorg._find_mask(display, symbol)

Returns the mode flags to use for a modifier symbol.

Parameters:

• display (Xlib.display.Display) – The X display.
• symbol (str) – The name of the symbol.

Returns:

the modifier mask

pynput._util.xorg.alt_gr_mask(display)

Returns the alt mask flags.

The first time this function is called for a display, the value is cached. Subsequent calls will return the cached value.

Parameters:display (Xlib.display.Display) – The X display. Returns:the modifier mask

pynput._util.xorg.alt_mask(display)

Returns the alt mask flags.

The first time this function is called for a display, the value is cached. Subsequent calls will return the cached value.

Parameters:display (Xlib.display.Display) – The X display. Returns:the modifier mask

pynput._util.xorg.display_manager(*args, **kwds)

Traps X errors and raises an :class:X11Error at the end if any error occurred.

This handler also ensures that the Xlib.display.Display being managed is sync’d.

Parameters:display (Xlib.display.Display) – The X display. Returns:the display Return type:Xlib.display.Display

pynput._util.xorg.index_to_shift(display, index)

Converts an index in a key code list to the corresponding shift state.

Parameters:

• display (Xlib.display.Display) – The display for which to retrieve the shift mask.
• index (int) – The keyboard mapping key code index.

Returns:

a shift mask

pynput._util.xorg.keyboard_mapping(display)

Generates a mapping from keysyms to key codes and required modifier shift states.

Parameters:display (Xlib.display.Display) – The display for which to retrieve the keyboard mapping. Returns:the keyboard mapping

pynput._util.xorg.keysym_group(a, b)

Generates a group from two keysyms.

The implementation of this function comes from:

Within each group, if the second element of the group is NoSymbol, then the group should be treated as if the second element were the same as the first element, except when the first element is an alphabetic KeySym K for which both lowercase and uppercase forms are defined.

In that case, the group should be treated as if the first element were the lowercase form of K and the second element were the uppercase form of K.

This function assumes that alphabetic means latin; this assumption appears to be consistent with observations of the return values from XGetKeyboardMapping.

Parameters:

• a – The first keysym.
• b – The second keysym.

Returns:

a tuple conforming to the description above

pynput._util.xorg.keysym_is_latin_lower(keysym)

Determines whether a keysym is a lower case latin character.

This is true only if XK_a <= keysym <= ` XK_z``.

Parameters:keysym (in) – The keysym to check.

pynput._util.xorg.keysym_is_latin_upper(keysym)

Determines whether a keysym is an upper case latin character.

This is true only if XK_A <= keysym <= ` XK_Z``.

Parameters:keysym (in) – The keysym to check.

pynput._util.xorg.keysym_normalize(keysym)

Normalises a list of keysyms.

The implementation of this function comes from:

If the list (ignoring trailing NoSymbol entries) is a single KeySym K, then the list is treated as if it were the list K NoSymbol K NoSymbol.

If the list (ignoring trailing NoSymbol entries) is a pair of KeySyms K1 K2, then the list is treated as if it were the list K1 K2 K1 K2.

If the list (ignoring trailing NoSymbol entries) is a triple of KeySyms K1 K2 K3, then the list is treated as if it were the list K1 K2 K3 NoSymbol.

This function will also group the keysyms using keysym_group().

Parameters:keysyms – A list of keysyms. Returns:the tuple (group_1, group_2) or None

pynput._util.xorg.shift_to_index(display, shift)

Converts an index in a key code list to the corresponding shift state.

Parameters:

• display (Xlib.display.Display) – The display for which to retrieve the shift mask.
• index (int) – The keyboard mapping key code index.

Retur:

a shift mask

pynput._util.xorg.symbol_to_keysym(symbol)

Converts a symbol name to a keysym.

Parameters:symbol (str) – The name of the symbol. Returns:the corresponding keysym, or 0 if it cannot be found

Mouse Modules

Keyboard Modules