or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdkeyboard.mdmouse.md
tile.json

tessl/pypi-pynput

Monitor and control user input devices across multiple operating systems

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pynput@1.8.x

To install, run

npx @tessl/cli install tessl/pypi-pynput@1.8.0

index.mddocs/

Pynput

A Python library that provides comprehensive control and monitoring capabilities for user input devices including mouse and keyboard interactions across multiple operating systems (Windows, macOS, Linux). Pynput offers both high-level control interfaces for simulating mouse movements, clicks, scrolls and keyboard input, as well as event listeners for monitoring and responding to user input events in real-time.

Package Information

  • Package Name: pynput
  • Language: Python
  • Installation: pip install pynput

Platform-specific dependencies:

  • macOS: Requires PyObjC frameworks: pyobjc-framework-ApplicationServices >=8.0, pyobjc-framework-Quartz >=8.0
  • Linux: Requires evdev >= 1.3, python-xlib >= 0.17
  • Windows: No additional dependencies (uses built-in win32 APIs)

Core Imports

import pynput
from pynput import mouse, keyboard

Common imports for specific functionality:

from pynput.mouse import Button, Controller as MouseController, Listener as MouseListener
from pynput.keyboard import Key, KeyCode, Controller as KeyboardController, Listener as KeyboardListener

Basic Usage

from pynput import mouse, keyboard
import time

# Mouse control example
mouse_controller = mouse.Controller()

# Get current position
print(f"Current position: {mouse_controller.position}")

# Move mouse to specific position
mouse_controller.position = (100, 100)

# Click left button
mouse_controller.click(mouse.Button.left)

# Keyboard control example
keyboard_controller = keyboard.Controller()

# Press and release a key
keyboard_controller.press('a')
keyboard_controller.release('a')

# Type a string
keyboard_controller.type('Hello World')

# Press special keys
keyboard_controller.press(keyboard.Key.enter)
keyboard_controller.release(keyboard.Key.enter)

# Mouse monitoring example
def on_click(x, y, button, pressed):
    print(f'{"Pressed" if pressed else "Released"} {button} at ({x}, {y})')
    if not pressed:
        # Stop listener
        return False

with mouse.Listener(on_click=on_click) as listener:
    listener.join()

# Keyboard monitoring example
def on_key_press(key):
    print(f'Key {key} pressed')
    if key == keyboard.Key.esc:
        return False

with keyboard.Listener(on_press=on_key_press) as listener:
    listener.join()

Architecture

Pynput uses a cross-platform architecture with platform-specific backends:

  • Controllers: Classes for sending synthetic input events (mouse movements, clicks, key presses)
  • Listeners: Thread-based event listeners for monitoring real user input
  • Backend System: Automatic platform detection (Windows: win32, macOS: darwin, Linux: xorg)
  • Event Classes: Structured event objects for synchronous event processing

The library automatically selects the appropriate backend based on the operating system, providing consistent API across platforms while leveraging platform-specific optimizations.

Capabilities

Mouse Control and Monitoring

Comprehensive mouse input simulation and monitoring including position control, button clicks, scrolling, and real-time event listening. Supports all standard mouse buttons and scroll wheel interactions.

class Controller:
    def __init__(self): ...

    @property
    def position(self) -> tuple[int, int]: ...

    @position.setter
    def position(self, pos: tuple[int, int]): ...

    def move(self, dx: int, dy: int): ...
    def click(self, button: Button, count: int = 1): ...
    def press(self, button: Button): ...
    def release(self, button: Button): ...
    def scroll(self, dx: int, dy: int): ...

class Listener:
    def __init__(
        self,
        on_move: callable = None,
        on_click: callable = None,
        on_scroll: callable = None,
        suppress: bool = False,
        **kwargs
    ): ...

    def start(self): ...
    def stop(self): ...
    def join(self, timeout: float = None): ...

class Button(enum.Enum):
    left = 1
    middle = 2
    right = 3
    unknown = 0

Mouse Control and Monitoring

Keyboard Control and Monitoring

Full keyboard input simulation and monitoring including individual key presses, string typing, modifier key combinations, and hotkey support. Handles both character keys and special keys across different layouts.

class Controller:
    def __init__(self): ...

    def press(self, key: Key | KeyCode | str): ...
    def release(self, key: Key | KeyCode | str): ...
    def tap(self, key: Key | KeyCode | str): ...
    def type(self, string: str): ...
    def pressed(self, *keys) -> ContextManager: ...

class Listener:
    def __init__(
        self,
        on_press: callable = None,
        on_release: callable = None,
        suppress: bool = False,
        **kwargs
    ): ...

    def start(self): ...
    def stop(self): ...
    def join(self, timeout: float = None): ...

class KeyCode:
    def __init__(self, vk: int = None, char: str = None, is_dead: bool = False): ...

    @classmethod
    def from_vk(cls, vk: int) -> 'KeyCode': ...

    @classmethod
    def from_char(cls, char: str) -> 'KeyCode': ...

    @classmethod
    def from_dead(cls, char: str) -> 'KeyCode': ...

class HotKey:
    def __init__(self, keys: set, on_activate: callable): ...

    @staticmethod
    def parse(keys: str) -> list: ...

    def press(self, key): ...
    def release(self, key): ...

class GlobalHotKeys(Listener):
    def __init__(self, hotkeys: dict, *args, **kwargs): ...

Keyboard Control and Monitoring

Cross-Platform Support

Pynput automatically detects the operating system and loads the appropriate backend:

  • Windows: Uses win32 API for optimal performance and compatibility
  • macOS: Uses Quartz Event Services and ApplicationServices framework
  • Linux: Uses X11 (Xorg) for input handling and monitoring

Platform-specific options can be passed to listeners using prefixed parameters (e.g., darwin_intercept, win32_event_filter, xorg_*).

Error Handling

Common exceptions include:

  • Controller.InvalidKeyException: Raised when invalid key parameters are passed
  • Controller.InvalidCharacterException: Raised when untypable characters are encountered
  • StopException: Can be raised in listener callbacks to stop the listener
  • ImportError: Raised when platform dependencies are missing

The library includes helpful resolution messages for platform-specific dependency issues.