python-libei 0.5.0__py3-none-any.whl → 0.5.2__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.0"
+__version__ = "0.5.2"
 
 __all__ = ["__version__"]

libei/_capi/__init__.py

@@ -1,5 +1,8 @@
-"""Low-level ctypes bindings. Not part of the public API -- use
-``libei.ei``, ``libei.eis`` and ``libei.oeffis`` instead."""
+"""Low-level ctypes bindings.
+
+Not part of the public API -- use ``libei.ei``, ``libei.eis`` and
+``libei.oeffis`` instead.
+"""
 
 from . import libei, libeis, liboeffis
 

libei/ei.py

@@ -87,6 +87,7 @@ class Error(Exception):
     """
 
     def __init__(self, message: str, errno: int | None = None) -> None:
+        """Record the failure message and, where libei reported one, errno."""
         super().__init__(message)
         self.message = message
         self.errno = errno
@@ -199,6 +200,12 @@ class _LogPriority(enum.IntEnum):
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class XkbModifiersEvent:
+    """XKB modifier state from a KEYBOARD_MODIFIERS event.
+
+    ``depressed``/``latched``/``locked`` are XKB's own mod-state bitmasks;
+    ``group`` is the active keyboard layout group.
+    """
+
     depressed: int
     latched: int
     locked: int
@@ -207,48 +214,76 @@ class XkbModifiersEvent:
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class KeyEvent:
+    """Key code and press state from a KEYBOARD_KEY event.
+
+    ``key`` is a Linux ``KEY_*`` code, the same numbering
+    :meth:`Device.keyboard_key` sends.
+    """
+
     key: int
     is_press: bool
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class ButtonEvent:
+    """Button code and press state from a BUTTON_BUTTON event.
+
+    ``button`` is a Linux ``BTN_*`` code, the same numbering
+    :meth:`Device.button` sends.
+    """
+
     button: int
     is_press: bool
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class PointerEvent:
+    """Relative motion deltas, in logical pixels, from a POINTER_MOTION event."""
+
     dx: float
     dy: float
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class PointerAbsoluteEvent:
+    """Absolute position from a POINTER_MOTION_ABSOLUTE event.
+
+    In the logical pixel space of the :class:`Region` the emitting device
+    covers -- see :meth:`Event.pointer_absolute_event`.
+    """
+
     x: float
     y: float
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class ScrollEvent:
+    """Smooth scroll deltas from a SCROLL_DELTA event."""
+
     dx: float
     dy: float
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class ScrollDiscreteEvent:
+    """Detent scroll deltas (120 per detent) from a SCROLL_DISCRETE event."""
+
     dx: int
     dy: int
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class ScrollStopEvent:
+    """Which axes stopped scrolling, from a SCROLL_STOP/SCROLL_CANCEL event."""
+
     stop_x: bool
     stop_y: bool
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class TouchEvent:
+    """Touch id and position from a TOUCH_DOWN or TOUCH_MOTION event."""
+
     touchid: int
     x: float
     y: float
@@ -256,17 +291,26 @@ class TouchEvent:
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class TouchUpEvent:
+    """Touch id and cancellation flag from a TOUCH_UP event.
+
+    See :meth:`Event.touch_up_event` for when ``is_cancel`` is trustworthy.
+    """
+
     touchid: int
     is_cancel: bool
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class TextUtf8Event:
+    """UTF-8 text carried by a TEXT_UTF8 event."""
+
     text: str
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class TextKeysymEvent:
+    """Keysym and press state from a TEXT_KEYSYM event."""
+
     keysym: int
     is_press: bool
 
@@ -545,9 +589,10 @@ class Device(CObject):
         return self
 
     def frame(self, timestamp: int | None = None) -> Device:
-        """Commit the events queued since the last frame as one logical
-        hardware event. ``timestamp`` defaults to the context's current
-        time."""
+        """Commit the events queued since the last frame as one logical hardware event.
+
+        ``timestamp`` defaults to the context's current time.
+        """
         if timestamp is None:
             timestamp = _capi.libei.now(_capi.libei.device_get_context(self))
         _capi.libei.device_frame(self, timestamp)
@@ -564,8 +609,10 @@ class Device(CObject):
         return self
 
     def button(self, button: int, is_press: bool) -> Device:
-        """Queue a button press or release. ``button`` is a Linux
-        ``BTN_*`` code (e.g. ``0x110`` for ``BTN_LEFT``)."""
+        """Queue a button press or release.
+
+        ``button`` is a Linux ``BTN_*`` code (e.g. ``0x110`` for ``BTN_LEFT``).
+        """
         _capi.libei.device_button_button(self, button, is_press)
         return self
 
@@ -760,8 +807,11 @@ class Event(CObject):
 
     @property
     def event_type(self) -> EventType | int:
-        """The event's type, or a raw int for a value newer than this
-        package's :class:`EventType` table -- see its docstring."""
+        """The event's type.
+
+        Returns a raw int for a value newer than this package's
+        :class:`EventType` table -- see its docstring.
+        """
         raw = _capi.libei.event_get_type(self)
         try:
             return EventType(raw)
@@ -1009,11 +1059,14 @@ class Context(CObject):
     _wrappable = False
 
     def __init__(self, pointer: int, *, _adopt: bool = False) -> None:
-        # _adopt is accepted and forwarded for signature consistency with
-        # CObject, but with _wrappable = False, _get_or_create() never
-        # actually reaches this constructor -- Context (and Sender/
-        # Receiver) are always built directly via cls(cls._new()) in
-        # create_for_fd()/create_for_socket().
+        """Wrap a freshly created ``struct ei *`` and arm its log handler.
+
+        _adopt is accepted and forwarded for signature consistency with
+        CObject, but with _wrappable = False, _get_or_create() never
+        actually reaches this constructor -- Context (and Sender/
+        Receiver) are always built directly via cls(cls._new()) in
+        create_for_fd()/create_for_socket().
+        """
         super().__init__(pointer, _adopt=_adopt)
         self._name: str | None = None
         _capi.libei.log_set_handler(self, _log_handler)
@@ -1081,7 +1134,8 @@ class Context(CObject):
         """Use an already-connected socket as the transport.
 
         libei takes ownership of a raw int fd and closes it itself; a file
-        object is duplicated first, so the caller's own object stays valid."""
+        object is duplicated first, so the caller's own object stays valid.
+        """
         # ei_setup_backend_fd() takes ownership of the fd and will close it
         # itself. A raw int is assumed to already be one the caller is
         # handing off (matching what eis.Eis.add_client()/oeffis.eis_fd
@@ -1099,7 +1153,8 @@ class Context(CObject):
         """Connect to an EIS socket by path.
 
         ``None`` uses ``$LIBEI_SOCKET``; a relative path is resolved
-        against ``$XDG_RUNTIME_DIR``."""
+        against ``$XDG_RUNTIME_DIR``.
+        """
         encoded = os.fspath(path).encode("utf-8") if path else None
         err = _capi.libei.setup_backend_socket(self, encoded)
         if err < 0:
@@ -1162,7 +1217,8 @@ class Context(CObject):
         """Read from the connection and queue any events that arrive.
 
         Call this before iterating :attr:`events`, which only drains what
-        is already queued."""
+        is already queued.
+        """
         _capi.libei.dispatch(self)
 
 

libei/eis.py

@@ -55,6 +55,7 @@ class Error(Exception):
     """
 
     def __init__(self, message: str, errno: int | None = None) -> None:
+        """Record the failure message and, where libeis reported one, errno."""
         super().__init__(message)
         self.message = message
         self.errno = errno
@@ -166,48 +167,75 @@ class _LogPriority(enum.IntEnum):
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class KeyEvent:
+    """Key code and press state received on a KEYBOARD_KEY event.
+
+    ``key`` is a Linux ``KEY_*`` code, as sent by the client's
+    ``ei.Device.keyboard_key``.
+    """
+
     key: int
     is_press: bool
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class ButtonEvent:
+    """Button code and press state received on a BUTTON_BUTTON event.
+
+    ``button`` is a Linux ``BTN_*`` code, as sent by the client's
+    ``ei.Device.button``.
+    """
+
     button: int
     is_press: bool
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class PointerEvent:
+    """Relative motion deltas, in logical pixels, from a POINTER_MOTION event."""
+
     dx: float
     dy: float
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class PointerAbsoluteEvent:
+    """Absolute position from a POINTER_MOTION_ABSOLUTE event.
+
+    In the logical pixel space of the region the sending device covers.
+    """
+
     x: float
     y: float
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class ScrollEvent:
+    """Smooth scroll deltas from a SCROLL_DELTA event."""
+
     dx: float
     dy: float
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class ScrollDiscreteEvent:
+    """Detent scroll deltas (120 per detent) from a SCROLL_DISCRETE event."""
+
     dx: int
     dy: int
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class ScrollStopEvent:
+    """Which axes stopped scrolling, from a SCROLL_STOP/SCROLL_CANCEL event."""
+
     stop_x: bool
     stop_y: bool
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class TouchEvent:
+    """Touch id and position from a TOUCH_DOWN or TOUCH_MOTION event."""
+
     touchid: int
     x: float
     y: float
@@ -215,17 +243,23 @@ class TouchEvent:
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class TouchUpEvent:
+    """Touch id and cancellation flag from a TOUCH_UP event."""
+
     touchid: int
     is_cancel: bool
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class TextUtf8Event:
+    """UTF-8 text carried by a TEXT_UTF8 event."""
+
     text: str
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
 class TextKeysymEvent:
+    """Keysym and press state from a TEXT_KEYSYM event."""
+
     keysym: int
     is_press: bool
 
@@ -576,8 +610,10 @@ class Device(CObject):
         return self
 
     def frame(self, timestamp: int | None = None) -> Device:
-        """Commit the events queued since the last frame as one logical
-        hardware event. ``timestamp`` defaults to the context's current time."""
+        """Commit the events queued since the last frame as one logical hardware event.
+
+        ``timestamp`` defaults to the context's current time.
+        """
         if timestamp is None:
             timestamp = _capi.libeis.now(_capi.libeis.device_get_context(self))
         _capi.libeis.device_frame(self, timestamp)
@@ -837,8 +873,11 @@ class Event(CObject):
 
     @property
     def event_type(self) -> EventType | int:
-        """The event's type, or a raw int for a value newer than this
-        package's :class:`EventType` table -- see its docstring."""
+        """The event's type.
+
+        Returns a raw int for a value newer than this package's
+        :class:`EventType` table -- see its docstring.
+        """
         raw = _capi.libeis.event_get_type(self)
         try:
             return EventType(raw)
@@ -1069,10 +1108,13 @@ class Eis(CObject):
     _wrappable = False
 
     def __init__(self, pointer: int, *, _adopt: bool = False) -> None:
-        # _adopt is accepted and forwarded for signature consistency with
-        # CObject, but with _wrappable = False, _get_or_create() never
-        # actually reaches this constructor -- Eis is always built directly
-        # via cls(cls._new()) in create_for_fd().
+        """Wrap a freshly created ``struct eis *`` and arm its log handler.
+
+        _adopt is accepted and forwarded for signature consistency with
+        CObject, but with _wrappable = False, _get_or_create() never
+        actually reaches this constructor -- Eis is always built directly
+        via cls(cls._new()) in create_for_fd().
+        """
         super().__init__(pointer, _adopt=_adopt)
         _capi.libeis.log_set_handler(self, _log_handler)
         _capi.libeis.log_set_priority(self, _LogPriority.DEBUG)
@@ -1146,7 +1188,8 @@ class Eis(CObject):
         """Read from the connection and queue any events that arrive.
 
         Call this before iterating :attr:`events`, which only drains what
-        is already queued."""
+        is already queued.
+        """
         _capi.libeis.dispatch(self)
 
     def add_client(self) -> int:
@@ -1172,14 +1215,16 @@ class Eis(CObject):
 
     @classmethod
     def create_for_fd(cls, flags: Sequence[Flag] = ()) -> Eis:
-        """Create a server using the fd backend -- the one real compositors
-        use, since it keeps each client's fd private rather than exposing a
-        connectable socket path. Call :meth:`add_client` once per
-        connection you want to accept.
+        """Create a server using the fd backend.
+
+        The one real compositors use, since it keeps each client's fd
+        private rather than exposing a connectable socket path. Call
+        :meth:`add_client` once per connection you want to accept.
 
         ``flags`` are applied here rather than left to the caller because
         :meth:`set_flag` has to run before the backend is set up, and this
-        method does both."""
+        method does both.
+        """
         server = cls(cls._new())
         for flag in flags:
             server.set_flag(flag)
@@ -1190,9 +1235,12 @@ class Eis(CObject):
 
     @classmethod
     def create_for_socket(cls, path: Path, flags: Sequence[Flag] = ()) -> Eis:
-        """Create a server listening on a Unix socket, as a compositor
-        would (this is the path a real ``ei_setup_backend_socket()`` client
-        connects to). See :meth:`create_for_fd` on ``flags``."""
+        """Create a server listening on a Unix socket.
+
+        As a compositor would (this is the path a real
+        ``ei_setup_backend_socket()`` client connects to). See
+        :meth:`create_for_fd` on ``flags``.
+        """
         server = cls(cls._new())
         for flag in flags:
             server.set_flag(flag)

libei/oeffis.py

@@ -1,5 +1,7 @@
-"""Pythonic wrapper around liboeffis -- negotiates an EIS connection through
-the ``org.freedesktop.portal.RemoteDesktop`` XDG desktop portal.
+"""Pythonic wrapper around liboeffis.
+
+Negotiates an EIS connection through the
+``org.freedesktop.portal.RemoteDesktop`` XDG desktop portal.
 
 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
@@ -52,6 +54,7 @@ class DisconnectedError(Exception):
     """The portal session ended unexpectedly (error, or denied by the user)."""
 
     def __init__(self, message: str | None) -> None:
+        """Record why the session ended."""
         super().__init__(message)
         self.message = message
 
@@ -60,6 +63,7 @@ class SessionClosedError(DisconnectedError):
     """The portal explicitly closed the session (not necessarily an error)."""
 
     def __init__(self) -> None:
+        """Build the fixed "Session closed" message."""
         super().__init__(message="Session closed")
 
 
@@ -100,6 +104,7 @@ class Oeffis:
     """
 
     def __init__(self) -> None:
+        """Create the underlying liboeffis context (no portal call yet)."""
         pointer = _capi.liboeffis.new(None)
         if not pointer:
             raise DisconnectedError("oeffis_new() returned NULL")

libei/portal.py

@@ -1,5 +1,7 @@
-"""Negotiate an EIS connection by driving a portal directly over D-Bus,
-rather than through :mod:`libei.oeffis`.
+"""Negotiate an EIS connection by driving a portal directly over D-Bus.
+
+Not through :mod:`libei.oeffis` -- see that module instead for the simpler,
+liboeffis-backed path.
 
 Two portals, two directions. :class:`RemoteDesktopSession` negotiates
 ``org.freedesktop.portal.RemoteDesktop`` to *inject* input; below it,
@@ -69,6 +71,7 @@ Three things worth knowing before building on this:
 
 from __future__ import annotations
 
+import contextlib
 import enum
 import logging
 import os
@@ -104,7 +107,7 @@ _MIN_REMOTE_DESKTOP_VERSION = 2  # ConnectToEIS needs v2+
 _MIN_INPUT_CAPTURE_VERSION = 2  # CreateSession2 is a v2-only method
 
 _DEFAULT_TIMEOUT = 60.0
-"""Seconds to wait for one portal round trip. Generous, because a human has
+"""Seconds to wait for one portal round trip. Generous, because a user has
 to see and answer the consent dialog `Start` raises -- but bounded, because
 the alternative is a caller wedged forever if the portal dies after
 accepting the call and before sending its `Response`."""
@@ -156,11 +159,12 @@ class PortalTimeoutError(PortalError):
 
     Distinct from a decline: the portal accepted the call and then never
     sent its ``Response`` signal. Most often the consent dialog is simply
-    still waiting for a human, so raise the timeout rather than treating
+    still waiting for a user, so raise the timeout rather than treating
     this as a failure if that is expected.
     """
 
     def __init__(self, step: str, timeout: float) -> None:
+        """Name which step timed out and after how long."""
         super().__init__(f"{step} did not answer within {timeout:g}s")
         self.step = step
         self.timeout = timeout
@@ -175,6 +179,7 @@ class PortalDeniedError(PortalError):
     """
 
     def __init__(self, step: str, message: str | None = None) -> None:
+        """Name which step was refused and, where the portal gave one, why."""
         super().__init__(message or f"{step} was not approved")
         self.step = step
         self.message = message
@@ -481,10 +486,16 @@ def _request(
             try:
                 loop.run()
             finally:
-                # Removing an already-fired one-shot source is harmless
-                # (GLib warns at most); leaking a live one holds a reference
-                # to this closure and fires it into a dead loop later.
-                GLib.source_remove(timeout_source)
+                # on_timeout() returns False, which is GLib's own signal to
+                # deregister a fired one-shot source -- removing it again
+                # here trips a real "Source ID N was not found when
+                # attempting to remove it" warning, the same bug already
+                # fixed for _wait_for_signal below. Only remove it when the
+                # *Response* woke the loop instead; leaving a live source in
+                # that case holds a reference to this closure and fires it
+                # into a dead loop on some later request.
+                if not timed_out:
+                    GLib.source_remove(timeout_source)
     finally:
         for subscription in subscriptions:
             connection.signal_unsubscribe(subscription)
@@ -584,6 +595,11 @@ class RemoteDesktopSession:
         session_handle: str | None = None,
         busname: str = _BUS_NAME,
     ) -> None:
+        """Hold a negotiated session's handle, connection and EIS fd.
+
+        Not for direct use -- built by :meth:`negotiate` once ``Start`` and
+        ``ConnectToEIS`` have both already succeeded.
+        """
         self._connection = connection
         self._eis_fd: int | None = eis_fd
         self._session_handle = session_handle
@@ -687,10 +703,9 @@ class RemoteDesktopSession:
             return
         eis_fd = getattr(self, "_eis_fd", None)
         if eis_fd is not None:
-            try:
+            # an exception here is only printed to stderr anyway
+            with contextlib.suppress(OSError):
                 os.close(eis_fd)
-            except OSError:
-                pass  # an exception here is only printed to stderr anyway
 
     @classmethod
     def negotiate(
@@ -819,7 +834,7 @@ class RemoteDesktopSession:
                 timeout=timeout,
             )
         except BaseException:
-            # BaseException, not Exception: `Start` blocks on a human
+            # BaseException, not Exception: `Start` blocks on a user
             # answering a consent dialog, so Ctrl-C during that wait is a
             # routine way out of this function -- and it strands an
             # approved session exactly as a decline does.
@@ -926,6 +941,53 @@ def _input_capture_version(
     return int(version)
 
 
+def _create_input_capture_session_v1(
+    connection: Any,
+    Gio: Any,
+    GLib: Any,
+    busname: str,
+    types: int,
+    timeout: float,
+) -> str:
+    """Create an InputCapture session on a portal that predates v2.
+
+    v1 has no ``Start`` at all -- that method, like ``CreateSession2``, was
+    added in version 2. Here ``CreateSession`` itself carries
+    ``capabilities`` and raises the consent dialog, and the session is ready
+    for ``GetZones`` / ``SetPointerBarriers`` / ``Enable`` the moment its
+    ``Response`` arrives. ``ConnectToEIS`` is a v1 original, so the rest of
+    this class works against such a portal unchanged.
+
+    Returns the session handle. ``persist_mode`` and ``restore_token`` have
+    no v1 equivalent -- both are documented as version 2 additions to
+    ``Start``, which does not exist here -- so the caller must reject them
+    before getting this far rather than have them silently ignored.
+    """
+    code, results = _request(
+        connection,
+        Gio,
+        GLib,
+        busname,
+        _INPUT_CAPTURE,
+        "CreateSession",
+        "(sa{sv})",
+        ("",),
+        {
+            "session_handle_token": GLib.Variant("s", uuid.uuid4().hex),
+            "capabilities": GLib.Variant("u", int(types)),
+        },
+        timeout,
+    )
+    if code != 0:
+        raise PortalDeniedError(
+            "CreateSession", "the user declined the input-capture consent dialog"
+        )
+    session_handle = results.get("session_handle")
+    if not isinstance(session_handle, str):
+        raise PortalError("CreateSession returned no session_handle")
+    return session_handle
+
+
 def _wait_for_signal(
     connection: Any,
     Gio: Any,
@@ -933,10 +995,10 @@ def _wait_for_signal(
     busname: str,
     interface: str,
     signal: str,
-    path: str,
+    session_handle: str,
     timeout: float | None,
 ) -> tuple[Any, ...]:
-    """Block for one emission of ``signal`` on ``path``, unpacked.
+    """Block for one emission of ``signal`` for ``session_handle``, unpacked.
 
     Unlike `_request`, nothing here *triggers* the signal: ``Activated`` and
     ``Deactivated`` fire whenever the compositor decides a pointer barrier
@@ -944,7 +1006,23 @@ def _wait_for_signal(
     before this is even called (a long-enabled session, subscribed to
     late) or not for a long time. ``timeout=None`` waits indefinitely --
     the read a caller wants when there is nothing else useful to do but
-    wait for a human to move the pointer.
+    wait for a user to move the pointer.
+
+    **These signals are emitted on the portal object, not on the session
+    object.** Subscribing with the session handle as the D-Bus object path
+    -- the obvious reading of "a signal for this session", and what this
+    did until 2026-09-09 -- matches nothing, delivers nothing, and is
+    indistinguishable from a compositor that never fires the signal at all:
+    it cost this project a live investigation across two GNOME versions, a
+    standalone C reproducer and an upstream Mutter bug report before an
+    xdg-desktop-portal developer pointed out the mistake. The session is
+    identified by the signal's own first argument instead (``o
+    session_handle``, per the portal spec), so the subscription is on
+    `_OBJECT_PATH` and the filtering happens here, on the payload. It is
+    deliberately not done with ``signal_subscribe``'s ``arg0`` filter: the
+    D-Bus specification restricts plain ``arg0=`` match rules to arguments
+    of type STRING, and this one is an OBJECT_PATH, which is the same shape
+    of silent non-delivery all over again.
     """
     loop = GLib.MainLoop()
     result: dict[str, Any] = {}
@@ -961,7 +1039,22 @@ def _wait_for_signal(
     ) -> None:
         if result:  # a subscription that outlives its own wait can fire twice
             return
-        result["args"] = params.unpack()
+        args = params.unpack()
+        if args[0] != session_handle:
+            # Logged, not silently dropped: this filter can hide a signal
+            # that *did* arrive just as effectively as the wrong-path
+            # subscription above did, and the two are indistinguishable
+            # from the outside -- both look exactly like a compositor that
+            # never fired. One debug line is what tells them apart.
+            logger.debug(
+                "ignoring %s for session %s while waiting for %s",
+                signal,
+                args[0],
+                session_handle,
+            )
+            return
+        logger.debug("received %s for session %s", signal, session_handle)
+        result["args"] = args
         loop.quit()
 
     def on_timeout() -> bool:
@@ -974,12 +1067,20 @@ def _wait_for_signal(
         busname,
         interface,
         signal,
-        path,
+        _OBJECT_PATH,
         None,
         Gio.DBusSignalFlags.NONE,
         on_signal,
         None,
     )
+    logger.debug(
+        "waiting up to %s for %s.%s on %s for session %s",
+        "forever" if timeout is None else f"{timeout:g}s",
+        interface,
+        signal,
+        _OBJECT_PATH,
+        session_handle,
+    )
     try:
         if not result:
             timeout_source = None
@@ -988,7 +1089,16 @@ def _wait_for_signal(
             try:
                 loop.run()
             finally:
-                if timeout_source is not None:
+                # A fired timeout source has already deregistered itself --
+                # on_timeout() returns False, which is GLib's signal to
+                # remove it -- so only remove it here when the *signal*
+                # woke the loop instead. Removing it unconditionally trips
+                # a real GLib warning ("Source ID N was not found when
+                # attempting to remove it"), confirmed live: it fired on
+                # every real timeout this session hit, never against
+                # test_portal.py's fake GLib.source_remove, which just
+                # clears pending_timeout with no complaint either way.
+                if timeout_source is not None and not timed_out:
                     GLib.source_remove(timeout_source)
     finally:
         connection.signal_unsubscribe(subscription)
@@ -1002,8 +1112,9 @@ def _wait_for_signal(
 
 
 class Activation(NamedTuple):
-    """One ``Activated`` signal's payload -- see
-    :meth:`InputCaptureSession.wait_for_activation`.
+    """One ``Activated`` signal's payload.
+
+    See :meth:`InputCaptureSession.wait_for_activation`.
     """
 
     activation_id: int
@@ -1054,10 +1165,10 @@ class InputCaptureSession:
 
     **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 human 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
+    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
     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
@@ -1073,6 +1184,11 @@ class InputCaptureSession:
         restore_token: str | None,
         busname: str = _BUS_NAME,
     ) -> None:
+        """Hold a negotiated capture session's handle, connection and EIS fd.
+
+        Not for direct use -- built by :meth:`negotiate` once ``ConnectToEIS``
+        has already succeeded.
+        """
         self._connection = connection
         self._session_handle: str | None = session_handle
         self._eis_fd: int | None = eis_fd
@@ -1273,13 +1389,24 @@ class InputCaptureSession:
         )
         if code != 0:
             raise PortalDeniedError("SetPointerBarriers")
-        return list(results.get("failed_barriers", []))
+        failed = list(results.get("failed_barriers", []))
+        # A partially-refused set is the quiet failure here: the call
+        # succeeds, some barriers stand, and an edge the caller believes is
+        # armed simply never triggers. Callers see only the returned list,
+        # which they may or may not act on -- this says it either way.
+        logger.debug(
+            "SetPointerBarriers: %d requested %s, refused: %s",
+            len(barriers),
+            [b[0] for b in barriers],
+            failed or "none",
+        )
+        return failed
 
     def wait_for_activation(self, timeout: float | None = None) -> Activation:
         """Block until the compositor activates capture, or ``timeout``.
 
         Only returns once a real barrier crossing has been reported --
-        which, on hardware, means a human moved a physical pointer across
+        which, on hardware, means a user moved a physical pointer across
         one. There is no way to trigger this synthetically (see the class
         docstring's third paragraph), so this call can legitimately hang
         until someone does that, and `timeout=None` -- the default -- waits
@@ -1371,10 +1498,8 @@ class InputCaptureSession:
             return
         eis_fd = getattr(self, "_eis_fd", None)
         if eis_fd is not None:
-            try:
+            with contextlib.suppress(OSError):
                 os.close(eis_fd)
-            except OSError:
-                pass
 
     @classmethod
     def negotiate(
@@ -1392,11 +1517,18 @@ class InputCaptureSession:
         Blocks until ``CreateSession2`` -> ``Start`` -> ``ConnectToEIS``
         resolves, prompting the user for consent along the way unless
         ``restore_token`` lets the portal skip that. Raises
-        :class:`PortalVersionError` if the compositor's InputCapture portal
-        predates ``CreateSession2`` (needs v2+ -- this module never speaks
-        the deprecated v1 ``CreateSession``), :class:`PortalDeniedError` if
-        ``Start`` is declined, and :class:`PortalTimeoutError` if any one
-        round trip exceeds ``timeout`` seconds.
+        :class:`PortalDeniedError` if consent is declined, and
+        :class:`PortalTimeoutError` if any one round trip exceeds ``timeout``
+        seconds.
+
+        A portal older than v2 has neither ``CreateSession2`` nor ``Start``,
+        and is negotiated through the deprecated v1 ``CreateSession``
+        instead -- one call that carries ``capabilities`` and raises the
+        consent dialog itself. Everything after negotiation is identical;
+        ``ConnectToEIS`` is a v1 original. The one thing v1 cannot do is
+        persist: ``persist_mode`` and ``restore_token`` were added to
+        ``Start``, so passing either against such a portal raises
+        :class:`PortalVersionError` rather than being quietly ignored.
 
         Returns before anything is actually captured: :meth:`set_pointer_barriers`
         and :meth:`enable` still have to be called, and even then nothing
@@ -1435,62 +1567,95 @@ class InputCaptureSession:
                 raise PortalError(f"cannot reach the session bus: {exc}") from exc
 
         version = _input_capture_version(connection, Gio, GLib, busname, timeout)
-        if version < _MIN_INPUT_CAPTURE_VERSION:
+        # A version below 2 is not a portal to give up on -- it is a portal
+        # that speaks the older half of the same interface. Only
+        # `CreateSession2` and `Start` are version 2 additions; `GetZones`,
+        # `SetPointerBarriers`, `Enable`, `Disable`, `Release` and, crucially,
+        # `ConnectToEIS` are all v1 originals, so everything this class does
+        # after negotiation works either way and only session creation forks.
+        #
+        # This is not hypothetical. xdg-desktop-portal-gnome 50 reports
+        # version 0 -- it registers the full impl interface and never sets the
+        # property -- and calling `CreateSession2` against it fails with
+        # `UnknownMethod`, while v1 `CreateSession` is dispatched normally.
+        # Note that its introspection XML advertises `CreateSession2` anyway:
+        # that XML is static, so it says nothing about what the frontend will
+        # actually dispatch. The `version` property is the only usable signal,
+        # which is why it is read first and believed.
+        legacy = version < _MIN_INPUT_CAPTURE_VERSION
+
+        if legacy and (persist_mode != PersistMode.NONE or restore_token is not None):
             raise PortalVersionError(
-                f"InputCapture version {version} is too old for "
-                f"CreateSession2 (need {_MIN_INPUT_CAPTURE_VERSION}+)"
+                f"InputCapture version {version} has no Start method, and "
+                f"persist_mode/restore_token are version "
+                f"{_MIN_INPUT_CAPTURE_VERSION} additions to it -- this portal "
+                f"cannot persist a session. Retry with persist_mode=NONE and "
+                f"no restore_token to negotiate a one-shot session."
             )
 
         if capabilities == DeviceType.ALL_DEVICES:
             types = _ALL_DEVICE_TYPES
         else:
             types = capabilities
-        reply = _call_sync(
-            connection,
-            Gio,
-            GLib,
-            busname,
-            _OBJECT_PATH,
-            _INPUT_CAPTURE,
-            "CreateSession2",
-            GLib.Variant(
-                "(a{sv})",
-                ({"session_handle_token": GLib.Variant("s", uuid.uuid4().hex)},),
-            ),
-            None,
-            int(timeout * 1000),
-        )
-        (results,) = reply.unpack()
-        session_handle = results.get("session_handle")
-        if not isinstance(session_handle, str):
-            raise PortalError("CreateSession2 returned no session_handle")
 
-        # Past this point a session exists inside xdg-desktop-portal, and
-        # nothing else can close it -- see RemoteDesktopSession.negotiate's
-        # identical reasoning, which this mirrors line for line.
-        try:
-            options: dict[str, Any] = {"capabilities": GLib.Variant("u", int(types))}
-            if persist_mode != PersistMode.NONE:
-                options["persist_mode"] = GLib.Variant("u", int(persist_mode))
-            if restore_token is not None:
-                options["restore_token"] = GLib.Variant("s", restore_token)
-            code, start_results = _request(
+        if legacy:
+            session_handle = _create_input_capture_session_v1(
+                connection, Gio, GLib, busname, int(types), timeout
+            )
+        else:
+            reply = _call_sync(
                 connection,
                 Gio,
                 GLib,
                 busname,
+                _OBJECT_PATH,
                 _INPUT_CAPTURE,
-                "Start",
-                "(osa{sv})",
-                (session_handle, ""),
-                options,
-                timeout,
+                "CreateSession2",
+                GLib.Variant(
+                    "(a{sv})",
+                    ({"session_handle_token": GLib.Variant("s", uuid.uuid4().hex)},),
+                ),
+                None,
+                int(timeout * 1000),
             )
-            if code != 0:
-                raise PortalDeniedError(
-                    "Start", "the user declined the input-capture consent dialog"
+            (results,) = reply.unpack()
+            session_handle = results.get("session_handle")
+            if not isinstance(session_handle, str):
+                raise PortalError("CreateSession2 returned no session_handle")
+
+        # Past this point a session exists inside xdg-desktop-portal, and
+        # nothing else can close it -- see RemoteDesktopSession.negotiate's
+        # identical reasoning, which this mirrors line for line.
+        try:
+            # v1 asked for consent and capabilities in CreateSession itself,
+            # and has no Start to call; it can therefore never issue a
+            # restore token either.
+            new_restore_token = None
+            if not legacy:
+                options: dict[str, Any] = {
+                    "capabilities": GLib.Variant("u", int(types))
+                }
+                if persist_mode != PersistMode.NONE:
+                    options["persist_mode"] = GLib.Variant("u", int(persist_mode))
+                if restore_token is not None:
+                    options["restore_token"] = GLib.Variant("s", restore_token)
+                code, start_results = _request(
+                    connection,
+                    Gio,
+                    GLib,
+                    busname,
+                    _INPUT_CAPTURE,
+                    "Start",
+                    "(osa{sv})",
+                    (session_handle, ""),
+                    options,
+                    timeout,
                 )
-            new_restore_token = start_results.get("restore_token")
+                if code != 0:
+                    raise PortalDeniedError(
+                        "Start", "the user declined the input-capture consent dialog"
+                    )
+                new_restore_token = start_results.get("restore_token")
 
             eis_fd = _call_for_fd(
                 connection,
@@ -1503,7 +1668,7 @@ class InputCaptureSession:
                 timeout,
             )
         except BaseException:
-            # BaseException, not Exception: Start blocks on a human
+            # BaseException, not Exception: Start blocks on a user
             # answering a consent dialog, so Ctrl-C during that wait is a
             # routine way out of this function -- and it strands an
             # approved session exactly as a decline does.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-libei
-Version: 0.5.0
+Version: 0.5.2
 Summary: Inject and receive input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis
 Author: Dennis K. Paulsen
 License-Expression: MIT
@@ -156,7 +156,7 @@ and why, is in
 
 ## Status
 
-Beta (`0.5.0`), published on [PyPI](https://pypi.org/project/python-libei/)
+Beta (`0.5.2`), 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
@@ -187,11 +187,11 @@ Exactly what was run, when, and against which versions:
   portal paths are the part likeliest to come up short off Linux, since
   they need an xdg-desktop-portal RemoteDesktop backend to talk to.
 - CPython 3.10 or newer (tested on 3.13)
-- The native libraries: on Fedora, `sudo dnf install libei libeis liboeffis`;
-  on FreeBSD, `pkg install libei` (the `x11/libei` port), which supplies all
-  three sonames including `liboeffis`
-- `libei.portal` only: PyGObject (`pip install 'python-libei[portal]'`), plus
-  whatever GObject-introspection libraries your distro needs for `Gio` --
+- The native `libei`, `libeis` and `liboeffis` libraries, which `pip` cannot
+  supply. Which package provides them on your distribution — and what to do
+  when the name does not match — is in [docs/install.md](docs/install.md).
+- `libei.portal` only: PyGObject, via the `portal` extra, plus whatever
+  GObject-introspection libraries your distribution needs for `Gio`, since
   PyPI's PyGObject wheel supplies the Python side only. Not needed for
   `libei.ei`, `libei.eis` or `libei.oeffis`.
 - libei 1.0.0 or newer for the core: connecting, binding a seat, and
@@ -224,22 +224,11 @@ Exactly what was run, when, and against which versions:
 
 ## Install
 
-From [PyPI](https://pypi.org/project/python-libei/):
-
 ```sh
 pip install python-libei
 ```
 
-The distribution is named `python-libei`, the import is `libei` -- so
-`pip show python-libei`, but `from libei import ei`.
-
-Pure Python, no build step: the wheel is `py3-none-any` and ctypes talks to
-the native libraries directly, so there is no compiler, no headers and no
-`libei-devel` involved at install time. What `pip` does *not* bring is the
-native libraries themselves -- see [Requirements](#requirements) above; on
-Fedora, `sudo dnf install libei libeis liboeffis`.
-
-To track `main` instead, or to hack on it, install from a checkout:
+From a checkout instead, to track `main` or to work on the package:
 
 ```sh
 git clone https://github.com/ctrondlp/python-libei.git
@@ -247,15 +236,11 @@ cd python-libei
 pip install .          # or `pip install -e '.[dev]'` to develop
 ```
 
-Importing is always safe, even where the native libraries are missing — they
-are loaded on first use, not at import. Check before you rely on them:
-
-```python
-from libei import ei
-
-if not ei.is_available():
-    ...  # fall back to another input backend
-```
+That is the half `pip` can do. The native `libei`/`libeis`/`liboeffis`
+libraries it cannot supply, the `portal` extra, and how to check what actually
+loaded are all in [docs/install.md](docs/install.md) — see
+[Requirements](#requirements) above for the version floors. Importing is safe
+without any of it: those libraries are loaded on first *use*, not at import.
 
 ## Concepts
 

python_libei-0.5.2.dist-info/RECORD

@@ -0,0 +1,17 @@
+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,,

python_libei-0.5.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-libei/__init__.py,sha256=ovsIL7-rEp8LMbiWdmlGSoU6r4lNS_stMLULlkFgwGg,1858
-libei/_cobject.py,sha256=msrbviABSWjc5fKsXHSCg7nQ0Y4Etcq_Dkh0fblW-sY,12845
-libei/ei.py,sha256=Da3ezXnFPXtejlcJFH8bcE5f4pxKZXXqb6ltCh2zAdE,46704
-libei/eis.py,sha256=aYWOCN1NlRchcWd6NjIUi1eYMFWJbp0UHMcQFEJ0ii4,43642
-libei/oeffis.py,sha256=UcnDwLErFxB0xuktNpIzAK01ylpl6ZrmaGnWiUOcFOo,9302
-libei/portal.py,sha256=-OAg_g0Q6s0BNN2B6bzfyD2T5N_dCuHbSpqtcL8dCUk,60488
-libei/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-libei/_capi/__init__.py,sha256=3VxixYYlr_ZcuiK0GwrCpbE3VvEv_O990mJzdIJ8i74,209
-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.0.dist-info/licenses/LICENSE,sha256=l6xbMU6Y-JZDzmBciBj-J5t6h6jNg_Bcyp4bHxDepqU,1074
-python_libei-0.5.0.dist-info/METADATA,sha256=YDry3cY8Id0Z9bwQh_27SZkR8U8Ntf-S2t7Elf2nojo,20475
-python_libei-0.5.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_libei-0.5.0.dist-info/top_level.txt,sha256=_DQXzGjDsUBENI_cNkiOxPB4xi8coCbQS1lq18FMudQ,6
-python_libei-0.5.0.dist-info/RECORD,,