Pynput

https://pynput.readthedocs.io/en/latest/
Admin
Pynput is a Python library that enables control and monitoring of input devices, specifically the...
Tokens:52,092
Snippets:443
Trust Score:9.6
Update:3 days ago
Show doc for...
Tokens:
Raw
### pynput.keyboard.Listener.start()

Source: https://pynput.readthedocs.io/en/latest/genindex.html

Starts the keyboard listener. This method is part of the pynput.keyboard.Listener class.

```APIDOC
## pynput.keyboard.Listener.start()

### Description
Starts the keyboard listener.

### Method
start

### Class
pynput.keyboard.Listener
```

--------------------------------

### pynput.mouse.Listener.start()

Source: https://pynput.readthedocs.io/en/latest/genindex.html

Starts the mouse listener. This method is part of the pynput.mouse.Listener class.

```APIDOC
## pynput.mouse.Listener.start()

### Description
Starts the mouse listener.

### Method
start

### Class
pynput.mouse.Listener
```

--------------------------------

### Thread _bootstrap_inner method

Source: https://pynput.readthedocs.io/en/latest/_modules/threading.html

Performs the internal setup for a new thread, including setting identifiers, locks, and trace/profile hooks.

```python
def _bootstrap_inner(self):
    try:
        self._set_ident()
        self._set_tstate_lock()
        self._started.set()
        with _active_limbo_lock:
            _active[self._ident] = self
            del _limbo[self]

        if _trace_hook:
            _sys.settrace(_trace_hook)
        if _profile_hook:
            _sys.setprofile(_profile_hook)
```

--------------------------------

### Thread start method

Source: https://pynput.readthedocs.io/en/latest/_modules/threading.html

Starts the thread's activity by invoking the run() method in a separate thread. Raises RuntimeError if called more than once.

```python
def start(self):
    """Start the thread's activity.

    It must be called at most once per thread object. It arranges for the
    object's run() method to be invoked in a separate thread of control.

    This method will raise a RuntimeError if called more than once on the
    same thread object.

    """
    if not self._initialized:
        raise RuntimeError("thread.__init__() not called")

    if self._started.is_set():
        raise RuntimeError("threads can only be started once")
    with _active_limbo_lock:
        _limbo[self] = self
    try:
        _start_new_thread(self._bootstrap, ())
    except Exception:
        with _active_limbo_lock:
            del _limbo[self]
        raise
    self._started.wait()
```

--------------------------------

### Threading Module Initialization

Source: https://pynput.readthedocs.io/en/latest/_modules/threading.html

Initial setup of the threading module, including imports and the definition of the public API.

```python
"""Thread module emulating a subset of Java's threading model."""

import os as _os
import sys as _sys
import _thread

from time import monotonic as _time
from traceback import format_exc as _format_exc
from _weakrefset import WeakSet
from itertools import islice as _islice, count as _count
try:
    from _collections import deque as _deque
except ImportError:
    from collections import deque as _deque

# Note regarding PEP 8 compliant names
#  This threading model was originally inspired by Java, and inherited
# the convention of camelCase function and method names from that
# language. Those original names are not in any imminent danger of
# being deprecated (even for Py3k),so this module provides them as an
# alias for the PEP 8 compliant names
# Note that using the new PEP 8 compliant names facilitates substitution
# with the multiprocessing module, which doesn't provide the old
# Java inspired names.

__all__ = ['get_ident', 'active_count', 'Condition', 'current_thread',
           'enumerate', 'main_thread', 'TIMEOUT_MAX',
           'Event', 'Lock', 'RLock', 'Semaphore', 'BoundedSemaphore', 'Thread',
           'Barrier', 'BrokenBarrierError', 'Timer', 'ThreadError',
           'setprofile', 'settrace', 'local', 'stack_size']

# Rename some stuff so "from threading import *" is safe
_start_new_thread = _thread.start_new_thread
_allocate_lock = _thread.allocate_lock
_set_sentinel = _thread._set_sentinel
get_ident = _thread.get_ident
ThreadError = _thread.error
try:
    _CRLock = _thread.RLock
except AttributeError:
    _CRLock = None
TIMEOUT_MAX = _thread.TIMEOUT_MAX
del _thread
```

--------------------------------

### Timer class usage

Source: https://pynput.readthedocs.io/en/latest/_modules/threading.html

Example of using the Timer class to execute a function after a delay.

```python
            t = Timer(30.0, f, args=None, kwargs=None)
            t.start()
            t.cancel()     # stop the timer's action if it's still waiting
```

--------------------------------

### AbstractListener context manager methods

Source: https://pynput.readthedocs.io/en/latest/_modules/pynput/_util.html

Enables the use of the listener with the 'with' statement to automatically start and stop the listener.

```python
def __enter__(self):
    self.start()
    self.wait()
    return self

def __exit__(self, exc_type, value, traceback):
    self.stop()
```

--------------------------------

### Listener context manager equivalent code

Source: https://pynput.readthedocs.io/en/latest/mouse.html

Shows the equivalent code for using a Listener as a context manager: start the listener, wait, execute the with-statements, and stop the listener in a finally block.

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

--------------------------------

### Listener.start()

Source: https://pynput.readthedocs.io/en/latest/mouse.html

Starts the listener thread's activity. It must be called at most once per listener instance and arranges for the run() method to be invoked in a separate thread. Raises RuntimeError if called more than once.

```APIDOC
## Listener.start()

### Description
Starts the thread's activity. It must be called at most once per thread object. It arranges for the object's run() method to be invoked in a separate thread of control. This method will raise a RuntimeError if called more than once on the same thread object.

### Method
start

### Parameters
None

### Return Value
None

### Exceptions
- RuntimeError - If called more than once on the same thread object.
```

--------------------------------

### pynput.keyboard.Listener.start

Source: https://pynput.readthedocs.io/en/latest/keyboard.html

Starts the thread's activity. It arranges for the object's run() method to be invoked in a separate thread of control.

```APIDOC
## pynput.keyboard.Listener.start

### Description
Start the thread's activity. It must be called at most once per thread object. It arranges for the object's run() method to be invoked in a separate thread of control.

### Raises
- **RuntimeError** - If called more than once on the same thread object.
```

--------------------------------

### Basic mouse listener with on_move, on_click, on_scroll

Source: https://pynput.readthedocs.io/en/latest/mouse.html

Creates a pynput.mouse.Listener that prints pointer movement, click press/release, and scroll events. The blocking version uses a context manager and join(), while the non-blocking version calls start() and lets the current thread continue. Returning False from on_click stops the listener.

```python
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()
```

--------------------------------

### pynput._util.AbstractListener.run()

Source: https://pynput.readthedocs.io/en/latest/genindex.html

Runs the listener loop. This method is part of the abstract listener class and is used to start listening for events.

```APIDOC
## pynput._util.AbstractListener.run()

### Description
Runs the listener loop. This method is part of the abstract listener class and is used to start listening for events.

### Method
run

### Parameters
None

### Returns
None
```

--------------------------------

### Listener class

Source: https://pynput.readthedocs.io/en/latest/keyboard.html

A listener for keyboard events. Instances can be used as context managers, equivalent to start(), wait(), and stop() in a try/finally block.

```APIDOC
## Listener(on_press=None, on_release=None, suppress=False, **kwargs)

### Description
A listener for keyboard events. Instances of this class can be used as context managers. This is equivalent to the following code:

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

### Parameters
- **on_press** - Callback for press events.
- **on_release** - Callback for release events.
- **suppress** - Whether to suppress events.
- **kwargs** - Additional keyword arguments.
```

--------------------------------

### Listener.__init__

Source: https://pynput.readthedocs.io/en/latest/_modules/pynput/keyboard/_base.html

Initializes a keyboard listener with callbacks for key press and release events, and options for event suppression and platform-specific configuration.

```APIDOC
## Listener.__init__

### Description
Initializes a keyboard listener. The listener can be used as a context manager, equivalent to calling start(), wait(), and stop(). It inherits from threading.Thread and sets daemon to True.

### Method
Constructor

### Signature
Listener(on_press=None, on_release=None, suppress=False, **kwargs)

### Parameters
- **on_press** (callable) - Optional - The callback to call when a button is pressed. It will be called with the argument (key), where key is a KeyCode, a Key, or None if the key is unknown.
- **on_release** (callable) - Optional - The callback to call when a button is released. It will be called with the argument (key), where key is a KeyCode, a Key, or None if the key is unknown.
- **suppress** (bool) - Optional - Whether to suppress events. Setting this to True will prevent the input events from being passed to the rest of the system.
- **kwargs** - Optional - Any non-standard platform dependent options. These should be prefixed with the platform name: darwin_, uinput_, xorg_, or win32_. Supported values include:
  - darwin_intercept: A callable taking the arguments (event_type, event), where event_type is Quartz.kCGEventKeyDown or Quartz.kCGEventKeyUp, and event is a CGEventRef. This callable can freely modify the event. If it does not return the event, the event is suppressed system wide.
  - uinput_device_paths: A list of device paths. If specified, pynput will limit the number of devices checked for the capabilities needed to those passed, otherwise all system devices will be used.
  - win32_event_filter: A callable taking the arguments (msg, data), where msg is the current message, and data is associated data as a KBDLLHOOKSTRUCT. If this callback returns False, the event will not be propagated to the listener callback. If self.suppress_event() is called, the event is suppressed system wide.

### Usage Example
listener = Listener(on_press=on_press, on_release=on_release, suppress=False)
listener.start()
try:
    listener.wait()
    with_statements()
finally:
    listener.stop()
```

--------------------------------

### pynput.mouse.Listener

Source: https://pynput.readthedocs.io/en/latest/_sources/mouse.rst.txt

The Listener class monitors mouse events and allows starting and stopping the monitoring thread. It provides methods to start, stop, and wait for the listener.

```APIDOC
## pynput.mouse.Listener

### Description
Monitors mouse events and provides methods to start, stop, and wait for the listener.

### Constructor
- **__init__(on_move=None, on_click=None, on_scroll=None)** - Initialize the listener with optional callbacks for mouse events.

### Properties
- **running** - Whether the listener is currently running.

### Methods
- **start()** - Start the listener thread.
- **stop()** - Stop the listener thread.
- **wait()** - Wait for the listener to finish.
```

--------------------------------

### Control the mouse with pynput.mouse.Controller

Source: https://pynput.readthedocs.io/en/latest/mouse.html

Demonstrates how to instantiate the mouse controller to read and set the pointer position, perform relative movements, simulate button presses, clicks, and scrolling.

```python
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
mouse.click(Button.left, 2)

# Scroll two steps down
mouse.scroll(0, 2)
```

--------------------------------

### Controller.tap Method

Source: https://pynput.readthedocs.io/en/latest/_modules/pynput/keyboard/_base.html

Simulates a full key press and release cycle.

```python
def tap(self, key):
    """Presses and releases a key.

    This is equivalent to the following code::

        controller.press(key)
        controller.release(key)

    :param key: The key to press.

    :raises InvalidKeyException: if the key is invalid

    :raises ValueError: if ``key`` is a string, but its length is not ``1``
    """
    self.press(key)
    self.release(key)
```

--------------------------------

### pynput.keyboard.Listener

Source: https://pynput.readthedocs.io/en/latest/_sources/keyboard.rst.txt

The Listener class monitors keyboard events and allows starting and stopping the listener.

```APIDOC
## pynput.keyboard.Listener

### Description
Listener for keyboard events. Can be started and stopped, and provides a running property.

### Methods
- **start()** - Start the listener.
- **stop()** - Stop the listener.
- **wait()** - Wait for the listener to finish.

### Properties
- **running** (bool) - Whether the listener is currently running.

### Usage Example
```python
from pynput.keyboard import Listener

listener = Listener()
listener.start()
# ...
listener.stop()
```
```

--------------------------------

### Thread identifier property

Source: https://pynput.readthedocs.io/en/latest/_modules/threading.html

Returns the nonzero integer identifier of the thread, or None if not started.

```python
    @property
    def ident(self):
        """Thread identifier of this thread or None if it has not been started.

        This is a nonzero integer. See the get_ident() function. Thread
        identifiers may be recycled when a thread exits and another thread is
        created. The identifier is available even after the thread has exited.

        """
        assert self._initialized, "Thread.__init__() not called"
        return self._ident
```

--------------------------------

### pynput.keyboard.Listener.__init__

Source: https://pynput.readthedocs.io/en/latest/keyboard.html

Constructor for the Listener class. Should be called with keyword arguments. Accepts callbacks for key press and release events, a suppress flag, and platform-specific options.

```APIDOC
## pynput.keyboard.Listener.__init__

### Description
Initializes a new keyboard listener. This constructor should always be called with keyword arguments. It sets the daemon attribute to True.

### Parameters
- **on_press** (callable) - Optional - The callback to call when a button is pressed. It will be called with the argument (key), where key is a KeyCode, a Key, or None if the key is unknown.
- **on_release** (callable) - Optional - The callback to call when a button is released. It will be called with the argument (key), where key is a KeyCode, a Key, or None if the key is unknown.
- **suppress** (bool) - Optional - Whether to suppress events. Setting this to True will prevent the input events from being passed to the rest of the system.
- **kwargs** - Optional - Any non-standard platform dependent options. These should be prefixed with the platform name: darwin_, uinput_, xorg_, or win32_. Supported values include:
  - **darwin_intercept** (callable) - A callable taking the arguments (event_type, event), where event_type is Quartz.kCGEventKeyDown or Quartz.kCGEventKeyUp, and event is a CGEventRef. This callable can freely modify the event. If it does not return the event, the event is suppressed system wide.
  - **uinput_device_paths** (list) - A list of device paths. If specified, pynput will limit the number of devices checked for capabilities to those passed. Passing this might be required if an incorrect device is chosen.
  - **win32_event_filter** (callable) - A callable taking the arguments (msg, data), where msg is the current message, and data is associated data as a KBDLLHOOKSTRUCT. If this callback returns False, the event will not be propagated to the listener callback. If self.suppress_event() is called, the event is suppressed system wide.

### Notes
- The constructor also accepts standard threading.Thread arguments: group, target, name, args, and kwargs. group should be None; target is the callable object to be invoked by run(); name is the thread name; args is the argument tuple for the target invocation; kwargs is a dictionary of keyword arguments for the target invocation.
- If a subclass overrides the constructor, it must invoke the base class constructor (Thread.__init__()) before doing anything else.
```

--------------------------------

### Control the keyboard with pynput.keyboard.Controller

Source: https://pynput.readthedocs.io/en/latest/keyboard.html

Demonstrates how to press, release, and type keys using the Controller class.

```python
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 'A'
keyboard.press('a')
keyboard.release('a')

# Type two upper case As
keyboard.press('A')
keyboard.release('A')
with keyboard.pressed(Key.shift):
    keyboard.press('a')
    keyboard.release('a')

# Type 'Hello World' using the shortcut type method
keyboard.type('Hello World')
```

--------------------------------

### Main Thread Accessor

Source: https://pynput.readthedocs.io/en/latest/_modules/threading.html

Returns the main thread object, which is the thread from which the Python interpreter was started.

```python
def main_thread():
    """Return the main thread object.

    In normal conditions, the main thread is the thread from which the
    Python interpreter was started.
    """
    return _main_thread
```

--------------------------------

### Listener.__init__

Source: https://pynput.readthedocs.io/en/latest/_modules/pynput/mouse/_base.html

Initializes a new mouse listener with optional callbacks for move, click, and scroll events, and a suppress flag.

```APIDOC
## Listener.__init__

### Description
Initializes a new mouse listener with optional callbacks for move, click, and scroll events, and a suppress flag.

### Method
Constructor

### Signature
Listener(on_move=None, on_click=None, on_scroll=None, suppress=False, **kwargs)

### Parameters
- **on_move** (callable) - Optional - Callback for mouse move events. Called with (x, y). If raises StopException or returns False, listener stops.
- **on_click** (callable) - Optional - Callback for mouse click events. Called with (x, y, button, pressed). If raises StopException or returns False, listener stops.
- **on_scroll** (callable) - Optional - Callback for mouse scroll events. Called with (x, y, dx, dy). If raises StopException or returns False, listener stops.
- **suppress** (bool) - Optional - Whether to suppress events system-wide.
- **kwargs** - Optional - Platform-specific options prefixed with platform name (e.g., darwin_, xorg_, win32_). Supported values: darwin_intercept, win32_event_filter.

### Notes
- The Listener class inherits from threading.Thread and can be used as a context manager.
- When used as a context manager, it starts the listener, waits, and stops it.
- The daemon attribute is set to True when created.

```

--------------------------------

### Thread daemon property accessors

Source: https://pynput.readthedocs.io/en/latest/_modules/threading.html

Manages the daemon status of a thread. Must be set before start() is called.

```python
    @property
    def daemon(self):
        """A boolean value indicating whether this thread is a daemon thread.

        This must be set before start() is called, otherwise RuntimeError is
        raised. Its initial value is inherited from the creating thread; the
        main thread is not a daemon thread and therefore all threads created in
        the main thread default to daemon = False.

        The entire Python program exits when only daemon threads are left.

        """
        assert self._initialized, "Thread.__init__() not called"
        return self._daemonic

    @daemon.setter
    def daemon(self, daemonic):
        if not self._initialized:
            raise RuntimeError("Thread.__init__() not called")
        if self._started.is_set():
            raise RuntimeError("cannot set daemon status of active thread")
        self._daemonic = daemonic
```

--------------------------------

### Monitor keyboard events with pynput.keyboard.Listener

Source: https://pynput.readthedocs.io/en/latest/keyboard.html

Shows how to set up blocking and non-blocking keyboard listeners to capture press and release events.

```python
from pynput import keyboard

def on_press(key):
    try:
        print('alphanumeric key {0} pressed'.format(
            key.char))
    except AttributeError:
        print('special key {0} pressed'.format(
            key))

def on_release(key):
    print('{0} released'.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()
```

--------------------------------

### Controller.scroll(dx, dy)

Source: https://pynput.readthedocs.io/en/latest/mouse.html

Sends scroll events. Raises ValueError if the values are invalid, for example out of bounds.

```APIDOC
## Controller.scroll(dx, dy)

### Description
Sends scroll events. Raises ValueError if the values are invalid, for example out of bounds.

### Method
scroll

### Parameters
- **dx** (int) - Required - The horizontal scroll. The units of scrolling is undefined.
- **dy** (int) - Required - The vertical scroll. The units of scrolling is undefined.

### Raises
- **ValueError** - if the values are invalid, for example out of bounds.

### Returns
None
```

--------------------------------

### AbstractListener context manager usage

Source: https://pynput.readthedocs.io/en/latest/private.html

Demonstrates the equivalent behavior of using an AbstractListener instance as a context manager.

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

--------------------------------

### Listener Initialization

Source: https://pynput.readthedocs.io/en/latest/_modules/pynput/keyboard/_base.html

The constructor for the keyboard listener, handling callbacks, event suppression, and platform-specific keyword arguments.

```python
def __init__(self, on_press=None, on_release=None, suppress=False,
             **kwargs):
    self._log = _logger(self.__class__)
    option_prefix = prefix(Listener, self.__class__)
    self._options = {
        key[len(option_prefix):]: value
        for key, value in kwargs.items()
        if key.startswith(option_prefix)}
    super(Listener, self).__init__(
        on_press=on_press, on_release=on_release, suppress=suppress)
```

--------------------------------

### Controller.release Method

Source: https://pynput.readthedocs.io/en/latest/_modules/pynput/keyboard/_base.html

Simulates releasing a key.

```python
def release(self, key):
    """Releases a key.

    A key may be either a string of length 1, one of the :class:`Key`
    members or a :class:`KeyCode`.

    Strings will be transformed to :class:`KeyCode` using
    :meth:`KeyCode.char`. Members of :class:`Key` will be translated to
    their :meth:`~Key.value`.

    :param key: The key to release. If this is a string, it is passed to
        :meth:`touches` and the returned releases are used.

    :raises InvalidKeyException: if the key is invalid

    :raises ValueError: if ``key`` is a string, but its length is not ``1``
    """
    resolved = self._resolve(key)
    if resolved is None:
        raise self.InvalidKeyException(key)
    self._update_modifiers(resolved, False)

    # Ignore released dead keys
    if resolved.is_dead:
        return

    self._handle(resolved, False)
```

--------------------------------

### Controller.position

Source: https://pynput.readthedocs.io/en/latest/_modules/pynput/mouse/_base.html

Gets or sets the current position of the mouse pointer as a tuple (x, y). Setting this property moves the pointer.

```APIDOC
## Controller.position

### Description
Gets or sets the current position of the mouse pointer. The position is a tuple (x, y). Setting this property moves the pointer.

### Property
- **type**: tuple (x, y)
- **getter**: Returns the current position
- **setter**: Moves the pointer to the given position
```

--------------------------------

### Register multiple global hotkeys with GlobalHotKeys

Source: https://pynput.readthedocs.io/en/latest/keyboard.html

Uses the GlobalHotKeys convenience class to register multiple shortcut strings and their corresponding activation callbacks.

```python
from pynput import keyboard

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

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

with keyboard.GlobalHotKeys({
        '<ctrl>+<alt>+h': on_activate_h,
        '<ctrl>+<alt>+i': on_activate_i}) as h:
    h.join()
```

--------------------------------

### Controller.press Method

Source: https://pynput.readthedocs.io/en/latest/_modules/pynput/keyboard/_base.html

Simulates pressing a key, handling modifiers, caps lock state, and dead keys.

```python
def press(self, key):
    """Presses a key.

    A key may be either a string of length 1, one of the :class:`Key`
    members or a :class:`KeyCode`.

    Strings will be transformed to :class:`KeyCode` using
    :meth:`KeyCode.char`. Members of :class:`Key` will be translated to
    their :meth:`~Key.value`.

    :param key: The key to press.

    :raises InvalidKeyException: if the key is invalid

    :raises ValueError: if ``key`` is a string, but its length is not ``1``
    """
    resolved = self._resolve(key)
    if resolved is None:
        raise self.InvalidKeyException(key)
    self._update_modifiers(resolved, True)

    # Update caps lock state
    if resolved == self._Key.caps_lock.value:
        self._caps_lock = not self._caps_lock

    # If we currently have a dead key pressed, join it with this key
    original = resolved
    if self._dead_key:
        try:
            resolved = self._dead_key.join(resolved)
        except ValueError:
            self._handle(self._dead_key, True)
            self._handle(self._dead_key, False)

    # If the key is a dead key, keep it for later
    if resolved.is_dead:
        self._dead_key = resolved
        return

    try:
        self._handle(resolved, True)
    except self.InvalidKeyException:
        if resolved != original:
            self._handle(self._dead_key, True)
            self._handle(self._dead_key, False)
            self._handle(original, True)

    self._dead_key = None
```

--------------------------------

### Thread join method implementation

Source: https://pynput.readthedocs.io/en/latest/_modules/threading.html

Handles blocking until a thread terminates, including error checks for initialization, start status, and deadlock prevention.

```python
        if not self._initialized:
            raise RuntimeError("Thread.__init__() not called")
        if not self._started.is_set():
            raise RuntimeError("cannot join thread before it is started")
        if self is current_thread():
            raise RuntimeError("cannot join current thread")

        if timeout is None:
            self._wait_for_tstate_lock()
        else:
            # the behavior of a negative timeout isn't documented, but
            # historically .join(timeout=x) for x<0 has acted as if timeout=0
            self._wait_for_tstate_lock(timeout=max(timeout, 0))
```

--------------------------------

### KeyCode.join

Source: https://pynput.readthedocs.io/en/latest/keyboard.html

Instance method that applies this dead key to another key and returns the result. Joining with space or itself yields the non-dead version if one exists.

```APIDOC
## KeyCode.join

### Description
Applies this dead key to another key and returns the result.

### Method
instance

### Parameters
- **key** (KeyCode) - Required - The key to join with this key.

### Returns
- a key code

### Raises
- **ValueError** - if the keys cannot be joined
```

--------------------------------

### Events class initialization and lifecycle

Source: https://pynput.readthedocs.io/en/latest/_modules/pynput/_util.html

The Events class manages an event queue and listener lifecycle. It implements context manager methods for automatic setup and teardown.

```python
    def __init__(self, *args, **kwargs):
        super(Events, self).__init__()
        self._event_queue = queue.Queue()
        self._sentinel = object()
        self._listener = self._Listener(*args, **{
            key: self._event_mapper(value)
            for (key, value) in kwargs.items()})
        self.start = self._listener.start


    def __enter__(self):
        self._listener.__enter__()
        return self

    def __exit__(self, *args):
        self._listener.__exit__(*args)

        # Drain the queue to ensure that the put does not block
        while True:
            try:
                self._event_queue.get_nowait()
            except queue.Empty:
                break

        self._event_queue.put(self._sentinel)

    def __iter__(self):
        return self

    def __next__(self):
        event = self.get()
        if event is not None:
            return event
        else:
            raise StopIteration()
```

--------------------------------

### pynput.keyboard.KeyCode.from_vk()

Source: https://pynput.readthedocs.io/en/latest/genindex.html

Class method to create a KeyCode from a virtual key code.

```APIDOC
## pynput.keyboard.KeyCode.from_vk()

### Description
Class method to create a KeyCode from a virtual key code.

### Method
from_vk

### Class
pynput.keyboard.KeyCode
```

--------------------------------

### Reading a single mouse event with pynput.mouse.Events

Source: https://pynput.readthedocs.io/en/latest/mouse.html

Uses pynput.mouse.Events to read a single mouse event in a non-blocking way. The get(1.0) call blocks for at most one second and returns None if no event occurs, printing a message accordingly.

```python
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('You did not interact with the mouse within one second')
    else:
        print('Received event {}'.format(event))
```

--------------------------------

### KeyCode.join Method

Source: https://pynput.readthedocs.io/en/latest/_modules/pynput/keyboard/_base.html

Applies a dead key to another key to produce a combined character.

```python
def join(self, key):
    """Applies this dead key to another key and returns the result.

    Joining a dead key with space (``' '``) or itself yields the non-dead
    version of this key, if one exists; for example,
    ``KeyCode.from_dead('~').join(KeyCode.from_char(' '))`` equals
    ``KeyCode.from_char('~')`` and
    ``KeyCode.from_dead('~').join(KeyCode.from_dead('~'))``.

    :param KeyCode key: The key to join with this key.

    :return: a key code

    :raises ValueError: if the keys cannot be joined
    """
    # A non-dead key cannot be joined
    if not self.is_dead:
        raise ValueError(self)

    # Joining two of the same keycodes, or joining with space, yields the
    # non-dead version of the key
    if key.char == ' ' or self == key:
        return self.from_char(self.char)

    # Otherwise we combine the characters
    if key.char is not None:
        combined = unicodedata.normalize(
            'NFC',
            key.char + self.combining)
        if combined:
            return self.from_char(combined)

    raise ValueError(key)
```

--------------------------------

### Handling mouse listener errors with custom exception

Source: https://pynput.readthedocs.io/en/latest/mouse.html

Shows how to catch exceptions raised in a mouse listener callback. The listener stops when a callback raises an exception, and the exception is re-raised when join() is called. This example raises MyException when the left button is clicked.

```python
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]))
```

--------------------------------

### Listener.running

Source: https://pynput.readthedocs.io/en/latest/mouse.html

Whether the listener is currently running.

```APIDOC
## Listener.running

### Description
Whether the listener is currently running.

### Property
running

### Returns
bool - True if the listener is currently running, False otherwise.
```

--------------------------------

### Handle keyboard listener errors

Source: https://pynput.readthedocs.io/en/latest/keyboard.html

Demonstrates how to catch exceptions raised within a listener callback by joining the listener thread.

```python
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('{0} was pressed'.format(e.args[0]))
```

--------------------------------

### Legacy thread methods

Source: https://pynput.readthedocs.io/en/latest/_modules/threading.html

Compatibility methods for daemon status and naming.

```python
    def isDaemon(self):
        return self.daemon

    def setDaemon(self, daemonic):
        self.daemon = daemonic

    def getName(self):
        return self.name

    def setName(self, name):
        self.name = name
```

--------------------------------

### pynput.keyboard.KeyCode.from_dead()

Source: https://pynput.readthedocs.io/en/latest/genindex.html

Class method to create a KeyCode from a dead key.

```APIDOC
## pynput.keyboard.KeyCode.from_dead()

### Description
Class method to create a KeyCode from a dead key.

### Method
from_dead

### Class
pynput.keyboard.KeyCode
```

--------------------------------

### Equivalent implementation of controller.tap

Source: https://pynput.readthedocs.io/en/latest/keyboard.html

The tap method is a convenience wrapper that performs a press and release sequence.

```python
controller.press(key)
controller.release(key)
```

--------------------------------

### KeyCode Factory Methods

Source: https://pynput.readthedocs.io/en/latest/_modules/pynput/keyboard/_base.html

Factory methods to create KeyCode instances from virtual key codes, characters, or dead keys.

```python
@classmethod
def from_vk(cls, vk, **kwargs):
    """Creates a key from a virtual key code.

    :param vk: The virtual key code.

    :param kwargs: Any other parameters to pass.

    :return: a key code
    """
    return cls(vk=vk, **kwargs)

@classmethod
def from_char(cls, char, **kwargs):
    """Creates a key from a character.

    :param str char: The character.

    :return: a key code
    """
    return cls(char=char, **kwargs)

@classmethod
def from_dead(cls, char, **kwargs):
    """Creates a dead key.

    :param char: The dead key. This should be the unicode character
        representing the stand alone character, such as ``'~'`` for
        *COMBINING TILDE*.

    :return: a key code
    """
    return cls(char=char, is_dead=True, **kwargs)
```

--------------------------------

### Controller.press(key)

Source: https://pynput.readthedocs.io/en/latest/_modules/pynput/keyboard/_base.html

Presses a key. The key can be a string of length 1, a Key member, or a KeyCode. Raises InvalidKeyException for invalid keys and ValueError for strings not of length 1.

```APIDOC
## Controller.press(key)

### Description
Presses a key. A key may be either a string of length 1, one of the Key members or a KeyCode. Strings will be transformed to KeyCode using KeyCode.char. Members of Key will be translated to their Key.value.

### Method
press

### Parameters
- **key** (str, Key, or KeyCode) - Required - The key to press.

### Exceptions
- **InvalidKeyException** - if the key is invalid
- **ValueError** - if key is a string, but its length is not 1

```

--------------------------------

### Timer Thread Initialization and Execution

Source: https://pynput.readthedocs.io/en/latest/_modules/threading.html

Defines the initialization and run logic for a timer-based thread, including the cancel method to stop the timer.

```python
def __init__(self, interval, function, args=None, kwargs=None):
        Thread.__init__(self)
        self.interval = interval
        self.function = function
        self.args = args if args is not None else []
        self.kwargs = kwargs if kwargs is not None else {}
        self.finished = Event()

    def cancel(self):
        """Stop the timer if it hasn't finished yet."""
        self.finished.set()

    def run(self):
        self.finished.wait(self.interval)
        if not self.finished.is_set():
            self.function(*self.args, **self.kwargs)
        self.finished.set()
```

--------------------------------

### pynput.keyboard.Controller.touch()

Source: https://pynput.readthedocs.io/en/latest/genindex.html

Simulates touching a key on the keyboard. This method is part of the pynput.keyboard.Controller class.

```APIDOC
## pynput.keyboard.Controller.touch()

### Description
Simulates touching a key on the keyboard.

### Method
touch

### Class
pynput.keyboard.Controller
```

--------------------------------

### Condition.notify and notify_all implementation

Source: https://pynput.readthedocs.io/en/latest/_modules/threading.html

Wakes up waiting threads. notify_all is an alias for notify_all.

```python
    def notify(self, n=1):
        """Wake up one or more threads waiting on this condition, if any.

        If the calling thread has not acquired the lock when this method is
        called, a RuntimeError is raised.

        This method wakes up at most n of the threads waiting for the condition
        variable; it is a no-op if no threads are waiting.

        """
        if not self._is_owned():
            raise RuntimeError("cannot notify on un-acquired lock")
        all_waiters = self._waiters
        waiters_to_notify = _deque(_islice(all_waiters, n))
        if not waiters_to_notify:
            return
        for waiter in waiters_to_notify:
            waiter.release()
            try:
                all_waiters.remove(waiter)
            except ValueError:
                pass

    def notify_all(self):
        """Wake up all threads waiting on this condition.

        If the calling thread has not acquired the lock when this method
        is called, a RuntimeError is raised.

        """
        self.notify(len(self._waiters))

    notifyAll = notify_all
```
Tokens:
Raw