evdev-binary 1.9.3__cp314-cp314t-musllinux_1_2_x86_64.whl

evdev/ecodes_runtime.py

@@ -0,0 +1,111 @@
+# pylint: disable=undefined-variable
+"""
+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'
+"""
+
+from inspect import getmembers
+
+from . import _ecodes
+
+#: Mapping of names to values.
+ecodes = {}
+
+prefixes = "KEY ABS REL SW MSC LED BTN REP SND ID EV BUS SYN FF_STATUS FF INPUT_PROP UI_FF".split()
+prev_prefix = ""
+g = globals()
+
+# eg. code: 'REL_Z', val: 2
+for code, val in getmembers(_ecodes):
+    for prefix in prefixes:  # eg. 'REL'
+        if code.startswith(prefix):
+            ecodes[code] = val
+            # FF_STATUS codes should not appear in the FF reverse mapping
+            if not code.startswith(prev_prefix):
+                d = g.setdefault(prefix, {})
+                # codes that share the same value will be added to a list. eg:
+                # >>> ecodes.FF_STATUS
+                # {0: 'FF_STATUS_STOPPED', 1: ['FF_STATUS_MAX', 'FF_STATUS_PLAYING']}
+                if val in d:
+                    if isinstance(d[val], list):
+                        d[val].append(code)
+                    else:
+                        d[val] = [d[val], code]
+                else:
+                    d[val] = code
+
+        prev_prefix = prefix
+
+
+# Convert lists to tuples.
+k, v = None, None
+for prefix in prefixes:
+    for k, v in g[prefix].items():
+        if isinstance(v, list):
+            g[prefix][k] = tuple(v)
+
+
+#: Keys are a combination of all BTN and KEY codes.
+keys = {}
+keys.update(BTN)
+keys.update(KEY)
+
+# make keys safe to use for the default list of uinput device
+# capabilities
+del keys[_ecodes.KEY_MAX]
+del keys[_ecodes.KEY_CNT]
+
+#: Mapping of event types to other value/name mappings.
+bytype = {
+    _ecodes.EV_KEY: keys,
+    _ecodes.EV_ABS: ABS,
+    _ecodes.EV_REL: REL,
+    _ecodes.EV_SW: SW,
+    _ecodes.EV_MSC: MSC,
+    _ecodes.EV_LED: LED,
+    _ecodes.EV_REP: REP,
+    _ecodes.EV_SND: SND,
+    _ecodes.EV_SYN: SYN,
+    _ecodes.EV_FF: FF,
+    _ecodes.EV_FF_STATUS: FF_STATUS,
+}
+
+from evdev._ecodes import *
+
+# cheaper than whitelisting in an __all__
+del code, val, prefix, getmembers, g, d, k, v, prefixes, prev_prefix

evdev/eventio.py

@@ -0,0 +1,152 @@
+import fcntl
+import functools
+import os
+import select
+from typing import Iterator, Union
+
+from . import _input, _uinput, ecodes
+from .events import InputEvent
+
+
+# --------------------------------------------------------------------------
+class EvdevError(Exception):
+    pass
+
+
+class EventIO:
+    """
+    Base class for reading and writing input events.
+
+    This class is used by :class:`InputDevice` and :class:`UInput`.
+
+    - On, :class:`InputDevice` it used for reading user-generated events (e.g.
+      key presses, mouse movements) and writing feedback events (e.g. leds,
+      beeps).
+
+    - On, :class:`UInput` it used for writing user-generated events (e.g.
+      key presses, mouse movements) and reading feedback events (e.g. leds,
+      beeps).
+    """
+
+    def fileno(self):
+        """
+        Return the file descriptor to the open event device. This makes
+        it possible to pass instances directly to :func:`select.select()` and
+        :class:`asyncore.file_dispatcher`.
+        """
+        return self.fd
+
+    def read_loop(self) -> Iterator[InputEvent]:
+        """
+        Enter an endless :func:`select.select()` loop that yields input events.
+        """
+
+        while True:
+            r, w, x = select.select([self.fd], [], [])
+            for event in self.read():
+                yield event
+
+    def read_one(self) -> Union[InputEvent, None]:
+        """
+        Read and return a single input event as an instance of
+        :class:`InputEvent <evdev.events.InputEvent>`.
+
+        Return ``None`` if there are no pending input events.
+        """
+
+        # event -> (sec, usec, type, code, val)
+        event = _input.device_read(self.fd)
+
+        if event:
+            return InputEvent(*event)
+
+    def read(self) -> Iterator[InputEvent]:
+        """
+        Read multiple input events from device. Return a generator object that
+        yields :class:`InputEvent <evdev.events.InputEvent>` instances. Raises
+        `BlockingIOError` if there are no available events at the moment.
+        """
+
+        # events -> ((sec, usec, type, code, val), ...)
+        events = _input.device_read_many(self.fd)
+
+        for event in events:
+            yield InputEvent(*event)
+
+    # pylint: disable=no-self-argument
+    def need_write(func):
+        """
+        Decorator that raises :class:`EvdevError` if there is no write access to the
+        input device.
+        """
+
+        @functools.wraps(func)
+        def wrapper(*args):
+            fd = args[0].fd
+            if fcntl.fcntl(fd, fcntl.F_GETFL) & os.O_RDWR:
+                # pylint: disable=not-callable
+                return func(*args)
+            msg = 'no write access to device "%s"' % args[0].path
+            raise EvdevError(msg)
+
+        return wrapper
+
+    def write_event(self, event):
+        """
+        Inject an input event into the input subsystem. Events are
+        queued until a synchronization event is received.
+
+        Arguments
+        ---------
+        event: InputEvent
+          InputEvent instance or an object with an ``event`` attribute
+          (:class:`KeyEvent <evdev.events.KeyEvent>`, :class:`RelEvent
+          <evdev.events.RelEvent>` etc).
+
+        Example
+        -------
+        >>> ev = InputEvent(1334414993, 274296, ecodes.EV_KEY, ecodes.KEY_A, 1)
+        >>> ui.write_event(ev)
+        """
+
+        if hasattr(event, "event"):
+            event = event.event
+
+        self.write(event.type, event.code, event.value)
+
+    @need_write
+    def write(self, etype: int, code: int, value: int):
+        """
+        Inject an input event into the input subsystem. Events are
+        queued until a synchronization event is received.
+
+        Arguments
+        ---------
+        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
+        """
+
+        _uinput.write(self.fd, etype, code, value)
+
+    def syn(self):
+        """
+        Inject a ``SYN_REPORT`` event into the input subsystem. Events
+        queued by :func:`write()` will be fired. If possible, events
+        will be merged into an 'atomic' event.
+        """
+
+        self.write(ecodes.EV_SYN, ecodes.SYN_REPORT, 0)
+
+    def close(self):
+        pass

evdev/eventio_async.py

@@ -0,0 +1,106 @@
+import asyncio
+import select
+import sys
+
+from . import eventio
+from .events import InputEvent
+
+# needed for compatibility
+from .eventio import EvdevError
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing import Any as Self
+
+
+class ReadIterator:
+    def __init__(self, device):
+        self.current_batch = iter(())
+        self.device = device
+
+    # Standard iterator protocol.
+    def __iter__(self) -> Self:
+        return self
+
+    def __next__(self) -> InputEvent:
+        try:
+            # Read from the previous batch of events.
+            return next(self.current_batch)
+        except StopIteration:
+            r, w, x = select.select([self.device.fd], [], [])
+            self.current_batch = self.device.read()
+            return next(self.current_batch)
+
+    def __aiter__(self) -> Self:
+        return self
+
+    def __anext__(self) -> "asyncio.Future[InputEvent]":
+        future = asyncio.Future()
+        try:
+            # Read from the previous batch of events.
+            future.set_result(next(self.current_batch))
+        except StopIteration:
+
+            def next_batch_ready(batch):
+                try:
+                    self.current_batch = batch.result()
+                    future.set_result(next(self.current_batch))
+                except Exception as e:
+                    future.set_exception(e)
+
+            self.device.async_read().add_done_callback(next_batch_ready)
+        return future
+
+
+class EventIO(eventio.EventIO):
+    def _do_when_readable(self, callback):
+        loop = asyncio.get_event_loop()
+
+        def ready():
+            loop.remove_reader(self.fileno())
+            callback()
+
+        loop.add_reader(self.fileno(), ready)
+
+    def _set_result(self, future, cb):
+        try:
+            future.set_result(cb())
+        except Exception as error:
+            future.set_exception(error)
+
+    def async_read_one(self):
+        """
+        Asyncio coroutine to read and return a single input event as
+        an instance of :class:`InputEvent <evdev.events.InputEvent>`.
+        """
+        future = asyncio.Future()
+        self._do_when_readable(lambda: self._set_result(future, self.read_one))
+        return future
+
+    def async_read(self):
+        """
+        Asyncio coroutine to read multiple input events from device. Return
+        a generator object that yields :class:`InputEvent <evdev.events.InputEvent>`
+        instances.
+        """
+        future = asyncio.Future()
+        self._do_when_readable(lambda: self._set_result(future, self.read))
+        return future
+
+    def async_read_loop(self) -> ReadIterator:
+        """
+        Return an iterator that yields input events. This iterator is
+        compatible with the ``async for`` syntax.
+
+        """
+        return ReadIterator(self)
+
+    def close(self):
+        try:
+            loop = asyncio.get_event_loop()
+            loop.remove_reader(self.fileno())
+        except RuntimeError:
+            # no event loop present, so there is nothing to
+            # remove the reader from. Ignore
+            pass

evdev/events.py

@@ -0,0 +1,192 @@
+"""
+This module provides the :class:`InputEvent` class, which closely
+resembles the ``input_event`` struct defined in ``linux/input.h``:
+
+.. code-block:: c
+
+    struct input_event {
+        struct timeval time;
+        __u16 type;
+        __u16 code;
+        __s32 value;
+    };
+
+This module also defines several :class:`InputEvent` sub-classes that
+know more about the different types of events (key, abs, rel etc). The
+:data:`event_factory` dictionary maps event types to these classes.
+
+Assuming you use the :func:`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
+:data:`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))
+"""
+
+# event type descriptions have been taken mot-a-mot from:
+# http://www.kernel.org/doc/Documentation/input/event-codes.txt
+
+# pylint: disable=no-name-in-module
+from typing import Final
+from .ecodes import ABS, EV_ABS, EV_KEY, EV_REL, EV_SYN, KEY, REL, SYN, keys
+
+
+class InputEvent:
+    """A generic input event."""
+
+    __slots__ = "sec", "usec", "type", "code", "value"
+
+    def __init__(self, sec, usec, type, code, value):
+        #: Time in seconds since epoch at which event occurred.
+        self.sec: int = sec
+
+        #: Microsecond portion of the timestamp.
+        self.usec: int = usec
+
+        #: Event type - one of ``ecodes.EV_*``.
+        self.type: int = type
+
+        #: Event code related to the event type.
+        self.code: int = code
+
+        #: Event value related to the event type.
+        self.value: int = value
+
+    def timestamp(self) -> float:
+        """Return event timestamp as a float."""
+        return self.sec + (self.usec / 1000000.0)
+
+    def __str__(self):
+        msg = "event at {:f}, code {:02d}, type {:02d}, val {:02d}"
+        return msg.format(self.timestamp(), self.code, self.type, self.value)
+
+    def __repr__(self):
+        msg = "{}({!r}, {!r}, {!r}, {!r}, {!r})"
+        return msg.format(self.__class__.__name__, self.sec, self.usec, self.type, self.code, self.value)
+
+
+class KeyEvent:
+    """An event generated by a keyboard, button or other key-like devices."""
+
+    key_up: Final[int] = 0x0
+    key_down: Final[int] = 0x1
+    key_hold: Final[int] = 0x2
+
+    __slots__ = "scancode", "keycode", "keystate", "event"
+
+    def __init__(self, event: InputEvent, allow_unknown: bool = False):
+        """
+        The ``allow_unknown`` argument determines what to do in the event of an event code
+        for which a key code cannot be found. If ``False`` a ``KeyError`` will be raised.
+        If ``True`` the keycode will be set to the hex value of the event code.
+        """
+
+        self.scancode: int = event.code
+
+        if event.value == 0:
+            self.keystate = KeyEvent.key_up
+        elif event.value == 2:
+            self.keystate = KeyEvent.key_hold
+        elif event.value == 1:
+            self.keystate = KeyEvent.key_down
+
+        try:
+            self.keycode = keys[event.code]
+        except KeyError:
+            if allow_unknown:
+                self.keycode = "0x{:02X}".format(event.code)
+            else:
+                raise
+
+        #: Reference to an :class:`InputEvent` instance.
+        self.event: InputEvent = event
+
+    def __str__(self):
+        try:
+            ks = ("up", "down", "hold")[self.keystate]
+        except IndexError:
+            ks = "unknown"
+
+        msg = "key event at {:f}, {} ({}), {}"
+        return msg.format(self.event.timestamp(), self.scancode, self.keycode, ks)
+
+    def __repr__(self):
+        return "{}({!r})".format(self.__class__.__name__, self.event)
+
+
+class RelEvent:
+    """A relative axis event (e.g moving the mouse 5 units to the left)."""
+
+    __slots__ = "event"
+
+    def __init__(self, event: InputEvent):
+        #: Reference to an :class:`InputEvent` instance.
+        self.event: InputEvent = event
+
+    def __str__(self):
+        msg = "relative axis event at {:f}, {}"
+        return msg.format(self.event.timestamp(), REL[self.event.code])
+
+    def __repr__(self):
+        return "{}({!r})".format(self.__class__.__name__, self.event)
+
+
+class AbsEvent:
+    """An absolute axis event (e.g the coordinates of a tap on a touchscreen)."""
+
+    __slots__ = "event"
+
+    def __init__(self, event: InputEvent):
+        #: Reference to an :class:`InputEvent` instance.
+        self.event: InputEvent = event
+
+    def __str__(self):
+        msg = "absolute axis event at {:f}, {}"
+        return msg.format(self.event.timestamp(), ABS[self.event.code])
+
+    def __repr__(self):
+        return "{}({!r})".format(self.__class__.__name__, self.event)
+
+
+class SynEvent:
+    """
+    A synchronization event. Used as markers to separate events. Events may be
+    separated in time or in space, such as with the multitouch protocol.
+    """
+
+    __slots__ = "event"
+
+    def __init__(self, event: InputEvent):
+        #: Reference to an :class:`InputEvent` instance.
+        self.event: InputEvent = event
+
+    def __str__(self):
+        msg = "synchronization event at {:f}, {}"
+        return msg.format(self.event.timestamp(), SYN[self.event.code])
+
+    def __repr__(self):
+        return "{}({!r})".format(self.__class__.__name__, self.event)
+
+
+#: A mapping of event types to :class:`InputEvent` sub-classes. Used
+#: by :func:`evdev.util.categorize()`
+event_factory = {
+    EV_KEY: KeyEvent,
+    EV_REL: RelEvent,
+    EV_ABS: AbsEvent,
+    EV_SYN: SynEvent,
+}
+
+
+__all__ = ("InputEvent", "KeyEvent", "RelEvent", "SynEvent", "AbsEvent", "event_factory")