pyinterception

Install the library using the PyPi package name interception-python via pip.

pip install interception-python

Before sending any inputs, you must call interception.auto_capture_devices() to allow the library to obtain the correct device handles.

Note: The interception-driver must be installed on your system for this to work.

import interception

interception.auto_capture_devices()

The Stroke protocol defines how input events (mouse or key) are converted between the C-structs expected by the interception driver and Python objects.

Every Stroke implementation must provide:

1. A format class variable (bytes) defining the struct packing format.
2. A parse(cls, data: bytes) class method to unpack raw bytes into a Python object.
3. A data property to pack the Python object back into raw bytes for driver communication.

This pattern ensures type safety and IDE support while maintaining the ability to interface with low-level C structures.

The library provides a simple interface for sending inputs, similar to pyautogui or pydirectinput.

Common operations include:

• move_to(x, y): Moves the mouse to specific coordinates.
• click(x, y, button='left', delay=0): Clicks at coordinates with a specified button and delay.
• press(key): Presses a key.
• hold_key(key): A context manager to hold a key down (e.g., for modifiers like ctrl).

import interception

interception.auto_capture_devices()

# Move mouse
interception.move_to(960, 540)

# Use modifiers with a context manager
with interception.hold_key("ctrl"):
    interception.press("v")

# Click with specific button and delay
interception.click(120, 160, button="right", delay=1)

The smooth movement functionality (specifically the HumanCurve class) depends on the pyclick library.

If pyclick is not installed in your environment, interception will initialize a dummy HumanCurve class. Attempting to use this dummy class will result in a PyClickNotInstalled exception from the interception.exceptions module.

Use receive() to retrieve the next available input stroke from the device.

Requirement: For receive() to work correctly, the device must be the result of a kernel32 WaitForMultipleObjects call to ensure there is valid input waiting to be read. If no stroke is available, the method returns None.

stroke = device.receive()
if stroke is not None:
    # stroke will be an instance of KeyStroke or MouseStroke
    pass

Use press(key, presses, interval) to simulate pressing a keyboard key a specific number of times.

Use write(term, interval) to type a string of characters sequentially. Note that uppercase characters are not currently supported; the input will be converted to lowercase.

Note: For mouse buttons, use the click functions instead of press.

# Press the 'a' key twice
interception.press("a", presses=2)

# Type a string
interception.write("hello world", interval=0.05)

The Interception class allows you to set which device index is treated as the primary mouse or keyboard for your context. This is useful for logic that needs to know which device is currently being targeted.

• mouse: Must be a valid mouse index (typically 10 <= num <= 19). Setting an invalid index raises a ValueError.
• keyboard: Must be a valid keyboard index (typically 0 <= num <= 9). Setting an invalid index raises a ValueError.

The Device class represents a Windows I/O mouse or keyboard device. It allows you to receive input strokes (keystrokes or mouse movements) and send strokes back to the device.

Important Lifecycle Note: You must call destroy() on a Device instance before it is destroyed to close the underlying Windows handles and prevent handle leakage.

from ctypes.wintypes import HANDLE
from interception.device import Device

# Note: handle and event must be obtained via appropriate Windows API calls (e.g., CreateFileA)
# is_keyboard should be True for keyboards, False for mice
device = Device(handle=my_handle, event=my_event, is_keyboard=True)

try:
    # Perform operations
    stroke = device.receive()
    if stroke:
        print(f"Received: {stroke}")
finally:
    device.destroy()