python-libei 0.5.2__py3-none-any.whl → 0.6.1__py3-none-any.whl

libei/__init__.py

@@ -31,6 +31,6 @@ the full breakdown, including which features need which libei version.
 Beta: the API is not frozen.
 """
 
-__version__ = "0.5.2"
+__version__ = "0.6.1"
 
 __all__ = ["__version__"]

libei/_capi/libei.py

@@ -128,7 +128,7 @@ event_scroll_get_discrete_dy = lib.function(
 event_touch_get_id = lib.function("ei_event_touch_get_id", (c_void_p,), c_uint32)
 event_touch_get_x = lib.function("ei_event_touch_get_x", (c_void_p,), c_double)
 event_touch_get_y = lib.function("ei_event_touch_get_y", (c_void_p,), c_double)
-event_touch_get_is_cancel = lib.function(
+event_touch_get_is_cancel = lib.function(  # libei 1.4+
     "ei_event_touch_get_is_cancel", (c_void_p,), c_bool
 )
 event_text_get_utf8 = lib.function(  # libei 1.6+
@@ -141,7 +141,9 @@ event_text_get_keysym_is_press = lib.function(  # libei 1.6+
     "ei_event_text_get_keysym_is_press", (c_void_p,), c_bool
 )
 # Borrowed reference -- the event still owns it, so wrap() rather than adopt().
-event_pong_get_ping = lib.function("ei_event_pong_get_ping", (c_void_p,), c_void_p)
+event_pong_get_ping = lib.function(  # libei 1.4+
+    "ei_event_pong_get_ping", (c_void_p,), c_void_p
+)
 
 device_ref = lib.function("ei_device_ref", (c_void_p,), c_void_p)
 device_unref = lib.function("ei_device_unref", (c_void_p,), c_void_p)
@@ -236,7 +238,7 @@ touch_get_device = lib.function("ei_touch_get_device", (c_void_p,), c_void_p)
 touch_down = lib.function("ei_touch_down", (c_void_p, c_double, c_double), None)
 touch_motion = lib.function("ei_touch_motion", (c_void_p, c_double, c_double), None)
 touch_up = lib.function("ei_touch_up", (c_void_p,), None)
-touch_cancel = lib.function("ei_touch_cancel", (c_void_p,), None)
+touch_cancel = lib.function("ei_touch_cancel", (c_void_p,), None)  # libei 1.4+
 
 # ei_new_ping() returns an owned reference; ei_ping() then triggers the round
 # trip that comes back as an EI_EVENT_PONG.

libei/_capi/libeis.py

@@ -104,7 +104,7 @@ event_scroll_get_discrete_dy = lib.function(
 event_touch_get_id = lib.function("eis_event_touch_get_id", (c_void_p,), c_uint32)
 event_touch_get_x = lib.function("eis_event_touch_get_x", (c_void_p,), c_double)
 event_touch_get_y = lib.function("eis_event_touch_get_y", (c_void_p,), c_double)
-event_touch_get_is_cancel = lib.function(
+event_touch_get_is_cancel = lib.function(  # libei 1.4+
     "eis_event_touch_get_is_cancel", (c_void_p,), c_bool
 )
 event_text_get_utf8 = lib.function(  # libei 1.6+
@@ -117,14 +117,16 @@ event_text_get_keysym_is_press = lib.function(  # libei 1.6+
     "eis_event_text_get_keysym_is_press", (c_void_p,), c_bool
 )
 # Borrowed reference -- the event still owns it, so wrap() rather than adopt().
-event_pong_get_ping = lib.function("eis_event_pong_get_ping", (c_void_p,), c_void_p)
+event_pong_get_ping = lib.function(  # libei 1.4+
+    "eis_event_pong_get_ping", (c_void_p,), c_void_p
+)
 
 client_ref = lib.function("eis_client_ref", (c_void_p,), c_void_p)
 client_unref = lib.function("eis_client_unref", (c_void_p,), c_void_p)
 client_is_sender = lib.function("eis_client_is_sender", (c_void_p,), c_bool)
 # pid_t, i.e. a 32-bit signed int on Linux. Socket backend only, and
 # negative errno on failure.
-backend_socket_get_client_pid = lib.function(
+backend_socket_get_client_pid = lib.function(  # libei 1.5+
     "eis_backend_socket_get_client_pid", (c_void_p,), c_int32
 )
 client_get_name = lib.function("eis_client_get_name", (c_void_p,), c_char_p)
@@ -277,7 +279,7 @@ touch_get_device = lib.function("eis_touch_get_device", (c_void_p,), c_void_p)
 touch_down = lib.function("eis_touch_down", (c_void_p, c_double, c_double), None)
 touch_motion = lib.function("eis_touch_motion", (c_void_p, c_double, c_double), None)
 touch_up = lib.function("eis_touch_up", (c_void_p,), None)
-touch_cancel = lib.function("eis_touch_cancel", (c_void_p,), None)
+touch_cancel = lib.function("eis_touch_cancel", (c_void_p,), None)  # libei 1.4+
 
 ping = lib.function("eis_ping", (c_void_p,), None)  # libei 1.4+
 ping_get_id = lib.function("eis_ping_get_id", (c_void_p,), c_uint64)  # libei 1.4+

libei/_capi/loader.py

@@ -25,12 +25,19 @@ class LazyLibrary:
     """A ctypes.CDLL that only opens the library on first real use."""
 
     def __init__(self, soname: str) -> None:
+        """Remember the soname; nothing is opened until first use."""
         self._soname = soname
         self._lib: ctypes.CDLL | None = None
         self._load_error: OSError | None = None
         self._lock = threading.Lock()
+        self._declared: dict[str, tuple[tuple[type, ...], type | None]] = {}
 
     def _ensure_loaded(self) -> ctypes.CDLL:
+        """Return the opened library, opening it on first call.
+
+        Raises LibraryNotFoundError on every later call too after a failure:
+        the failed load is cached rather than retried.
+        """
         # Double-checked: the unlocked read is the fast path taken by every
         # call after the first, and the repeated check inside the lock is
         # what makes it safe -- two threads can both fall through the first
@@ -69,6 +76,21 @@ class LazyLibrary:
             return False
         return True
 
+    @property
+    def soname(self) -> str:
+        """The shared library this binds, as it is passed to ``dlopen``."""
+        return self._soname
+
+    @property
+    def declared(self) -> dict[str, tuple[tuple[type, ...], type | None]]:
+        """Every function bound so far: C name -> (argtypes, restype).
+
+        Read by the ABI tests, which compare it with the library's exports and
+        with the upstream headers. Declaring a binding records it here and does
+        nothing else -- the library is still not opened until a call.
+        """
+        return dict(self._declared)
+
     def function(
         self,
         name: str,
@@ -88,9 +110,11 @@ class LazyLibrary:
         # the dict is chosen only because "absent from the dict" already
         # means "not resolved yet", with no None sentinel to confuse with a
         # legitimately-None value.
+        self._declared[name] = (tuple(argtypes), restype)
         cache: dict[str, Any] = {}
 
         def call(*args: Any) -> Any:
+            """Resolve the C function on first call, then pass straight through."""
             # Resolution happens here, on first call, not at bind time --
             # that is the whole point of this module (see its docstring).
             bound = cache.get("f")
@@ -106,7 +130,23 @@ class LazyLibrary:
                 bound.argtypes = list(argtypes)
                 bound.restype = restype
                 cache["f"] = bound
-            return bound(*args)
+            try:
+                return bound(*args)
+            except ctypes.ArgumentError:
+                # ctypes turns *any* exception raised while converting an
+                # argument into an ArgumentError carrying only its text -- no
+                # __cause__, no __context__. For a released object that loses
+                # the RuntimeError its ``_as_parameter_`` raised, so a caller
+                # catching RuntimeError (as documented) would miss it. Ask the
+                # arguments again and re-raise the real one.
+                for arg in args:
+                    try:
+                        arg._as_parameter_  # noqa: B018 - evaluated for its error
+                    except RuntimeError as released:
+                        raise released from None
+                    except AttributeError:
+                        continue
+                raise
 
         call.__name__ = name
         return call

libei/_cobject.py

@@ -66,6 +66,7 @@ class CObject:
     _instances_lock: ClassVar[threading.RLock]
 
     def __init_subclass__(cls, **kwargs: Any) -> None:
+        """Give each wrapper hierarchy one identity cache, shared by subclasses."""
         super().__init_subclass__(**kwargs)
         # One cache per wrapper *hierarchy*, not per class. Only a root
         # wrapper class -- one whose only CObject ancestor is CObject
@@ -98,6 +99,7 @@ class CObject:
             cls._instances_lock = threading.RLock()
 
     def __init__(self, pointer: int, *, _adopt: bool = False) -> None:
+        """Take a reference on a non-NULL pointer and cache this wrapper for it."""
         if not pointer:
             raise ValueError(f"{type(self).__name__} cannot wrap a NULL pointer")
         self._pointer = pointer
@@ -121,6 +123,7 @@ class CObject:
 
     @property
     def _as_parameter_(self) -> int:
+        """The raw pointer ctypes passes to C -- an error once it is released."""
         if self._pointer == 0:
             raise RuntimeError(
                 f"{type(self).__name__} has already been released; "
@@ -159,6 +162,7 @@ class CObject:
 
     @classmethod
     def _get_or_create(cls: type[T], pointer: int | None, *, adopt: bool) -> T | None:
+        """The wrapper already caching this pointer, or a new one; None for NULL."""
         if not pointer:
             return None
         if not cls._wrappable:
@@ -232,6 +236,7 @@ class CObject:
         return cls._get_or_create(pointer, adopt=True)
 
     def __eq__(self, other: object) -> bool:
+        """Equal when the types match and the wrapped pointers are the same."""
         if not isinstance(other, CObject):
             return NotImplemented
         if type(self) is not type(other):
@@ -245,6 +250,7 @@ class CObject:
         return self._pointer == other._pointer
 
     def __hash__(self) -> int:
+        """Stable for the object's life: the original pointer, not the live one."""
         # Deliberately keyed on _hash_key, not _pointer: release() zeroes
         # _pointer, and an object whose hash changes mid-life vanishes
         # from any set or dict it was placed in. Two wrappers can share a

libei/ei.py

@@ -67,6 +67,7 @@ _emulating_sequence = itertools.count(1)
 
 
 def _next_emulating_sequence() -> int:
+    """The next emulating-event sequence number: 32-bit, and never 0."""
     # Masked into uint32 to match the C parameter. libei asks callers to
     # keep wraparound detection "reasonable"; skipping 0 keeps the value
     # away from anything that might read as unset.
@@ -192,6 +193,8 @@ class KeymapType(enum.IntEnum):
 
 
 class _LogPriority(enum.IntEnum):
+    """The log levels, as the integers the C library passes to its handler."""
+
     DEBUG = 10
     INFO = 20
     WARNING = 30
@@ -329,6 +332,7 @@ class Region(CObject):
     _unref_func = staticmethod(_capi.libei.region_unref)
 
     def __repr__(self) -> str:
+        """The size and position, as WxH+X+Y."""
         w, h = self.dimension
         x, y = self.position
         return f"<Region {w}x{h}+{x}+{y}>"
@@ -510,6 +514,7 @@ class Device(CObject):
     _unref_func = staticmethod(_capi.libei.device_unref)
 
     def __repr__(self) -> str:
+        """Name, device type and capabilities -- what tells two devices apart."""
         caps = "|".join(c.name or str(c.value) for c in self.capabilities)
         return f"<Device {self.name!r} {self.device_type.name} {caps}>"
 
@@ -692,6 +697,7 @@ class Seat(CObject):
     _unref_func = staticmethod(_capi.libei.seat_unref)
 
     def __repr__(self) -> str:
+        """The seat's name and capabilities."""
         caps = "|".join(c.name or str(c.value) for c in self.capabilities)
         return f"<Seat {self.name!r} {caps}>"
 
@@ -774,6 +780,7 @@ class Ping(CObject):
     _unref_func = staticmethod(_capi.libei.ping_unref)
 
     def __repr__(self) -> str:
+        """The ping's id, which is all a ping carries."""
         return f"<Ping {self.id}>"
 
     @property
@@ -801,6 +808,7 @@ class Event(CObject):
     _unref_func = staticmethod(_capi.libei.event_unref)
 
     def __repr__(self) -> str:
+        """The event type by name, or the raw value for one we do not model."""
         event_type = self.event_type
         label = event_type.name if isinstance(event_type, EventType) else event_type
         return f"<Event {label}>"
@@ -1008,6 +1016,11 @@ class Event(CObject):
 
 
 def _log_callback(_ei: int, priority: int, message: bytes, _context: int) -> None:
+    """Forward libei's log lines into the logging module.
+
+    Runs inside a ctypes callback, where an exception is printed to stderr
+    and then dropped, so every lookup below falls back rather than raising.
+    """
     # Look up the raw int, not _LogPriority(priority): constructing the
     # enum from an unrecognized value raises ValueError immediately, which
     # would happen *before* .get()'s default ever gets a chance to apply
@@ -1227,6 +1240,7 @@ class Sender(Context):
 
     @classmethod
     def _new(cls) -> int:
+        """A new sender from the C library, or an error if it returned NULL."""
         pointer = _capi.libei.new_sender(c_void_p(None))
         if not pointer:
             raise Error("ei_new_sender() returned NULL")
@@ -1250,6 +1264,7 @@ class Receiver(Context):
 
     @classmethod
     def _new(cls) -> int:
+        """A new receiver from the C library, or an error if it returned NULL."""
         pointer = _capi.libei.new_receiver(c_void_p(None))
         if not pointer:
             raise Error("ei_new_receiver() returned NULL")
@@ -1280,6 +1295,10 @@ __all__ = [
     "KeyEvent",
     "Keymap",
     "KeymapType",
+    # Imported rather than defined here: every call bound through
+    # _capi.libei can raise it, so a caller importing from this module
+    # catches it from here too -- see docs/troubleshooting.md.
+    "LibraryNotFoundError",
     "Ping",
     "PointerAbsoluteEvent",
     "PointerEvent",

libei/eis.py

@@ -159,6 +159,8 @@ class Flag(enum.IntEnum):
 
 
 class _LogPriority(enum.IntEnum):
+    """The log levels, as the integers libeis passes to its log handler."""
+
     DEBUG = 10
     INFO = 20
     WARNING = 30
@@ -456,6 +458,7 @@ class Device(CObject):
     _unref_func = staticmethod(_capi.libeis.device_unref)
 
     def __repr__(self) -> str:
+        """Name, device type and capabilities -- what tells two devices apart."""
         caps = "|".join(c.name or str(c.value) for c in self.capabilities)
         return f"<Device {self.name!r} {self.device_type.name} {caps}>"
 
@@ -709,6 +712,7 @@ class Seat(CObject):
     _unref_func = staticmethod(_capi.libeis.seat_unref)
 
     def __repr__(self) -> str:
+        """The seat's name and capabilities."""
         caps = "|".join(c.name or str(c.value) for c in self.capabilities)
         return f"<Seat {self.name!r} {caps}>"
 
@@ -770,6 +774,7 @@ class Client(CObject):
     _unref_func = staticmethod(_capi.libeis.client_unref)
 
     def __repr__(self) -> str:
+        """The client's name and which side of the protocol it is on."""
         return f"<Client {self.name!r} sender={self.is_sender}>"
 
     @property
@@ -840,6 +845,7 @@ class Ping(CObject):
     _unref_func = staticmethod(_capi.libeis.ping_unref)
 
     def __repr__(self) -> str:
+        """The ping's id, which is all a ping carries."""
         return f"<Ping {self.id}>"
 
     @property
@@ -867,6 +873,7 @@ class Event(CObject):
     _unref_func = staticmethod(_capi.libeis.event_unref)
 
     def __repr__(self) -> str:
+        """The event type by name, or the raw value for one we do not model."""
         event_type = self.event_type
         label = event_type.name if isinstance(event_type, EventType) else event_type
         return f"<Event {label}>"
@@ -1079,6 +1086,11 @@ class Event(CObject):
 
 
 def _log_callback(_eis: int, priority: int, message: bytes, _context: int) -> None:
+    """Forward libeis's log lines into the logging module.
+
+    The same constraint as ei.py's callback of that name: it runs inside a
+    ctypes callback, so it falls back rather than raising.
+    """
     # See ei.py's _log_callback: look up the raw int, not
     # _LogPriority(priority), which would raise ValueError before .get()'s
     # default could apply -- silently, since this runs inside a ctypes
@@ -1208,6 +1220,7 @@ class Eis(CObject):
 
     @classmethod
     def _new(cls) -> int:
+        """A new server from the C library, or an error if it returned NULL."""
         pointer = _capi.libeis.new(c_void_p(None))
         if not pointer:
             raise Error("eis_new() returned NULL")
@@ -1265,6 +1278,10 @@ __all__ = [
     "KeyEvent",
     "Keymap",
     "KeymapType",
+    # Imported rather than defined here: every call bound through
+    # _capi.libeis can raise it, so a caller importing from this module
+    # catches it from here too -- see docs/troubleshooting.md.
+    "LibraryNotFoundError",
     "Ping",
     "PointerAbsoluteEvent",
     "PointerEvent",

libei/oeffis.py

@@ -6,7 +6,7 @@ Negotiates an EIS connection through the
 This is the path a sandboxed or otherwise non-privileged client uses to get
 an EI socket: it asks the portal, the user is shown a consent dialog, and on
 approval this hands back a file descriptor to pass to
-:meth:`libei.ei.Sender.create_for_fd`.
+:meth:`libei.ei.Sender.create_for_fd`::
 
     oeffis = Oeffis.create(devices=DeviceType.POINTER)
     while True:
@@ -41,6 +41,7 @@ import logging
 import os
 
 from . import _capi
+from ._capi.loader import LibraryNotFoundError
 
 logger = logging.getLogger("libei.oeffis")
 
@@ -122,6 +123,11 @@ class Oeffis:
         self._state = _EventType.NONE
 
     def __del__(self) -> None:
+        """Release the session, closing the EIS fd if nobody claimed it.
+
+        Safe on a half-built object: __init__ can raise before every
+        attribute exists, and this still runs.
+        """
         # getattr() with defaults rather than plain attribute access:
         # __init__ raises DisconnectedError when oeffis_new() returns NULL,
         # and Python still calls __del__ on the half-built object, where
@@ -237,6 +243,11 @@ class Oeffis:
 __all__ = [
     "DeviceType",
     "DisconnectedError",
+    # Imported rather than defined here: every call bound through
+    # _capi.liboeffis can raise it -- Oeffis.create() on a machine with no
+    # liboeffis is the ordinary one -- so a caller importing from this
+    # module catches it from here too. See docs/troubleshooting.md.
+    "LibraryNotFoundError",
     "Oeffis",
     "SessionClosedError",
     "is_available",

libei/portal.py

@@ -21,7 +21,7 @@ should be handled by an application talking to DBus directly"
 (https://libinput.pages.freedesktop.org/libei/api/group__liboeffis.html).
 This module is that: the ``CreateSession`` -> ``SelectDevices`` -> ``Start``
 -> ``ConnectToEIS`` sequence driven directly, with ``persist_mode`` and
-``restore_token`` exposed as real parameters.
+``restore_token`` exposed as real parameters::
 
     with RemoteDesktopSession.negotiate(
         devices=DeviceType.POINTER | DeviceType.KEYBOARD,
@@ -427,18 +427,21 @@ def _request(
         params: Any,
         *_a: Any,
     ) -> None:
+        """Record the first reply and quit the loop; later replies are ignored."""
         if result:  # both subscriptions may fire; the first reply wins
             return
         result["code"], result["results"] = params.unpack()
         loop.quit()
 
     def on_timeout() -> bool:
+        """Stop the loop and record that it timed out rather than finished."""
         nonlocal timed_out
         timed_out = True
         loop.quit()
         return False  # one-shot; GLib removes the source when this is False
 
     def subscribe(path: str) -> None:
+        """Subscribe to Response on one path, keeping the handle alive."""
         subscriptions.append(
             connection.signal_subscribe(
                 busname,
@@ -685,12 +688,20 @@ class RemoteDesktopSession:
             self._connection = None
 
     def __enter__(self) -> RemoteDesktopSession:
+        """Return self: entering performs no action of its own."""
         return self
 
     def __exit__(self, *_exc: Any) -> None:
+        """Close the session on the way out, whatever happened."""
         self.close()
 
     def __del__(self) -> None:
+        """Close the fd only: __del__ can run during interpreter shutdown.
+
+        A synchronous D-Bus round trip there may hang or fail with nothing
+        left able to report it, so the D-Bus half of close() is deliberately
+        not attempted.
+        """
         # Deliberately only the fd, not the D-Bus half of close(): __del__
         # can run during interpreter shutdown, where a synchronous D-Bus
         # round trip may hang or fail in ways nothing can report. Closing an
@@ -1037,6 +1048,7 @@ def _wait_for_signal(
         params: Any,
         *_a: Any,
     ) -> None:
+        """Record the first matching signal; anything else is logged and dropped."""
         if result:  # a subscription that outlives its own wait can fire twice
             return
         args = params.unpack()
@@ -1058,6 +1070,7 @@ def _wait_for_signal(
         loop.quit()
 
     def on_timeout() -> bool:
+        """Stop the loop and record that it timed out rather than finished."""
         nonlocal timed_out
         timed_out = True
         loop.quit()
@@ -1141,8 +1154,8 @@ class InputCaptureSession:
     direction: instead of injecting synthetic input, this receives real
     input from the user's own devices once the compositor decides to divert
     it here. That decision is the whole point of the protocol and is never
-    this session's to make -- see :meth:`enable` and :meth:`
-    wait_for_activation`.
+    this session's to make -- see :meth:`enable` and
+    :meth:`wait_for_activation`.
 
     **Capturing is exclusive.** Once the compositor activates a capture,
     the events it captures stop reaching the desktop entirely and are sent
@@ -1163,12 +1176,13 @@ class InputCaptureSession:
     about, and this cannot release on a caller's behalf during cleanup
     without risking racing a capture that only just started.
 
-    **Never live-tested.** Every other class in this module that talks to a
-    real portal carries a hand-verification note in its own docstring; this
-    one does not, because verifying it means a developer clicking through
-    the consent dialog *and* accepting that their pointer will be diverted
-    away from their own desktop for the length of the test -- not something
-    to trigger without asking first, unlike everything else here. Designed
+    **Only half live-tested.** The negotiation -- consent dialog, EIS fd,
+    zones, ``Session.Close()`` -- was run against a real GNOME session on
+    libei's own hand-verification terms (see
+    ``docs/developers/verification.md``); the *capture* half never has been,
+    because verifying it means a developer accepting that their pointer will
+    be diverted away from their own desktop for the length of the test -- not
+    something to trigger without asking first, unlike everything else here. Designed
     against ``/usr/share/dbus-1/interfaces/org.freedesktop.portal.
     InputCapture.xml`` (the shipped portal spec, not the header alone) and
     unit-tested against a fake connection reproducing that spec's documented
@@ -1487,12 +1501,15 @@ class InputCaptureSession:
             self._connection = None
 
     def __enter__(self) -> InputCaptureSession:
+        """Return self: entering performs no action of its own."""
         return self
 
     def __exit__(self, *_exc: Any) -> None:
+        """Close the session on the way out, whatever happened."""
         self.close()
 
     def __del__(self) -> None:
+        """Close the fd only, for the reason RemoteDesktopSession.__del__ gives."""
         # See RemoteDesktopSession.__del__ for why this closes only the fd.
         if getattr(self, "_eis_fd_claimed", True):
             return

{python_libei-0.5.2.dist-info → python_libei-0.6.1.dist-info}/METADATA

@@ -1,18 +1,21 @@
 Metadata-Version: 2.4
 Name: python-libei
-Version: 0.5.2
-Summary: Inject and receive input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis
+Version: 0.6.1
+Summary: Inject, receive and capture input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis, plus the RemoteDesktop and InputCapture portals
 Author: Dennis K. Paulsen
 License-Expression: MIT
 Project-URL: homepage, https://github.com/ctrondlp/python-libei
 Project-URL: repository, https://github.com/ctrondlp/python-libei
 Project-URL: issues, https://github.com/ctrondlp/python-libei/issues
+Project-URL: documentation, https://github.com/ctrondlp/python-libei/tree/main/docs
+Project-URL: pyguitest, https://github.com/ctrondlp/pyguitest
 Project-URL: changelog, https://github.com/ctrondlp/python-libei/blob/main/CHANGELOG.md
-Keywords: wayland,libei,libeis,liboeffis,input,input-emulation,emulated-input,portal,xdg-desktop-portal,remote-desktop,automation,gui-testing,accessibility,ctypes
+Keywords: wayland,libei,libeis,liboeffis,input,input-emulation,emulated-input,input-capture,eis,portal,xdg-desktop-portal,remote-desktop,automation,gui-testing,accessibility,ctypes
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: POSIX :: BSD :: FreeBSD
 Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: POSIX
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.10
@@ -37,6 +40,10 @@ Dynamic: license-file
 
 # python-libei
 
+[![CI](https://github.com/ctrondlp/python-libei/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ctrondlp/python-libei/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/python-libei)](https://pypi.org/project/python-libei/)
+[![License](https://img.shields.io/pypi/l/python-libei)](https://github.com/ctrondlp/python-libei/blob/main/LICENSE)
+
 Python bindings for [libei, libeis and liboeffis](https://libinput.pages.freedesktop.org/libei/) —
 the Wayland input-emulation libraries. Use this to **move the pointer, click,
 type, or scroll on a Wayland desktop** from Python, the way `xdotool` did on
@@ -49,8 +56,11 @@ device.start_emulating().pointer_motion(5, 0).frame().stop_emulating()
 ```
 
 **The one concept:** events queue up, and **`frame()` is what sends them** as
-one logical hardware event. Forget it and nothing happens — no exception, no
-warning, no movement. Fill the package, then post it.
+one logical hardware event. Forget it and the motion is usually lost — no
+exception, no warning, no movement. (Ending the chain with `stop_emulating()`
+makes libei frame the queue for you, but it logs an error-level `Bug:` line
+when it does; see [Things that will bite you](#things-that-will-bite-you).) Fill
+the package, then post it.
 
 New here? [docs/getting-started.md](docs/getting-started.md) is install
 through a first real pointer motion, in five minutes.
@@ -92,8 +102,8 @@ than a widget-tree back door:
 
 ## Which API do I need?
 
-Five modules, and most callers need exactly two of them: `oeffis` or `portal`
-to get permission, then `ei` to inject.
+Four modules (`ei`, `eis`, `oeffis`, `portal`), and most callers need exactly
+two of them: `oeffis` or `portal` to get permission, then `ei` to inject.
 
 | You want to… | Use | Notes |
 | --- | --- | --- |
@@ -101,13 +111,18 @@ to get permission, then `ei` to inject.
 | **Consume input** from a compositor | `libei.ei` → `Receiver` | Compositor-side or input-capture code; same connection dance |
 | **Get permission**, simply | `libei.oeffis` | One call, pollable fd, no dependencies. The consent dialog appears on **every** run |
 | **Get permission**, and not be asked again | `libei.portal` | Same handshake over D-Bus directly, with `persist_mode` / `restore_token`. Needs PyGObject |
+| **Capture the user's real input** | `libei.portal` → `InputCaptureSession` | The read direction, through the InputCapture portal: once the compositor decides to, the user's pointer and keyboard are diverted to you over EIS. Exclusive while active, so hold it briefly. Only its negotiation half has been run against a real desktop — see [verification](docs/developers/verification.md) |
 | **Be the server**, for tests or a compositor | `libei.eis` | Drives your client code with no real compositor and no consent dialog |
 
-Each module has `is_available()`, an `Error` exception, and an `EventType` /
-`DeviceCapability` enum. `ei` and `eis` also share the shapes around them:
-`Device`, `Seat`, `Region`, `Keymap`, `Touch`, `Ping`, `Event`, and the frozen
-dataclasses its accessors return. The package ships `py.typed`, so callers
-type-check against real annotations rather than `Any`.
+Each module has `is_available()`. `ei` and `eis` share the shapes around them:
+an `Error` exception, an `EventType` and `DeviceCapability` enum, and `Device`,
+`Seat`, `Region`, `Keymap`, `Touch`, `Ping`, `Event` with the frozen dataclasses
+its accessors return. `oeffis` and `portal` are smaller — `DeviceType`, no
+`EventType` or `DeviceCapability`, `Activation` as the one frozen result a
+portal wait hands back, and their own exception classes rather than an `Error`.
+[docs/troubleshooting.md](docs/troubleshooting.md) names every class they raise.
+The package ships `py.typed`, so callers type-check against real
+annotations rather than `Any`.
 
 ## What's implemented
 
@@ -135,8 +150,9 @@ because a skimming reader could otherwise take them as supported. 1.6.0's own
 `enum ei_device_capability` stops at `TEXT`, and its `enum ei_event_type`
 stops at `EI_EVENT_TEXT_UTF8` — so the swipe/pinch/hold/stylus members of
 `EventType` cannot arrive either. The values here match upstream `main`
-exactly, so they are ready for whatever release adds them. The 22
-gesture/stylus accessor functions `main` adds are deliberately not bound:
+exactly, so they are ready for whatever release adds them. The gesture
+and stylus functions `main` adds -- 46 in libei and 51 in libeis against
+1.6.0's headers, counted 2026-09-30 -- are deliberately not bound:
 nothing that ships today exports them, so nothing here could be verified
 against a real library, which is the bar every other binding in this package
 was held to.
@@ -149,14 +165,16 @@ Beyond sending input, the wrapper also covers ping/pong round trips
 (`Device.keymap`), region mapping ids and coordinate conversion,
 `Context.disconnect()`, `Context.peek_event_type()`, and
 `Seat.request_device()`. On the server side, `libei.eis` mirrors all of it and
-adds `Eis.set_flag()` and `Client.pid`. Underneath, the ctypes layer binds 250
+adds `Eis.set_flag()` (with the `Flag` values it takes), `Client.pid`, and
+`Device.configure()` with the `ConfigureRegion` descriptions it accepts.
+Underneath, the ctypes layer binds 250
 of the 302 functions the three libraries export as of 1.6.0; what is left out,
 and why, is in
 [docs/developers/architecture.md](docs/developers/architecture.md#what-is-bound-and-what-is-deliberately-not).
 
 ## Status
 
-Beta (`0.5.2`), published on [PyPI](https://pypi.org/project/python-libei/)
+Beta (`0.6.1`), published on [PyPI](https://pypi.org/project/python-libei/)
 since `0.1.0`, and **the API is not frozen** — expect renames before 1.0.
 
 The injection path is exercised end to end against the real libraries by the
@@ -197,9 +215,13 @@ Exactly what was run, when, and against which versions:
 - libei 1.0.0 or newer for the core: connecting, binding a seat, and
   sending pointer, button, keyboard, scroll and touch input all use symbols
   that have existed with a stable signature since 1.0.0, and upstream keeps
-  API/ABI back-compatible within the 1.x series. Only 1.5.0 and 1.6.0 have
-  actually been run against -- 1.6.0 on both Fedora 44 and FreeBSD 15, where
-  the injection path passes the full suite with nothing skipped.
+  API/ABI back-compatible within the 1.x series. The suite has been run
+  against 1.2.1 (Ubuntu 24.04, in CI) and 1.6.0 -- the latter on Fedora 44 and
+  45 and FreeBSD 15, where the injection path passes the full suite with
+  nothing skipped. Every binding's name, argument types and return type, and
+  every enum value, is also checked against the upstream headers of 1.0.0,
+  1.2.1, 1.4.0, 1.5.0 and 1.6.0 (`tests/test_abi.py`), which is the only
+  coverage 1.0.0, 1.4.0 and 1.5.0 have had.
 
   Newer libei buys you more, per feature:
 
@@ -357,8 +379,12 @@ All four, with working code:
   soon as the loop moves on, and using it afterwards raises `RuntimeError`.
   Objects you pull *off* an event (`event.device`, `event.seat`) are safe to
   keep — copy out `event.pointer_event` and friends rather than the event.
-- **`frame()` or nothing happens.** Events queue up until a `frame()` commits
-  them.
+- **`frame()` or the input is lost.** Events queue up until a `frame()` commits
+  them, and queued events that are never framed are dropped without an
+  exception or a log line. The one exception is a chain that ends in
+  `stop_emulating()`: libei frames what is queued, delivers it, and logs
+  `Bug: ei_device_stop_emulating: missing call to ei_device_frame()` at error
+  level. Measured against libei 1.2.1 and 1.6.0; don't rely on it.
 - **`bind()` needs at least one capability.** Binding an empty set sends
   nothing, so the device you are waiting for never arrives; this raises
   `ValueError` rather than hanging.
@@ -367,20 +393,22 @@ All four, with working code:
 - **One seat can resume several devices.** Bind both `POINTER` and
   `POINTER_ABSOLUTE` and GNOME gives you two, relative first. Taking
   whichever resumes first is a coin flip — select on `device.capabilities`
-  instead. Sending an event the device lacks the capability for is silently
-  ignored, which makes this look like the injection simply not working.
+  instead. Sending an event the device lacks the capability for is dropped with
+  no exception — libei only logs an error-level `Bug: ... device is not a
+  keyboard` line — which makes this look like the injection simply not working.
 - **Read the accessor that matches the event type.** `event.key_event` on a
   `POINTER_MOTION` event raises `TypeError` naming both types. libei itself
   would have returned `KeyEvent(key=0, is_press=False)` — a real-looking
-  value — while logging a `Bug:` line the caller never sees, so branch on
-  `event_type` first. `TOUCH_UP` has its own `touch_up_event`, since it
+  value — and raised nothing, only logging a `Bug:` line at error level, so
+  branch on `event_type` first. `TOUCH_UP` has its own `touch_up_event`, since it
   carries no coordinates.
 - **`GESTURES` and `STYLUS` are not in any released libei.** They match
   upstream `main` and are here ready for it, but 1.6.0's capability enum
   stops at `TEXT`. Binding them against a shipping library silently does
   nothing — no error, no device, no events.
 
-Nearly all of these fail *silently*, which is why
+Nearly all of these fail without raising — some only log an error-level `Bug:`
+line, some not even that — which is why
 [docs/troubleshooting.md](docs/troubleshooting.md) is a checklist rather than
 a list of error messages. Start there when nothing happens.
 
@@ -394,8 +422,10 @@ a list of error messages. Start there when nothing happens.
   happens" checklist
 - [docs/vs-snegg.md](docs/vs-snegg.md) — how this differs from the reference
   bindings, and two signature issues found by cross-checking the C source
-- [docs/developers/](docs/developers/) — the four-layer architecture, and what
-  has actually been verified against which libei versions
+- [docs/developers/architecture.md](docs/developers/architecture.md) and
+  [docs/developers/verification.md](docs/developers/verification.md) — the
+  four-layer architecture, and what has actually been verified against which
+  libei versions
 - [CONTRIBUTING.md](CONTRIBUTING.md) — setup, checks, testing against an old
   libei, releasing
 

python_libei-0.6.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+libei/__init__.py,sha256=OP-aoBP8bXNhL8q3gXxVL4FtWLhVyaBlmoQEInBdhp4,1858
+libei/_cobject.py,sha256=XjbUNJpZ87jAyPWh6dmRslk6cMy831oMRFhWmfjLDFo,13344
+libei/ei.py,sha256=W4akKc_BNVfL0FroSXLGD1Z_L3OmYjZT5QDHNnEtMP8,49367
+libei/eis.py,sha256=X_umAaAAbAMC9d2RdnMReeJZI61WsnKz3cySY5YrGr0,45841
+libei/oeffis.py,sha256=gJHR90s9VhQrgkjWUMDx-lxZ8qKxkttnqbx_xo-7oxs,10035
+libei/portal.py,sha256=XC_FsKueIpcmAPZ4TDXJgFhucJNeMEO2byTJHG3GMmI,69756
+libei/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+libei/_capi/__init__.py,sha256=raISSWSV9hAcE92DcLCz-vUb1IPcsmxRZaS-iAoQJBE,211
+libei/_capi/libei.py,sha256=qsccHa_komCxtvPYi6AobszhFbEG2qA8QYJJVr8SaGM,11356
+libei/_capi/libeis.py,sha256=C_Uh7DwNncFC8A4wuMhviAj5C_TUmKHtLJYq0Qhhz1E,13142
+libei/_capi/liboeffis.py,sha256=V8jdmJm3qOQUzzNiCAXt4Jr2JY11Y4-w6NIfIxbxGI4,1218
+libei/_capi/loader.py,sha256=xW67uk35ckgeFaheDGrHC05ZM5w_cxBGvX5lG_GUSu8,6625
+python_libei-0.6.1.dist-info/licenses/LICENSE,sha256=l6xbMU6Y-JZDzmBciBj-J5t6h6jNg_Bcyp4bHxDepqU,1074
+python_libei-0.6.1.dist-info/METADATA,sha256=nV9GTh7ArlrDPXyPTt4fGHJiPP22J9bmA2e8v-mDgp0,22728
+python_libei-0.6.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+python_libei-0.6.1.dist-info/top_level.txt,sha256=_DQXzGjDsUBENI_cNkiOxPB4xi8coCbQS1lq18FMudQ,6
+python_libei-0.6.1.dist-info/RECORD,,

python_libei-0.5.2.dist-info/RECORD

@@ -1,17 +0,0 @@
-libei/__init__.py,sha256=SwaEhWSSGzxTEOqlW6PsfGC24QWz2A2FUrktq4AztTM,1858
-libei/_cobject.py,sha256=msrbviABSWjc5fKsXHSCg7nQ0Y4Etcq_Dkh0fblW-sY,12845
-libei/ei.py,sha256=5LAvMDOYS0AdwEHpKKZ3Anky5yIcDvr926A7ydL_Vmk,48289
-libei/eis.py,sha256=HepGyded_soT84GUu66iSz9IcGP6Bm_Y2750-YK9GDg,44912
-libei/oeffis.py,sha256=MhUPKD2Sk2OzKikaztNoL5k1CresqjdY7EPWuCPCMIM,9477
-libei/portal.py,sha256=dGOX5Rf5slbEKq-Ie0od4_ZgStd8UruwMbSnaOO2QI8,68682
-libei/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-libei/_capi/__init__.py,sha256=raISSWSV9hAcE92DcLCz-vUb1IPcsmxRZaS-iAoQJBE,211
-libei/_capi/libei.py,sha256=gpp42bhqPonhVD2zmFWCl4rdk_lm4XvD_7W2Rw5RsuI,11308
-libei/_capi/libeis.py,sha256=jQR0Z0YN9qa71mAcSJ__-UaoF8PsVsBs8OXwjfqstFk,13080
-libei/_capi/liboeffis.py,sha256=V8jdmJm3qOQUzzNiCAXt4Jr2JY11Y4-w6NIfIxbxGI4,1218
-libei/_capi/loader.py,sha256=k7fb_Nz0fg5QkuLJ_duKXj8bESSktLQ2ZyS5LNQ5v2I,4689
-python_libei-0.5.2.dist-info/licenses/LICENSE,sha256=l6xbMU6Y-JZDzmBciBj-J5t6h6jNg_Bcyp4bHxDepqU,1074
-python_libei-0.5.2.dist-info/METADATA,sha256=IIL9EKM_LBc2PoqLzGQKu5sZHQ9l4ivyH5W3uq61CW0,20086
-python_libei-0.5.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_libei-0.5.2.dist-info/top_level.txt,sha256=_DQXzGjDsUBENI_cNkiOxPB4xi8coCbQS1lq18FMudQ,6
-python_libei-0.5.2.dist-info/RECORD,,