Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,39 @@ All notable changes to python-libei are recorded here. The format follows

## [Unreleased]

## [0.5.1] - 2026-09-08

### Fixed

- **`InputCaptureSession.negotiate()` now works against pre-v2 portals**, via
the deprecated v1 `CreateSession`. Only `CreateSession2` and `Start` are
version 2 additions to the interface -- `GetZones`, `SetPointerBarriers`,
`Enable`, `Disable`, `Release` and `ConnectToEIS` are all v1 originals -- so
just session creation forks and everything after negotiating is unchanged.
On v1 a single `CreateSession` carries `capabilities` and raises the consent
dialog itself; there is no `Start` to call.

This turns out to matter on shipping systems, not just old ones:
**xdg-desktop-portal-gnome 50 reports InputCapture version 0** -- it
registers the complete impl interface (including `ConnectToEIS`, the
`Activated`/`Deactivated` signals and `SupportedCapabilities = 15`) and
simply never sets the `version` property, and the frontend derives its own
version from the impl's. Previously that raised
`PortalVersionError: InputCapture version 0 is too old for CreateSession2`
and there was no way through. Live-validated on Fedora 44 / GNOME Shell 50.0
(xdg-desktop-portal 1.21.1): negotiation returns a real EIS fd and `zones()`
answers `(0, [(1920, 1080, 0, 0)])`.

Note that such a portal's introspection XML advertises `CreateSession2`
anyway -- that XML is static and says nothing about what the frontend will
dispatch, which is why the `version` property is read first and believed.
Calling `CreateSession2` there fails with `UnknownMethod`.

The one thing v1 cannot do is persist: `persist_mode` and `restore_token`
were added to `Start`, which does not exist. Passing either against a pre-v2
portal now raises `PortalVersionError` explaining that, rather than being
silently ignored and handing back a `restore_token` of `None`.

## [0.5.0] - 2026-09-08

### Added
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ and why, is in

## Status

Beta (`0.5.0`), published on [PyPI](https://pypi.org/project/python-libei/)
Beta (`0.5.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
Expand Down
30 changes: 19 additions & 11 deletions docs/developers/verification.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# What has actually been verified

The package is beta (`0.5.0`) and the API is not frozen — expect renames
The package is beta (`0.5.1`) and the API is not frozen — expect renames
before 1.0. This page is what that qualifier covers, concretely: which paths
have been driven against real libraries, which have only ever been driven
against fakes, and which libei versions the whole thing has met.
Expand Down Expand Up @@ -36,16 +36,24 @@ By hand:
relative pointer, keyboard, absolute pointer, in that order, which is the
device race `ei`-side callers must handle; and `Session.Close()` was
exercised. No input was injected — emulation is `libei.ei`'s job.
- **`libei.portal.InputCaptureSession` (added 0.5.0) has never been run
against a real portal, unlike everything else on this list** — and unlike
the rest of `libei.portal`, its consent dialog is not the whole reason why.
Approving it exclusively diverts the approving human's own pointer,
keyboard or touch input away from their desktop for as long as the capture
stays active, so verifying it needs someone to deliberately accept that,
not merely click through a permission prompt. Designed against the shipped
D-Bus spec (`/usr/share/dbus-1/interfaces/org.freedesktop.portal.
InputCapture.xml`) and unit-tested against a fake connection reproducing
its documented shapes (`tests/test_inputcapture.py`) instead.
- **`libei.portal.InputCaptureSession` (added 0.5.0), negotiation half only**,
2026-09-08, against a real Fedora 44 / GNOME Shell 50.0 session
(xdg-desktop-portal 1.21.1). That portal reports InputCapture **version 0**,
so this exercised the **v1 `CreateSession` path**: consent dialog approved,
a real EIS fd returned, `zones()` answering `(0, [(1920, 1080, 0, 0)])`, and
`Session.Close()` exercised. The v2 `CreateSession2` -> `Start` path has
still never been run live.

**The capture half remains unverified**, and unlike the rest of
`libei.portal` its consent dialog is not the whole reason why. Approving a
capture exclusively diverts the approving human's own pointer, keyboard or
touch input away from their desktop for as long as it stays active, so
verifying `set_pointer_barriers()` / `enable()` / `wait_for_activation()`
needs someone to deliberately accept that, not merely click through a
permission prompt. Those were designed against the shipped D-Bus spec
(`/usr/share/dbus-1/interfaces/org.freedesktop.portal.InputCapture.xml`)
and unit-tested against a fake connection reproducing its documented shapes
(`tests/test_inputcapture.py`) instead.

## Which libei versions this has met

Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

[project]
name = "python-libei"
version = "0.5.0"
version = "0.5.1"
description = "Inject and receive input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis"
readme = "README.md"
license = "MIT"
Expand Down
2 changes: 1 addition & 1 deletion src/libei/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,6 @@
Beta: the API is not frozen.
"""

__version__ = "0.5.0"
__version__ = "0.5.1"

__all__ = ["__version__"]
179 changes: 133 additions & 46 deletions src/libei/portal.py
Original file line number Diff line number Diff line change
Expand Up @@ -926,6 +926,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,
Expand Down Expand Up @@ -1392,11 +1439,18 @@ def negotiate(
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
Expand Down Expand Up @@ -1435,62 +1489,95 @@ def negotiate(
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,
Expand Down
Loading
Loading