# 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(*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.

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

  property 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)
  __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.

## Mouse Modules

## Keyboard Modules