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

General utility functions and classes.

class pynput._util.AbstractListener(suppress=False, **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()

Actual implementations of this class must set the attribute _log, which must be an instance of logging.Logger.

Parameters:

• suppress (bool) – Whether to suppress events. Setting this to True will prevent the input events from being passed to the rest of the system.
• 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.

__weakref__

list of weak references to the object (if defined)

_HANDLED_EXCEPTIONS = ()

Exceptions that are handled outside of the emitter and should thus not be passed through the queue

__init__(suppress=False, **kwargs)

This constructor should always be called with keyword arguments. Arguments are:

group should be None; reserved for future extension when a ThreadGroup class is implemented.

target is the callable object to be invoked by the run() method. Defaults to None, meaning nothing is called.

name is the thread name. By default, a unique name is constructed of the form “Thread-N” where N is a small decimal number.

args is the argument tuple for the target invocation. Defaults to ().

kwargs is a dictionary of keyword arguments for the target invocation. Defaults to {}.

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.

classmethod _emitter(f)

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

This decorator will wrap the method and catch exception. If a StopException is caught, the listener will be stopped gracefully. If any other exception is caught, it will be propagated to the thread calling join() and reraised there.

_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.

_run()

The implementation of the run() method.

This is a platform dependent implementation.

_stop_platform()

The implementation of the stop() method.

This is a platform dependent implementation.

join(timeout=None, *args)

Wait until the thread terminates.

This blocks the calling thread until the thread whose join() method is called terminates – either normally or through an unhandled exception or until the optional timeout occurs.

When the timeout argument is present and not None, it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof). As join() always returns None, you must call is_alive() after join() to decide whether a timeout happened – if the thread is still alive, the join() call timed out.

When the timeout argument is not present or None, the operation will block until the thread terminates.

A thread can be join()ed many times.

join() raises a RuntimeError if an attempt is made to join the current thread as that would cause a deadlock. It is also an error to join() a thread before it has been started and attempts to do so raises the same exception.

run()

The thread runner method.

running

Whether the listener is currently running.

stop()

Stops listening for events.

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 threading.Thread, and once stopped it cannot be restarted.

To resume listening for event, a new listener must be created.

suppress

Whether to suppress events.

wait()

Waits for this listener to become ready.

class pynput._util.Events(*args, **kwargs)

A base class to enable iterating over events.

_Listener = None

The listener class providing events.

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

__weakref__

list of weak references to the object (if defined)

_event_mapper(event)

Generates an event callback to transforms the callback arguments to an event and then publishes it.

Parameters:event (callback) – A function generating an event object. Returns:a callback

get(timeout=None)

Attempts to read the next event.

Parameters:timeout (int) – An optional timeout. If this is not provided, this method may block infinitely. Returns:the next event, or None if the source has been stopped or no events were received

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.

pynput._util.RESOLUTIONS = {'darwin': 'Please make sure that you have Python bindings for the system frameworks installed', 'uinput': 'Please make sure that you are running as root, and that the utility dumpkeys is installed', 'xorg': 'Please make sure that you have an X server running, and that the DISPLAY environment variable is set correctly'}

Possible resolutions for import related errors.

pynput._util.backend(package)

Returns the backend module for a package.

Parameters:package (str) – The package for which to load a backend.

pynput._util.prefix(base, cls)

Calculates the prefix to use for platform specific options for a specific class.

The prefix if the name of the module containing the class that is an immediate subclass of base among the super classes of cls.

Mouse Modules

Keyboard Modules