python-libei 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

libei/__init__.py

@@ -13,6 +13,9 @@ Use the submodules directly:
   drive a test harness for the ``ei`` module without a real compositor)
 - :mod:`libei.oeffis` -- negotiate an EI connection through the
   ``org.freedesktop.portal.RemoteDesktop`` XDG desktop portal
+- :mod:`libei.portal` -- negotiate that same portal directly over D-Bus
+  instead, for ``persist_mode``/``restore_token`` support liboeffis's C API
+  doesn't expose
 
 Scope, in short: this needs a compositor speaking EI/EIS -- there is no X11
 fallback. Pointer (relative and absolute), button, keyboard, scroll, touch
@@ -26,6 +29,6 @@ the full breakdown, including which features need which libei version.
 Alpha: the API is not frozen.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 
 __all__ = ["__version__"]

libei/portal.py

@@ -0,0 +1,708 @@
+"""Negotiate an EIS connection by driving ``org.freedesktop.portal.RemoteDesktop``
+directly over D-Bus, rather than through :mod:`libei.oeffis`.
+
+:mod:`libei.oeffis` wraps liboeffis, whose C API
+(``oeffis_create_session()``) takes only a device-type bitmask -- it exposes
+neither ``persist_mode`` nor the ``restore_token`` a caller needs to avoid
+re-prompting the user on every run. Upstream's own documentation is explicit
+about why: liboeffis is "intentionally kept simple, any more complex needs
+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.
+
+    with RemoteDesktopSession.negotiate(
+        devices=DeviceType.POINTER | DeviceType.KEYBOARD,
+        persist_mode=PersistMode.UNTIL_REVOKED,
+        restore_token=saved_token,  # None on the first run
+    ) as session:
+        save_somewhere(session.restore_token)  # for next time
+        sender = ei.Sender.create_for_fd(session.eis_fd, name="my-app")
+        ...  # inject input for as long as the session is needed
+
+Three things worth knowing before building on this:
+
+* **Blocking, not event-driven.** Unlike :class:`libei.oeffis.Oeffis`
+  (poll ``fd``, call ``dispatch()`` until it returns ``True``),
+  :meth:`RemoteDesktopSession.negotiate` runs its own nested
+  ``GLib.MainLoop`` per D-Bus round trip and returns only once the whole
+  sequence has resolved, or raises. liboeffis is itself event-driven, which
+  is why ``Oeffis`` is; a caller driving GDBus directly already has
+  ``GLib.MainLoop`` available to it, and there is no equivalent requirement
+  here to expose an async surface -- so this doesn't. Each round trip is
+  bounded by ``timeout`` (:class:`PortalTimeoutError` when it expires),
+  since a blocking call with no escape hatch is the one thing ``Oeffis``'s
+  pollable fd would otherwise buy you.
+* **Close it when done.** The portal session outlives this object unless
+  ``Session.Close()`` is called, and the EIS fd is owned by whoever
+  received it. :meth:`RemoteDesktopSession.close` (and the context-manager
+  form above) does both; see that method for what it does and does not
+  clean up.
+* **Least automatically verified path in this package**, same caveat
+  :mod:`libei.oeffis` carries: nothing in CI can click through a real
+  consent dialog, so ``tests/test_portal.py`` exercises the
+  request/response orchestration against a fake D-Bus connection only.
+
+  Verified by hand 2026-09-01 against a real GNOME Wayland session
+  (xdg-desktop-portal, ``RemoteDesktop`` v2), end to end: a first run
+  raised the consent dialog and was approved with "Remember" checked
+  (5.4s), and a second run replaying the ``restore_token`` was granted
+  with no dialog at all (0.2s) -- which is the whole point of
+  ``persist_mode``, and is also what proves the first run was a genuine
+  first-time authorisation rather than a pre-existing grant. Three devices
+  resumed on the returned fd: relative pointer, keyboard, then absolute
+  pointer -- in that order, which is exactly the device race ``ei``-side
+  callers have to handle. ``Session.Close()`` was exercised too. No input
+  was injected: emulation is ``libei.ei``'s job and is not what this
+  module does.
+"""
+
+from __future__ import annotations
+
+import enum
+import logging
+import os
+import uuid
+from typing import Any
+
+from .oeffis import DeviceType
+
+logger = logging.getLogger("libei.portal")
+
+__all__ = [
+    "DeviceType",
+    "PersistMode",
+    "PortalError",
+    "PortalVersionError",
+    "PortalDeniedError",
+    "PortalTimeoutError",
+    "RemoteDesktopSession",
+    "is_available",
+]
+
+_BUS_NAME = "org.freedesktop.portal.Desktop"
+_OBJECT_PATH = "/org/freedesktop/portal/desktop"
+_REMOTE_DESKTOP = "org.freedesktop.portal.RemoteDesktop"
+_REQUEST_INTERFACE = "org.freedesktop.portal.Request"
+_SESSION_INTERFACE = "org.freedesktop.portal.Session"
+
+_MIN_REMOTE_DESKTOP_VERSION = 2  # ConnectToEIS needs v2+
+
+_DEFAULT_TIMEOUT = 60.0
+"""Seconds to wait for one portal round trip. Generous, because a human 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`."""
+
+_ALL_DEVICE_TYPES = DeviceType.KEYBOARD | DeviceType.POINTER | DeviceType.TOUCHSCREEN
+"""Every bit the RemoteDesktop `types` bitmask defines.
+
+`DeviceType.ALL_DEVICES` is liboeffis's own sentinel and is literally 0,
+which the portal reads as *no* device types rather than all of them -- a
+session that negotiates fine and then never resumes a single device. The
+sentinel is translated to this before it reaches `SelectDevices`."""
+
+
+class PersistMode(enum.IntEnum):
+    """``SelectDevices``'s ``persist_mode`` option, per the RemoteDesktop XML."""
+
+    NONE = 0
+    WHILE_RUNNING = 1
+    UNTIL_REVOKED = 2
+
+
+class PortalError(Exception):
+    """Base class for this module's failures."""
+
+
+class PortalVersionError(PortalError):
+    """The compositor's RemoteDesktop portal is too old for ConnectToEIS."""
+
+
+class PortalTimeoutError(PortalError):
+    """A portal request did not answer within the timeout.
+
+    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
+    this as a failure if that is expected.
+    """
+
+    def __init__(self, step: str, timeout: float) -> None:
+        super().__init__(f"{step} did not answer within {timeout:g}s")
+        self.step = step
+        self.timeout = timeout
+
+
+class PortalDeniedError(PortalError):
+    """``CreateSession``, ``SelectDevices`` or ``Start`` was not approved.
+
+    Covers both an explicit user decline and any other non-zero portal
+    response code -- the portal spec does not guarantee a code means
+    "the user said no" versus some other failure, so this does not either.
+    """
+
+    def __init__(self, step: str, message: str | None = None) -> None:
+        super().__init__(message or f"{step} was not approved")
+        self.step = step
+        self.message = message
+
+
+def _gio() -> tuple[Any, Any] | None:
+    """Import Gio and GLib, or return None.
+
+    Deferred so importing this module never requires PyGObject -- the same
+    "zero hard dependencies, probed at runtime" rule the rest of this
+    package follows. See is_available().
+    """
+    try:
+        import gi
+
+        gi.require_version("Gio", "2.0")
+        from gi.repository import Gio, GLib
+    except Exception:
+        return None
+    return Gio, GLib
+
+
+def is_available() -> bool:
+    """Whether PyGObject (Gio) can be imported on this system.
+
+    Does not check for a running session bus or a portal implementation --
+    only whether the Python side this module needs is installed. A missing
+    session bus or portal surfaces as a `PortalError` from `negotiate()`.
+    """
+    return _gio() is not None
+
+
+def _glib_error(GLib: Any) -> Any:
+    """``GLib.Error``, or a tuple that catches nothing where it is absent.
+
+    Every GDBus failure -- no session bus, no portal implementation behind
+    the name, a method that returns a D-Bus error -- arrives as this one
+    exception type. It is looked up rather than imported so that a test
+    double standing in for ``GLib`` need not define it: `except ()` catches
+    nothing, which is the right behaviour when there is no real GLib whose
+    errors could be raised in the first place.
+    """
+    return getattr(GLib, "Error", ())
+
+
+def _call_sync(
+    connection: Any,
+    Gio: Any,
+    GLib: Any,
+    busname: str,
+    object_path: str,
+    interface: str,
+    method: str,
+    parameters: Any,
+    reply_type: Any,
+) -> Any:
+    """``call_sync``, with GDBus failures translated to `PortalError`.
+
+    Without this a `GLib.Error` propagates raw, so the no-session-bus and
+    no-portal-backend cases -- exactly the ones `is_available()` documents
+    as surfacing here, since it deliberately checks neither -- escape a
+    caller's `except PortalError`.
+    """
+    try:
+        return connection.call_sync(
+            busname,
+            object_path,
+            interface,
+            method,
+            parameters,
+            reply_type,
+            Gio.DBusCallFlags.NONE,
+            -1,
+            None,
+        )
+    except _glib_error(GLib) as exc:
+        raise PortalError(f"{method} failed on the D-Bus: {exc}") from exc
+
+
+def _returned_handle(reply: Any) -> str | None:
+    """The request object path a Request-returning call replied with.
+
+    Every such portal method answers ``(o)``, but this stays defensive and
+    returns ``None`` on anything else: the value is only ever used as a
+    *second* path to listen on alongside the one derived from our own
+    handle_token, so a reply shaped unexpectedly is a reason to fall back to
+    that derived path, never to fail the negotiation outright.
+    """
+    try:
+        unpacked = reply.unpack()
+    except Exception:
+        return None
+    if isinstance(unpacked, tuple) and len(unpacked) == 1:
+        handle = unpacked[0]
+        if isinstance(handle, str):
+            return handle
+    return None
+
+
+def _request(
+    connection: Any,
+    Gio: Any,
+    GLib: Any,
+    busname: str,
+    interface: str,
+    method: str,
+    signature: str,
+    leading_args: tuple[Any, ...],
+    options: dict[str, Any],
+    timeout: float,
+) -> tuple[int, Any]:
+    """Call a Request-returning portal method, racelessly.
+
+    Subscribing to the ``Response`` signal only *after* the call that
+    returns its request handle is a real race, not a hypothetical one: a
+    fast, non-interactive response (no consent dialog involved, e.g.
+    ``SelectDevices``) can arrive and be delivered before the subscription
+    is registered, hanging forever on a signal that already came and went.
+    Reproduced live (intermittent hangs at both ``SelectDevices`` and
+    ``SelectSources`` in the code this was ported from). Fixed by choosing
+    the ``handle_token`` ourselves, computing the resulting request object
+    path up front, and subscribing to that exact path *before* making the
+    call at all -- the pattern xdg-desktop-portal's own documentation
+    describes.
+
+    Raises :class:`PortalTimeoutError` if no ``Response`` arrives within
+    ``timeout``. The nested loop is otherwise unbounded, and a portal that
+    dies after accepting the call sends no ``Response`` and no error --
+    leaving the caller wedged with nothing to poll and no way out.
+    """
+    unique_name = connection.get_unique_name()
+    escaped_sender = unique_name[1:].replace(".", "_")
+    token = uuid.uuid4().hex
+    options = dict(options)
+    options["handle_token"] = GLib.Variant("s", token)
+    expected_path = f"/org/freedesktop/portal/desktop/request/{escaped_sender}/{token}"
+
+    loop = GLib.MainLoop()
+    result: dict[str, Any] = {}
+    subscriptions: list[Any] = []
+    # Set inside the timeout callback rather than inferred from an empty
+    # `result` afterwards: a Response carrying no results is legitimate
+    # (SelectDevices answers with an empty dict), so "did the loop end
+    # because it timed out" has to be recorded, not deduced.
+    timed_out = False
+
+    def on_response(
+        _conn: Any,
+        _sender: Any,
+        _path: Any,
+        _iface: Any,
+        _signal: Any,
+        params: Any,
+        *_a: Any,
+    ) -> None:
+        if result:  # both subscriptions may fire; the first reply wins
+            return
+        result["code"], result["results"] = params.unpack()
+        loop.quit()
+
+    def on_timeout() -> bool:
+        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:
+        subscriptions.append(
+            connection.signal_subscribe(
+                busname,
+                _REQUEST_INTERFACE,
+                "Response",
+                path,
+                None,
+                Gio.DBusSignalFlags.NONE,
+                on_response,
+                None,
+            )
+        )
+
+    subscribe(expected_path)
+    try:
+        parameters = GLib.Variant(signature, (*leading_args, options))
+        reply = _call_sync(
+            connection,
+            Gio,
+            GLib,
+            busname,
+            _OBJECT_PATH,
+            interface,
+            method,
+            parameters,
+            None,
+        )
+        # The spec says the handle the call returns matches the path derived
+        # from our own handle_token, but a portal is free to hand back
+        # something else -- and some do. Listening on both is strictly safer
+        # than trusting either alone: watching only the derived path means a
+        # Response delivered to the returned handle is never seen, and the
+        # wait below then runs out the full timeout for no reason.
+        handle = _returned_handle(reply)
+        if handle is not None and handle != expected_path:
+            subscribe(handle)
+        # `if not result` because a synchronous answer (a fast
+        # non-interactive Response, or a test double) can arrive during the
+        # call above, before run() is reached -- and quit() on a loop that
+        # is not running yet does not stop the later run(), so running it
+        # then would block with the reply already delivered.
+        if not result:
+            timeout_source = GLib.timeout_add(int(timeout * 1000), on_timeout)
+            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)
+    finally:
+        for subscription in subscriptions:
+            connection.signal_unsubscribe(subscription)
+    if timed_out:
+        raise PortalTimeoutError(method, timeout)
+    return result["code"], result["results"]
+
+
+def _call_for_fd(
+    connection: Any,
+    Gio: Any,
+    GLib: Any,
+    busname: str,
+    interface: str,
+    method: str,
+    session_handle: str,
+) -> int:
+    """Call a method that returns a fd via a GUnixFDList index.
+
+    The fd that comes back is *owned* -- `g_unix_fd_list_get()` dups it --
+    so whoever receives it has to close it. See
+    :meth:`RemoteDesktopSession.close`.
+    """
+    try:
+        reply, fd_list = connection.call_with_unix_fd_list_sync(
+            busname,
+            _OBJECT_PATH,
+            interface,
+            method,
+            GLib.Variant("(oa{sv})", (session_handle, {})),
+            GLib.VariantType.new("(h)"),
+            Gio.DBusCallFlags.NONE,
+            -1,
+            None,
+            None,
+        )
+    except _glib_error(GLib) as exc:
+        raise PortalError(f"{method} failed on the D-Bus: {exc}") from exc
+    (handle_index,) = reply.unpack()
+    return fd_list.get(handle_index)
+
+
+def _remote_desktop_version(connection: Any, Gio: Any, GLib: Any, busname: str) -> int:
+    reply = _call_sync(
+        connection,
+        Gio,
+        GLib,
+        busname,
+        _OBJECT_PATH,
+        "org.freedesktop.DBus.Properties",
+        "Get",
+        GLib.Variant("(ss)", (_REMOTE_DESKTOP, "version")),
+        None,
+    )
+    (version,) = reply.unpack()
+    return int(version)
+
+
+class RemoteDesktopSession:
+    """A negotiated ``org.freedesktop.portal.RemoteDesktop`` session.
+
+    Two things here need releasing, and neither happens on its own when
+    this object is dropped:
+
+    * **The portal session.** It lives in xdg-desktop-portal, not in this
+      process, and persists until ``Session.Close()`` is called or the D-Bus
+      connection that created it drops. That connection is *not* owned here
+      -- ``Gio.bus_get_sync()`` hands back GLib's shared session-bus
+      singleton, which outlives any one session -- so a long-running process
+      that negotiates repeatedly accumulates live portal sessions until it
+      exits. :meth:`close` is what ends one.
+    * **The EIS fd**, which arrives dup'd and owned. Reading :attr:`eis_fd`
+      hands that ownership on (typically straight to
+      :meth:`libei.ei.Sender.create_for_fd`, which closes it itself); if it
+      is never read, :meth:`close` closes it rather than leaking it.
+
+    Use it as a context manager, or call :meth:`close` when done.
+    """
+
+    def __init__(
+        self,
+        connection: Any,
+        eis_fd: int,
+        restore_token: str | None,
+        session_handle: str | None = None,
+    ) -> None:
+        self._connection = connection
+        self._eis_fd: int | None = eis_fd
+        self._session_handle = session_handle
+        # Mirrors libei.oeffis.Oeffis's ownership rule: reading `eis_fd`
+        # hands the fd to the caller, so close() must not also close it once
+        # that has happened -- but nothing else will ever close it if the
+        # session dies before anyone reads it, so close() must in that case.
+        self._eis_fd_claimed = False
+        self._closed = False
+        self.restore_token = restore_token
+        """The token to pass as ``restore_token=`` on the next call to
+        avoid re-prompting, or ``None`` if the portal issued none -- either
+        because no ``persist_mode`` was requested, or the portal declined
+        to grant persistence.
+
+        Save whatever comes back on *every* run rather than only the first:
+        the portal is free to hand back a different token each time, and a
+        caller that keeps only the original would eventually present a stale
+        one. (Observed 2026-09-01 on GNOME: the same token comes back on
+        each restore. That is this portal's behaviour, not a guarantee --
+        the interface permits a new one.)
+
+        Nothing is written to disk here: a token is a standing grant of
+        input injection, so storing it is the caller's decision."""
+
+    @property
+    def eis_fd(self) -> int:
+        """The fd to pass to :meth:`libei.ei.Sender.create_for_fd`.
+
+        Reading this transfers ownership of the fd to the caller -- after
+        that, closing it is the caller's job (or, far more usually, the
+        `Sender`'s, which takes ownership and closes it itself).
+        """
+        if self._eis_fd is None:
+            raise PortalError("the session is closed; its EIS fd is gone")
+        self._eis_fd_claimed = True
+        return self._eis_fd
+
+    def close(self) -> None:
+        """End the portal session, and close the EIS fd if unclaimed.
+
+        Idempotent. ``Session.Close()`` failures are logged and swallowed:
+        the session may already be gone (the portal restarted, the user
+        revoked the grant), and there is nothing a caller could usefully do
+        about it during cleanup either way.
+
+        Note that this does *not* disturb an `ei.Sender` already built on
+        the fd -- closing the portal session is what tears the EIS
+        connection down, so do it when finished injecting, not before.
+        """
+        if self._closed:
+            return
+        self._closed = True
+        if self._eis_fd is not None and not self._eis_fd_claimed:
+            try:
+                os.close(self._eis_fd)
+            except OSError as exc:
+                # Nothing a caller could do about a failed close during
+                # cleanup, and raising here would mask whatever exception
+                # was already unwinding through a `with` block.
+                logger.debug("closing the EIS fd failed: %s", exc)
+        self._eis_fd = None
+        if self._session_handle is None or self._connection is None:
+            return
+        gio_modules = _gio()
+        if gio_modules is None:  # pragma: no cover - unreachable once negotiated
+            return
+        Gio, GLib = gio_modules
+        try:
+            _call_sync(
+                self._connection,
+                Gio,
+                GLib,
+                _BUS_NAME,
+                self._session_handle,
+                _SESSION_INTERFACE,
+                "Close",
+                None,
+                None,
+            )
+        except PortalError as exc:
+            logger.debug("closing the portal session failed: %s", exc)
+        finally:
+            self._session_handle = None
+            self._connection = None
+
+    def __enter__(self) -> RemoteDesktopSession:
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        # 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
+        # unclaimed fd is the part that is always safe and always necessary
+        # -- nothing else will ever close it. getattr() with defaults
+        # because __init__ can raise before these exist, and a bare
+        # attribute access would then raise AttributeError inside __del__,
+        # which Python only prints to stderr.
+        if getattr(self, "_eis_fd_claimed", True):
+            return
+        eis_fd = getattr(self, "_eis_fd", None)
+        if eis_fd is not None:
+            try:
+                os.close(eis_fd)
+            except OSError:
+                pass  # an exception here is only printed to stderr anyway
+
+    @classmethod
+    def negotiate(
+        cls,
+        *,
+        connection: Any = None,
+        devices: DeviceType = DeviceType.ALL_DEVICES,
+        persist_mode: PersistMode = PersistMode.NONE,
+        restore_token: str | None = None,
+        busname: str = _BUS_NAME,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> RemoteDesktopSession:
+        """Negotiate a RemoteDesktop portal session and connect it to EIS.
+
+        Blocks until the whole ``CreateSession`` -> ``SelectDevices`` ->
+        ``Start`` -> ``ConnectToEIS`` sequence resolves, prompting the user
+        for consent along the way unless ``restore_token`` lets the portal
+        skip that. Raises :class:`PortalVersionError` if the compositor's
+        RemoteDesktop portal is too old for ``ConnectToEIS`` (needs v2+),
+        :class:`PortalDeniedError` if any step is declined, and
+        :class:`PortalTimeoutError` if any one round trip exceeds
+        ``timeout`` seconds (60 by default -- generous, since ``Start``
+        waits on a human answering a dialog).
+
+        ``devices`` selects what to ask for. ``DeviceType.ALL_DEVICES`` is
+        liboeffis's sentinel for "everything" and is literally ``0``, which
+        the portal would read as *nothing*; it is translated here to every
+        type the portal defines.
+
+        ``persist_mode`` and ``restore_token`` are how a caller avoids
+        being prompted on every launch: ask for persistence, read
+        :attr:`restore_token` afterwards, store it, and hand it back next
+        time. Passing ``restore_token`` *without* a ``persist_mode`` raises
+        :class:`ValueError`: the portal answers such a request with no
+        token at all, so a caller following the store-what-comes-back rule
+        would write ``None`` over the token it just spent -- silently
+        ending the persistence it plainly meant to keep.
+
+        ``connection`` can be injected (a `Gio.DBusConnection`, or a
+        test double matching its subset of methods this module calls) to
+        reuse an existing bus connection, or to test this against a fake
+        one without a real portal -- see ``tests/test_portal.py``. Left as
+        ``None``, this opens a new session-bus connection itself.
+
+        No ScreenCast source is ever requested here: an absolute-pointer
+        EIS device carries its own region, and asking for ScreenCast too
+        would make the user grant screen-recording permission for nothing
+        an EIS-only caller needs.
+        """
+        if restore_token is not None and persist_mode == PersistMode.NONE:
+            raise ValueError(
+                "restore_token was given with persist_mode=NONE: the portal "
+                "consumes a restore token on use and only issues a new one "
+                "when persistence is requested, so this would spend the "
+                "saved token and hand back None. Pass a persist_mode too."
+            )
+
+        gio_modules = _gio()
+        if gio_modules is None:
+            raise PortalError(
+                "PyGObject is not installed; libei.portal needs it to "
+                "negotiate a RemoteDesktop portal session "
+                "(pip install 'python-libei[portal]')"
+            )
+        Gio, GLib = gio_modules
+
+        if connection is None:
+            try:
+                connection = Gio.bus_get_sync(Gio.BusType.SESSION, None)
+            except _glib_error(GLib) as exc:
+                raise PortalError(f"cannot reach the session bus: {exc}") from exc
+
+        version = _remote_desktop_version(connection, Gio, GLib, busname)
+        if version < _MIN_REMOTE_DESKTOP_VERSION:
+            raise PortalVersionError(
+                f"RemoteDesktop version {version} is too old for "
+                f"ConnectToEIS (need {_MIN_REMOTE_DESKTOP_VERSION}+)"
+            )
+
+        # session_handle_token is a *different* token from the handle_token
+        # _request() injects itself: omitting it crashes xdg-desktop-portal
+        # 1.22.1 outright (SIGABRT, "assertion failed:
+        # (session->token != NULL)") -- not optional.
+        code, results = _request(
+            connection,
+            Gio,
+            GLib,
+            busname,
+            _REMOTE_DESKTOP,
+            "CreateSession",
+            "(a{sv})",
+            (),
+            {"session_handle_token": GLib.Variant("s", uuid.uuid4().hex)},
+            timeout,
+        )
+        if code != 0:
+            raise PortalDeniedError("CreateSession")
+        session_handle = results["session_handle"]
+
+        # ALL_DEVICES is 0, which SelectDevices reads as "no device types"
+        # rather than "every device type" -- see _ALL_DEVICE_TYPES.
+        types = _ALL_DEVICE_TYPES if devices == DeviceType.ALL_DEVICES else devices
+        options: dict[str, Any] = {"types": 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, _results = _request(
+            connection,
+            Gio,
+            GLib,
+            busname,
+            _REMOTE_DESKTOP,
+            "SelectDevices",
+            "(oa{sv})",
+            (session_handle,),
+            options,
+            timeout,
+        )
+        if code != 0:
+            raise PortalDeniedError("SelectDevices")
+
+        code, results = _request(
+            connection,
+            Gio,
+            GLib,
+            busname,
+            _REMOTE_DESKTOP,
+            "Start",
+            "(osa{sv})",
+            (session_handle, ""),
+            {},
+            timeout,
+        )
+        if code != 0:
+            raise PortalDeniedError(
+                "Start", "the user declined the remote-control consent dialog"
+            )
+        new_restore_token = results.get("restore_token")
+
+        eis_fd = _call_for_fd(
+            connection,
+            Gio,
+            GLib,
+            busname,
+            _REMOTE_DESKTOP,
+            "ConnectToEIS",
+            session_handle,
+        )
+        return cls(connection, eis_fd, new_restore_token, session_handle)

{python_libei-0.1.0.dist-info → python_libei-0.3.0.dist-info}/METADATA

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: python-libei
-Version: 0.1.0
+Version: 0.3.0
 Summary: Inject and receive input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis
 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: 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
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -25,6 +26,8 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Provides-Extra: portal
+Requires-Dist: PyGObject>=3.42; extra == "portal"
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: ruff>=0.6; extra == "dev"
@@ -133,8 +136,9 @@ pointer.
 
 ## Status
 
-Alpha (`0.1.0`), not yet on PyPI, and the API is not frozen — expect
-renames before 1.0. What that qualifier covers, concretely:
+Alpha (`0.3.0`), published on [PyPI](https://pypi.org/project/python-libei/)
+since `0.1.0`, and the API is not frozen — expect renames before 1.0. What
+that qualifier covers, concretely:
 
 - The injection path — connect, bind, wait for a device, send events — is
   exercised end-to-end against the real libraries by
@@ -143,9 +147,20 @@ renames before 1.0. What that qualifier covers, concretely:
 - Text input, touch cancellation, ping/pong, keymap transfer, region mapping
   ids and `peek_event_type()` are each round-tripped through a real libeis
   server in `tests/test_integration_extras.py`.
-- The portal path (`libei.oeffis`) has only ever been verified by hand, since
-  it needs an interactive consent dialog that nothing here can drive. See
-  [Troubleshooting](#troubleshooting).
+- Both portal paths (`libei.oeffis` and `libei.portal`) can only ever be
+  verified by hand, since they need an interactive consent dialog that
+  nothing here can drive automatically — `tests/test_portal.py` covers
+  `libei.portal`'s orchestration (raceless subscribe-before-call, the
+  `session_handle_token` crash workaround, persist_mode/restore_token)
+  against a fake D-Bus connection only. `libei.oeffis` was verified by hand
+  on 2026-08-25 (see [Troubleshooting](#troubleshooting)), and
+  `libei.portal` on 2026-09-01 against a real GNOME Wayland session
+  (`RemoteDesktop` v2): a first run raised the consent dialog and was
+  approved (5.4s), a second replaying the `restore_token` was granted with
+  no dialog at all (0.2s), three devices resumed on the returned fd
+  (relative pointer, keyboard, absolute pointer — in that order, the device
+  race `ei`-side callers must handle), and `Session.Close()` was exercised.
+  No input was injected — emulation is `libei.ei`'s job.
 - Verified against libei 1.6.0 on Fedora 44 / GNOME 50.4, and against a
   locally built 1.2.1 (130 passed, 4 skipped — the 1.4 and 1.6 features
   gate themselves out). CI repeats the 1.2.1 run on Python 3.10-3.13, so
@@ -157,7 +172,7 @@ renames before 1.0. What that qualifier covers, concretely:
 | Instead of this | Why you might |
 | --- | --- |
 | [snegg](https://gitlab.freedesktop.org/whot/snegg) | The reference bindings, by libei's own author — closer to upstream, and first to get new API. Self-described as for "rapid prototyping" with an explicitly unstable API, and `import snegg.ei` fails outright where libei isn't installed. [`docs/vs-snegg.md`](docs/vs-snegg.md) covers the differences in detail. |
-| The portal's D-Bus API directly (`org.freedesktop.portal.RemoteDesktop`, via Gio or dbus-python) | No native library and no bindings at all — `NotifyPointerMotion`, `NotifyKeyboardKeycode` and friends are plain method calls. The catch is absolute motion: `NotifyPointerMotionAbsolute` needs a PipeWire stream id, which only exists after a second, separate ScreenCast consent dialog. libei has no such requirement. |
+| The RemoteDesktop portal's own D-Bus API directly (`NotifyPointerMotion`, `NotifyKeyboardKeycode`, …), bypassing libei/EI entirely | `libei.portal` already gets you the D-Bus session and its `persist_mode`/`restore_token` handling — reach past libei entirely only if you don't want the EI protocol at all. The catch if you do: `NotifyPointerMotionAbsolute` needs a PipeWire stream id, which only exists after a second, separate ScreenCast consent dialog. libei has no such requirement. |
 | `ydotool` and other `/dev/uinput` tools | Kernel-level, so they work under any compositor and need no portal session — at the cost of a privileged daemon, and of sidestepping the consent model that EI exists to enforce. |
 
 ## Requirements
@@ -165,6 +180,10 @@ renames before 1.0. What that qualifier covers, concretely:
 - Linux with a Wayland compositor (GNOME, KDE, Sway, …)
 - CPython 3.10 or newer (tested on 3.13)
 - The native libraries: on Fedora, `sudo dnf install libei libeis liboeffis`
+- `libei.portal` only: PyGObject (`pip install 'python-libei[portal]'`), plus
+  whatever GObject-introspection libraries your distro needs for `Gio` --
+  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
   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
@@ -194,17 +213,29 @@ renames before 1.0. What that qualifier covers, concretely:
 
 ## Install
 
-Not published to PyPI yet — install from a checkout:
+From [PyPI](https://pypi.org/project/python-libei/):
 
 ```sh
-git clone https://github.com/ctrondlp/python-libei.git
-cd python-libei
-pip install .
+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:
+
+```sh
+git clone https://github.com/ctrondlp/python-libei.git
+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:
 
@@ -288,23 +319,59 @@ several devices — see the absolute-positioning notes under
 call and exposes no options dict, so the two things that make an approval
 persist — `persist_mode` on `SelectDevices`, and the `restore_token` that
 comes back on `Start` — are unreachable through it. This is a limitation of
-the C library, not of these bindings; there is nothing here left to bind.
+the C library, not of these bindings; upstream's own docs say as much:
+liboeffis is "intentionally kept simple, any more complex needs should be
+handled by an application talking to DBus directly"
+([source](https://libinput.pages.freedesktop.org/libei/api/group__liboeffis.html)).
 
-What works is negotiating the portal yourself over D-Bus and handing the
-resulting fd to `Sender.create_for_fd()`, which does not care where the fd
-came from:
+`libei.portal` is that: the same `CreateSession` → `SelectDevices` → `Start`
+→ `ConnectToEIS` sequence, driven directly over D-Bus (needs PyGObject —
+`pip install 'python-libei[portal]'`), with `persist_mode`/`restore_token`
+as real parameters:
 
-1. `CreateSession` on `org.freedesktop.portal.RemoteDesktop`
-2. `SelectDevices` with `persist_mode` (1 = while running, 2 = until
-   revoked) and, on later runs, the saved `restore_token`
-3. `Start` — the response carries a fresh `restore_token`, which you store
-4. `ConnectToEIS` — the fd for `ei.Sender.create_for_fd()`
+```python
+from libei import ei, portal
+
+with portal.RemoteDesktopSession.negotiate(
+    devices=portal.DeviceType.POINTER,
+    persist_mode=portal.PersistMode.UNTIL_REVOKED,
+    restore_token=saved_token,  # None on the first run
+) as session:
+    save_somewhere(session.restore_token)  # a fresh token every time -- save it
+    sender = ei.Sender.create_for_fd(session.eis_fd, name="my-app")
+    ...  # inject input for as long as the session is needed
+```
 
 Save the token somewhere durable and pass it back next time; the portal then
 restores the session without prompting. Treat it as a credential — anyone
 holding it can reopen input injection on that desktop, so it belongs
 wherever you'd keep a password, and the decision to store it at all belongs
-to the application rather than to a library.
+to the application rather than to this library, which never writes it
+anywhere itself.
+
+Save whatever comes back on **every** run, not just the first: the portal is
+free to hand back a different token each time, and a caller that keeps only
+the original would eventually present a stale one. (On GNOME the same token
+comes back on each restore — that is one portal's behaviour, not a
+guarantee.) Passing `restore_token` *without* a `persist_mode` raises
+`ValueError`: the portal answers such a request with no token at all, so
+storing what came back would write `None` over the token you just spent.
+
+Three differences from `Oeffis` above worth knowing:
+
+- **Blocking, not event-driven.** `negotiate()` runs its own nested
+  `GLib.MainLoop` per D-Bus round trip and returns only once connected, or
+  raises `PortalVersionError` / `PortalDeniedError` / `PortalTimeoutError`.
+- **Bounded.** Each round trip gets `timeout` seconds (60 by default —
+  generous, since `Start` waits on a human answering a dialog). Without it a
+  portal that dies after accepting the call would wedge the calling thread
+  forever, which is the one thing `Oeffis`'s pollable fd protects against.
+- **Close it.** The portal session lives in xdg-desktop-portal and outlives
+  the object unless `Session.Close()` is called — `Gio.bus_get_sync()` hands
+  back GLib's *shared* connection, so dropping the session tears nothing
+  down, and a long-running process that negotiates repeatedly accumulates
+  live sessions. The `with` block above handles it; otherwise call
+  `session.close()`.
 
 ## Sending input
 
@@ -633,6 +700,7 @@ the capability you bound (`seat.capabilities`).
 | `libei.ei` | Clients: `Sender` (inject), `Receiver` (consume) |
 | `libei.eis` | Servers: `Eis`, for compositors and for testing clients |
 | `libei.oeffis` | Getting an EI fd from the desktop portal |
+| `libei.portal` | The same, over D-Bus directly, with `persist_mode`/`restore_token` |
 
 Each module has `is_available()`, an `Error` exception, and an `EventType` /
 `DeviceCapability` enum. `ei` and `eis` also share the shapes around them:
@@ -657,6 +725,12 @@ them in this order -- each one only makes sense once the one below it does.
 | [`_cobject.py`](src/libei/_cobject.py) | `CObject`: pointer ownership, refcounting, and the identity cache that every wrapper class inherits |
 | [`ei.py`](src/libei/ei.py), [`eis.py`](src/libei/eis.py), [`oeffis.py`](src/libei/oeffis.py) | The public API: Python classes, enums and dataclasses over the raw calls |
 
+[`portal.py`](src/libei/portal.py) sits outside this stack entirely -- there
+is no C library behind it, so no `_capi` binding and no `CObject`. It talks
+D-Bus directly through PyGObject (`Gio`/`GLib`, imported lazily the same way
+the C libraries are loaded lazily) and only ever produces a plain fd, which
+is where it hands off to `ei.Sender.create_for_fd()`.
+
 **Read `_cobject.py` first.** It is the smallest file with the most
 consequence: get `wrap()` vs `adopt()`, the `staticmethod()` wrapping of
 `_ref_func`/`_unref_func`, or the `_wrappable` flag wrong and the failure is
@@ -721,16 +795,17 @@ Versions are SemVer and live in two places -- `pyproject.toml` and
 `src/libei/__init__.py` -- which have to agree with each other and with the
 tag. Nothing enforces that yet.
 
-A release is an annotated, `v`-prefixed tag plus a GitHub Release:
+A release is an annotated, `v`-prefixed tag. Pushing it is the whole of it;
+PyPI is the only place a release is published, and no GitHub Release is cut:
 
 ```sh
-git tag -a v0.1.0 -m "0.1.0"
-git push origin v0.1.0
-gh release create v0.1.0 --generate-notes --prerelease
+git tag -a v0.2.0 -m "0.2.0"
+git push origin v0.2.0
 ```
 
-`--prerelease` while the API is unfrozen -- it keeps an alpha out of the
-"Latest release" slot.
+While the API is unfrozen, the pre-release signal lives in the version
+itself: a PEP 440 suffix (`0.2.0a1`) keeps a plain `pip install
+python-libei` off it, and a `0.x` version already says the API can move.
 
 Publishing runs from CI on a `v*` tag using PyPI
 [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC), so
@@ -739,22 +814,24 @@ job in `ci.yml` handles it, uploading the artifacts the `build` job already
 ran `twine check` over.
 
 That job depends on two pieces of configuration outside this repository,
-which have to exist before the first tag:
-
-1. On pypi.org, under Account settings -> Publishing, a **pending**
-   publisher -- the flow for a project that has no releases yet. Project
-   `python-libei`, owner `ctrondlp`, repository `python-libei`, workflow
-   `ci.yml`, environment `pypi`. Every field has to match the workflow
+both of which are in place as of `0.1.0`:
+
+1. On pypi.org, a trusted publisher on the `python-libei` project: owner
+   `ctrondlp`, repository `python-libei`, workflow `ci.yml`, environment
+   `pypi`. It started life as a **pending** publisher -- the flow for a
+   project with no releases yet -- and the first upload converted it into
+   an ordinary project-level one, so a fresh project is the only case that
+   needs the pending form again. Every field has to match the workflow
    exactly; a mismatch surfaces as a rejected credential at upload time,
    not when it is saved.
 2. A GitHub environment named `pypi`, in the repository settings. A
    required reviewer on it makes each publish a deliberate approval rather
    than a side effect of pushing a tag.
 
-Worth rehearsing on TestPyPI first: separate account, separate pending
-publisher, and `repository-url: https://test.pypi.org/legacy/` on the
-publish step. PyPI filenames are immutable, so a bad upload can only be
-yanked and superseded by a new version, never replaced.
+PyPI filenames are immutable, so a bad upload can only be yanked and
+superseded by a new version, never replaced -- worth rehearsing anything
+unusual on TestPyPI first (separate account, separate pending publisher,
+and `repository-url: https://test.pypi.org/legacy/` on the publish step).
 
 ## Design notes
 

{python_libei-0.1.0.dist-info → python_libei-0.3.0.dist-info}/RECORD

@@ -1,16 +1,17 @@
-libei/__init__.py,sha256=iGbXyJLQl-zAV0AMAWdEMe0WxJivQCH4NLnwmlmub2I,1511
+libei/__init__.py,sha256=ckwB3oooo2C06cgm5CFk182ieSwvWwcRtazRfmEs6nw,1676
 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=Vf0HeI5kjvTBlCv5P531ugDqclMdL5o9Qru_T80VFq4,27679
 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.1.0.dist-info/licenses/LICENSE,sha256=l6xbMU6Y-JZDzmBciBj-J5t6h6jNg_Bcyp4bHxDepqU,1074
-python_libei-0.1.0.dist-info/METADATA,sha256=aY3gXPsVdtrASfC7m1JDV7-4v0wNyv8u2LTZCQLVFqs,35447
-python_libei-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_libei-0.1.0.dist-info/top_level.txt,sha256=_DQXzGjDsUBENI_cNkiOxPB4xi8coCbQS1lq18FMudQ,6
-python_libei-0.1.0.dist-info/RECORD,,
+python_libei-0.3.0.dist-info/licenses/LICENSE,sha256=l6xbMU6Y-JZDzmBciBj-J5t6h6jNg_Bcyp4bHxDepqU,1074
+python_libei-0.3.0.dist-info/METADATA,sha256=ATlj4wSdgfKN1MOaeQa8h27ss1xC3FxrouZ3hZqSWAI,40033
+python_libei-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+python_libei-0.3.0.dist-info/top_level.txt,sha256=_DQXzGjDsUBENI_cNkiOxPB4xi8coCbQS1lq18FMudQ,6
+python_libei-0.3.0.dist-info/RECORD,,