# API Reference

## `events`

This module provides the `InputEvent` class, which closely resembles the `input_event` struct defined in `linux/input.h`:

    struct input_event {
        struct timeval time;
        __u16 type;
        __u16 code;
        __s32 value;
    };

This module also defines several `InputEvent` sub-classes that know more about the different types of events (key, abs, rel etc). The `event_factory` dictionary maps event types to these classes.

Assuming you use the `evdev.util.categorize()` function to categorize events according to their type, adding or replacing a class for a specific event type becomes a matter of modifying `event_factory`.

All classes in this module have reasonable `str()` and `repr()` methods:

    >>> print(event)
    event at 1337197425.477827, code 04, type 04, val 458792
    >>> print(repr(event))
    InputEvent(1337197425L, 477827L, 4, 4, 458792L)

    >>> print(key_event)
    key event at 1337197425.477835, 28 (KEY_ENTER), up
    >>> print(repr(key_event))
    KeyEvent(InputEvent(1337197425L, 477835L, 1, 28, 0L))

class evdev.events.InputEvent(sec, usec, type, code, value)

  A generic input event.

  sec: int

    Time in seconds since epoch at which event occurred.

  usec: int

    Microsecond portion of the timestamp.

  type: int

    Event type - one of `ecodes.EV_*`.

  code: int

    Event code related to the event type.

  value: int

    Event value related to the event type.

  timestamp() → float

    Return event timestamp as a float.

class evdev.events.KeyEvent(event: InputEvent, allow_unknown: bool = False)

  An event generated by a keyboard, button or other key-like devices.

  key_up: Final[int] = 0
  key_down: Final[int] = 1
  key_hold: Final[int] = 2
  scancode: int
  keystate
  keycode
  event: InputEvent

    Reference to an `InputEvent` instance.

class evdev.events.RelEvent(event: InputEvent)

  A relative axis event (e.g moving the mouse 5 units to the left).

  event: InputEvent

    Reference to an `InputEvent` instance.

class evdev.events.SynEvent(event: InputEvent)

  A synchronization event. Used as markers to separate events. Events may be separated in time or in space, such as with the multitouch protocol.

  event: InputEvent

    Reference to an `InputEvent` instance.

class evdev.events.AbsEvent(event: InputEvent)

  An absolute axis event (e.g the coordinates of a tap on a touchscreen).

  event: InputEvent

    Reference to an `InputEvent` instance.

evdev.events.event_factory = {0: <class 'evdev.events.SynEvent'>, 1: <class 'evdev.events.KeyEvent'>, 2: <class 'evdev.events.RelEvent'>, 3: <class 'evdev.events.AbsEvent'>}

  A mapping of event types to `InputEvent` sub-classes. Used by `evdev.util.categorize()`

## `eventio`

class evdev.eventio.EventIO

  Base class for reading and writing input events.

  This class is used by `InputDevice` and `UInput`.

  - On, `InputDevice` it used for reading user-generated events (e.g. key presses, mouse movements) and writing feedback events (e.g. leds, beeps).

  - On, `UInput` it used for writing user-generated events (e.g. key presses, mouse movements) and reading feedback events (e.g. leds, beeps).

  fileno()

    Return the file descriptor to the open event device. This makes it possible to pass instances directly to `select.select()` and `asyncore.file_dispatcher`.

  read_loop() → Iterator[InputEvent]

    Enter an endless `select.select()` loop that yields input events.

  read_one() → InputEvent | None

    Read and return a single input event as an instance of `InputEvent`.

    Return `None` if there are no pending input events.

  read() → Iterator[InputEvent]

    Read multiple input events from device. Return a generator object that yields `InputEvent` instances. Raises BlockingIOError if there are no available events at the moment.

  need_write()

    Decorator that raises `EvdevError` if there is no write access to the input device.

  write_event(event)

    Inject an input event into the input subsystem. Events are queued until a synchronization event is received.

    Parameters:

      event (InputEvent) – InputEvent instance or an object with an `event` attribute (`KeyEvent`, `RelEvent` etc).

    Example

        >>> ev = InputEvent(1334414993, 274296, ecodes.EV_KEY, ecodes.KEY_A, 1)
        >>> ui.write_event(ev)

  write(etype: int, code: int, value: int)

    Inject an input event into the input subsystem. Events are queued until a synchronization event is received.

    Parameters:

      - etype – event type (e.g. `EV_KEY`).

      - code – event code (e.g. `KEY_A`).

      - value – event value (e.g. 0 1 2 - depends on event type).

    Example

        >>> ui.write(e.EV_KEY, e.KEY_A, 1) # key A - down
        >>> ui.write(e.EV_KEY, e.KEY_A, 0) # key A - up

  syn()

    Inject a `SYN_REPORT` event into the input subsystem. Events queued by `write()` will be fired. If possible, events will be merged into an ‘atomic’ event.

  close()
  __firstlineno__ = 16
  __static_attributes__ = ()
  __weakref__

    list of weak references to the object

## `eventio_async`

class evdev.eventio_async.EventIO
  async_read_one()

    Asyncio coroutine to read and return a single input event as an instance of `InputEvent`.

  async_read()

    Asyncio coroutine to read multiple input events from device. Return a generator object that yields `InputEvent` instances.

  async_read_loop() → ReadIterator

    Return an iterator that yields input events. This iterator is compatible with the `async for` syntax.

  __annotations__ = {}
  __firstlineno__ = 56
  __static_attributes__ = ()
  close()

## `device`

class evdev.device.AbsInfo(value: int, min: int, max: int, fuzz: int, flat: int, resolution: int)

  Absolute axis information.

  A `namedtuple` with absolute axis information - corresponds to the `input_absinfo` struct:

  value

    Latest reported value for the axis.

    Type:

      int

  min

    Specifies minimum value for the axis.

    Type:

      int

  max

    Specifies maximum value for the axis.

    Type:

      int

  fuzz

    Specifies fuzz value that is used to filter noise from the event stream.

    Type:

      int

  flat

    Values that are within this value will be discarded by joydev interface and reported as 0 instead.

    Type:

      int

  resolution

    Specifies resolution for the values reported for the axis. Resolution for main axes (`ABS_X, ABS_Y, ABS_Z`) is reported in units per millimeter (units/mm), resolution for rotational axes (`ABS_RX, ABS_RY, ABS_RZ`) is reported in units per radian.

    Type:

      int

  Note

  The input core does not clamp reported values to the `[minimum, maximum]` limits, such task is left to userspace.

  value: int

    Alias for field number 0

  min: int

    Alias for field number 1

  max: int

    Alias for field number 2

  fuzz: int

    Alias for field number 3

  flat: int

    Alias for field number 4

  resolution: int

    Alias for field number 5

  __annotations__ = {'flat': <class 'int'>, 'fuzz': <class 'int'>, 'max': <class 'int'>, 'min': <class 'int'>, 'resolution': <class 'int'>, 'value': <class 'int'>}
  __firstlineno__ = 13
  __getnewargs__()

    Return self as a plain tuple. Used by copy and pickle.

  __match_args__ = ('value', 'min', 'max', 'fuzz', 'flat', 'resolution')
  static __new__(_cls, value: int, min: int, max: int, fuzz: int, flat: int, resolution: int)

    Create new instance of AbsInfo(value, min, max, fuzz, flat, resolution)

  __orig_bases__ = (<function NamedTuple>,)
  __replace__(**kwds)

    Return a new AbsInfo object replacing specified fields with new values

  __static_attributes__ = ()

class evdev.device.KbdInfo(delay: int, repeat: int)

  Keyboard repeat rate.

  delay

    Amount of time that a key must be depressed before it will start to repeat (in milliseconds).

    Type:

      int

  repeat

    Keyboard repeat rate in characters per second.

    Type:

      int

  delay: int

    Alias for field number 0

  repeat: int

    Alias for field number 1

  __annotations__ = {'delay': <class 'int'>, 'repeat': <class 'int'>}
  __firstlineno__ = 63
  __getnewargs__()

    Return self as a plain tuple. Used by copy and pickle.

  __match_args__ = ('delay', 'repeat')
  static __new__(_cls, delay: int, repeat: int)

    Create new instance of KbdInfo(delay, repeat)

  __orig_bases__ = (<function NamedTuple>,)
  __replace__(**kwds)

    Return a new KbdInfo object replacing specified fields with new values

  __static_attributes__ = ()

class evdev.device.DeviceInfo(bustype: int, vendor: int, product: int, version: int)
  bustype
    Type:

      int

  vendor
    Type:

      int

  product
    Type:

      int

  version
    Type:

      int

  bustype: int

    Alias for field number 0

  vendor: int

    Alias for field number 1

  product: int

    Alias for field number 2

  version: int

    Alias for field number 3

  __annotations__ = {'bustype': <class 'int'>, 'product': <class 'int'>, 'vendor': <class 'int'>, 'version': <class 'int'>}
  __firstlineno__ = 83
  __getnewargs__()

    Return self as a plain tuple. Used by copy and pickle.

  __match_args__ = ('bustype', 'vendor', 'product', 'version')
  static __new__(_cls, bustype: int, vendor: int, product: int, version: int)

    Create new instance of DeviceInfo(bustype, vendor, product, version)

  __orig_bases__ = (<function NamedTuple>,)
  __replace__(**kwds)

    Return a new DeviceInfo object replacing specified fields with new values

  __static_attributes__ = ()

class evdev.device.InputDevice(dev: str | bytes | PathLike)

  A linux input device from which input events can be read.

  __init__(dev: str | bytes | PathLike)
    Parameters:

      dev (str|bytes|PathLike) – Path to input device

  path

    Path to input device.

  fd: int

    A non-blocking file descriptor to the device file.

  info

    A `DeviceInfo` instance.

  name: str

    The name of the event device.

  phys: str

    The physical topology of the device.

  uniq: str

    The unique identifier of the device.

  version: int

    The evdev protocol version.

  ff_effects_count

    The number of force feedback effects the device can keep in its memory.

  capabilities(verbose: Literal[False] = False, absinfo: bool = True) → Dict[int, List[int]]
  capabilities(verbose: Literal[True], absinfo: bool = True) → Dict[Tuple[str, int], List[Tuple[str, int]]]

    Return the event types that this device supports as a mapping of supported event types to lists of handled event codes.

    Example

        >>> device.capabilities()
        { 1: [272, 273, 274],
          2: [0, 1, 6, 8] }

    If `verbose` is `True`, event codes and types will be resolved to their names.

        { ('EV_KEY', 1): [('BTN_MOUSE', 272),
                          ('BTN_RIGHT', 273),
                          ('BTN_MIDDLE', 273)],
          ('EV_REL', 2): [('REL_X', 0),
                          ('REL_Y', 1),
                          ('REL_HWHEEL', 6),
                          ('REL_WHEEL', 8)] }

    Unknown codes or types will be resolved to `'?'`.

    If `absinfo` is `True`, the list of capabilities will also include absolute axis information in the form of `AbsInfo` instances:

        { 3: [ (0, AbsInfo(min=0, max=255, fuzz=0, flat=0)),
               (1, AbsInfo(min=0, max=255, fuzz=0, flat=0)) ]}

    Combined with `verbose` the above becomes:

        { ('EV_ABS', 3): [ (('ABS_X', 0), AbsInfo(min=0, max=255, fuzz=0, flat=0)),
                           (('ABS_Y', 1), AbsInfo(min=0, max=255, fuzz=0, flat=0)) ]}

  input_props(verbose: bool = False)

    Get device properties and quirks.

    Example

        >>> device.input_props()
        [0, 5]

    If `verbose` is `True`, input properties are resolved to their names. Unknown codes are resolved to `'?'`:

        [('INPUT_PROP_POINTER', 0), ('INPUT_PROP_POINTING_STICK', 5)]

  leds(verbose: bool = False)

    Return currently set LED keys.

    Example

        >>> device.leds()
        [0, 1, 8, 9]

    If `verbose` is `True`, event codes are resolved to their names. Unknown codes are resolved to `'?'`:

        [('LED_NUML', 0), ('LED_CAPSL', 1), ('LED_MISC', 8), ('LED_MAIL', 9)]

  set_led(led_num: int, value: int) → None

    Set the state of the selected LED.

    Example

        >>> device.set_led(ecodes.LED_NUML, 1)

  __eq__(other)

    Two devices are equal if their `info` attributes are equal.

  __fspath__()
  close() → None
  grab() → None

    Grab input device using `EVIOCGRAB` - other applications will be unable to receive events until the device is released. Only one process can hold a `EVIOCGRAB` on a device.

    Warning

    Grabbing an already grabbed device will raise an `OSError`.

  ungrab() → None

    Release device if it has been already grabbed (uses EVIOCGRAB).

    Warning

    Releasing an already released device will raise an `OSError('Invalid argument')`.

  grab_context() → Iterator[None]

    A context manager for the duration of which only the current process will be able to receive events from the device.

  upload_effect(effect: ff.Effect)

    Upload a force feedback effect to a force feedback device.

  erase_effect(ff_id) → None

    Erase a force effect from a force feedback device. This also stops the effect.

  property repeat

    Get or set the keyboard repeat rate (in characters per minute) and delay (in milliseconds).

  __annotations__ = {'fd': 'int', 'name': 'str', 'phys': 'str', 'uniq': 'str', 'version': 'int'}
  __firstlineno__ = 103
  __hash__ = None
  __static_attributes__ = ('_rawcapabilities', 'fd', 'ff_effects_count', 'info', 'name', 'path', 'phys', 'uniq', 'version')
  active_keys(verbose: bool = False)

    Return currently active keys.

    Example

        >>> device.active_keys()
        [1, 42]

    If `verbose` is `True`, key codes are resolved to their verbose names. Unknown codes are resolved to `'?'`. For example:

        [('KEY_ESC', 1), ('KEY_LEFTSHIFT', 42)]

  absinfo(axis_num: int)

    Return current `AbsInfo` for input device axis

    Parameters:

      axis_num (int) – EV_ABS keycode (example `ecodes.ABS_X`)

    Example

        >>> device.absinfo(ecodes.ABS_X)
        AbsInfo(value=1501, min=-32768, max=32767, fuzz=0, flat=128, resolution=0)

  set_absinfo(axis_num: int, value=None, min=None, max=None, fuzz=None, flat=None, resolution=None) → None

    Update `AbsInfo` values. Only specified values will be overwritten.

    Parameters:

      axis_num (int) – EV_ABS keycode (example `ecodes.ABS_X`)

    Example

        >>> device.set_absinfo(ecodes.ABS_X, min=-2000, max=2000)

    You can also unpack AbsInfo tuple that will overwrite all values

        >>> device.set_absinfo(ecodes.ABS_Y, *AbsInfo(0, -2000, 2000, 0, 15, 0))

## `uinput`

class evdev.uinput.UInput(events: Dict[int, Sequence[int]] | None = None, name: str = 'py-evdev-uinput', vendor: int = 1, product: int = 1, version: int = 1, bustype: int = 3, devnode: str = '/dev/uinput', phys: str = 'py-evdev-uinput', input_props=None, max_effects=96)

  A userland input device and that can inject input events into the linux input subsystem.

  classmethod from_device(*devices: InputDevice | str | bytes | PathLike, filtered_types: Tuple[int] = (0, 21), **kwargs)

    Create an UInput device with the capabilities of one or more input devices.

    Parameters:

      - devices (InputDevice|str) – Varargs of InputDevice instances or paths to input devices.

      - filtered_types (Tuple[event type codes]) – Event types to exclude from the capabilities of the uinput device.

      - **kwargs – Keyword arguments to UInput constructor (i.e. name, vendor etc.).

  __init__(events: Dict[int, Sequence[int]] | None = None, name: str = 'py-evdev-uinput', vendor: int = 1, product: int = 1, version: int = 1, bustype: int = 3, devnode: str = '/dev/uinput', phys: str = 'py-evdev-uinput', input_props=None, max_effects=96)
    Parameters:

      - events (dict) – Dictionary of event types mapping to lists of event codes. The event types and codes that the uinput device will be able to inject - defaults to all key codes.

      - name – The name of the input device.

      - vendor – Vendor identifier.

      - product – Product identifier.

      - version – Version identifier.

      - bustype – Bustype identifier.

      - phys – Physical path.

      - input_props – Input properties and quirks.

      - max_effects – Maximum simultaneous force-feedback effects.

    Note

    If you do not specify any events, the uinput device will be able to inject only `KEY_*` and `BTN_*` event codes.

  name: str

    Uinput device name.

  vendor: int

    Device vendor identifier.

  product: int

    Device product identifier.

  version: int

    Device version identifier.

  bustype: int

    Device bustype - e.g. `BUS_USB`.

  phys: str

    Uinput device physical path.

  devnode: str

    Uinput device node - e.g. `/dev/uinput/`.

  fd

    Write-only, non-blocking file descriptor to the uinput device node.

  device: InputDevice

    An `InputDevice` instance for the fake input device. `None` if the device cannot be opened for reading and writing.

  capabilities(verbose: bool = False, absinfo: bool = True)

    See `capabilities`.

## `util`

evdev.util.list_devices(input_device_dir: str | bytes | PathLike = '/dev/input') → List[str]

  List readable character devices in `input_device_dir`.

evdev.util.is_device(fn: str | bytes | PathLike) → bool

  Check if `fn` is a readable and writable character device.

evdev.util.categorize(event: InputEvent) → InputEvent

  Categorize an event according to its type.

  The `event_factory` dictionary maps event types to sub-classes of `InputEvent`. If the event cannot be categorized, it is returned unmodified.

evdev.util.resolve_ecodes(ecode_dict, ecode_list, unknown='?')

  Resolve event codes and types to their verbose names.

  Example

      >>> resolve_ecodes(ecodes.BTN, [272, 273, 274])
      [(['BTN_LEFT', 'BTN_MOUSE'], 272), ('BTN_RIGHT', 273), ('BTN_MIDDLE', 274)]

evdev.util.resolve_ecodes_dict(typecodemap, unknown='?')

  Resolve event codes and types to their verbose names.

  Parameters:

    - typecodemap – mapping of event types to lists of event codes.

    - unknown – symbol to which unknown types or codes will be resolved.

  Example

      >>> resolve_ecodes_dict({ 1: [272, 273, 274] })
      { ('EV_KEY', 1): [('BTN_MOUSE',  272),
                        ('BTN_RIGHT',  273),
                        ('BTN_MIDDLE', 274)] }

  If `typecodemap` contains absolute axis info (instances of `AbsInfo` ) the result would look like:

      >>> resolve_ecodes_dict({ 3: [(0, AbsInfo(...))] })
      { ('EV_ABS', 3L): [(('ABS_X', 0L), AbsInfo(...))] }

## `ecodes`

This modules exposes the integer constants defined in `linux/input.h` and `linux/input-event-codes.h`.

Exposed constants:

    KEY, ABS, REL, SW, MSC, LED, BTN, REP, SND, ID, EV,
    BUS, SYN, FF, FF_STATUS, INPUT_PROP

This module also provides reverse and forward mappings of the names and values of the above mentioned constants:

    >>> evdev.ecodes.KEY_A
    30

    >>> evdev.ecodes.ecodes['KEY_A']
    30

    >>> evdev.ecodes.KEY[30]
    'KEY_A'

    >>> evdev.ecodes.REL[0]
    'REL_X'

    >>> evdev.ecodes.EV[evdev.ecodes.EV_KEY]
    'EV_KEY'

    >>> evdev.ecodes.bytype[evdev.ecodes.EV_REL][0]
    'REL_X'

Keep in mind that values in reverse mappings may point to one or more event codes. For example:

    >>> evdev.ecodes.FF[80]
    ('FF_EFFECT_MIN', 'FF_RUMBLE')

    >>> evdev.ecodes.FF[81]
    'FF_PERIODIC'

evdev.ecodes.keys {0: 'KEY_RESERVED', 1: 'KEY_ESC', 2: 'KEY_1', ...}

  Keys are a combination of all BTN and KEY codes.

evdev.ecodes.ecodes {'KEY_END': 107, 'FF_RUMBLE': 80, 'KEY_KPDOT': 83, 'KEY_CNT': 768, ...}'

  Mapping of names to values.

evdev.ecodes.bytype {0: {0: 'SYN_REPORT', 1: 'SYN_CONFIG', 2: 'SYN_MT_REPORT', 3: 'SYN_DROPPED'}, ...}

  Mapping of event types to other value/name mappings.