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
111 changes: 111 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,117 @@ All notable changes to python-libei are recorded here. The format follows

## [Unreleased]

## [0.8.2] - 2026-11-13

### Added

- **Round-trip coverage for the socket backend, `SEAT_BIND` and
`scroll_stop`/`scroll_cancel`.** Three more groups of public names that
no test reached, found the same way as 0.8.1's sweep.
`create_for_socket()` on both sides is a whole *transport* the fd-backend
tests never take, and the only one that can answer `eis.Client.pid` —
`eis_backend_socket_get_client_pid` reads a live `SO_PEERCRED`
credential, so with client and server in one process the reported pid has
to be exactly `os.getpid()`. That symbol is libei 1.5+ while the
transport itself is on the 1.0.0 floor, so the round trip runs
everywhere and only the pid read is version-gated. `SEAT_BIND` exercises
`eis_event_seat_has_capability` at the value level, with the offer and
the bind each passing their capabilities in a different order so the
asserted result can match neither by accident.
`scroll_stop`/`scroll_cancel` set their two axes asymmetrically, so a
getter wired to the wrong axis symbol disagrees with what was sent.

### Documented

- **`*_get_context()` is not quite as unbound as the docs said.** The
"deliberately unbound" list in `docs/developers/architecture.md` and the
matching bullet in `docs/vs-snegg.md` both claimed the whole
`*_get_context()` family has nothing to hand back and is therefore not
bound. The two *device* variants are in fact bound and used internally:
when the caller gives `frame()` no `timestamp`, it reads the device's own
context to get one, because `ei_now()` needs a context. What is true of
all of them is that none is ever *surfaced* — a context only ever
reaches Python through its own `create_for_*()`, never wrapped from a raw
pointer — which is the claim the docs now make. The seat, keymap and
client variants stay genuinely unbound.

- **There is no C-level logging for liboeffis.** `docs/recipes.md`'s
Logging section listed `libei.oeffis` alongside `libei.ei` and
`libei.eis` as a logger carrying routed C diagnostics. liboeffis exposes
no log-handler entry point to hook, so nothing of the sort reaches it;
that logger carries only this package's own messages. Named explicitly
rather than quietly dropped from the list, since "no output on that
logger" is otherwise indistinguishable from a library that has gone
quiet.

### Fixed

- **The `version` property reply is checked before it is believed.** Both
portals' version reads unpacked a `Properties.Get` reply on faith. As
everywhere in this module, `_call_sync` is given no `reply_type`, so
GDBus validates nothing about the shape that comes back — which is why
every other reply-consuming site here checks the unpacked value first.
These two did not: a reply that did not unpack to a single value raised
`ValueError` out of the tuple assignment, and a non-numeric `version`
raised `TypeError` from `int()`, both bare built-ins escaping the
`except PortalError` that `docs/troubleshooting.md` promises covers the
negotiation. They now raise `PortalProtocolError` with the reply as the
payload, like the `Response` and fd-index faults beside them. A `True` is
refused too rather than read as version 1 — `bool` is an `int`, so it
would otherwise have been reported as a portal too old for
`ConnectToEIS`, blaming the version for a reply that was nonsense.
Verified against a live portal rather than a stub: on Ubuntu 26.10
(GNOME/Wayland) the real `org.freedesktop.portal.Desktop` answered
RemoteDesktop version 2 through this path, and six malformed shapes —
two values, none, a non-tuple, a string, a `True` and a `None` — each
arrived as a `PortalProtocolError` catchable as `PortalError`. With the
check removed, the same six produced a bare `ValueError`/`TypeError` or
silently returned the nonsense as a version. Reading a property needs no
session and so no consent dialog, which is what makes this path
reachable over a plain login.
- **A failed second signal subscription no longer leaks the first.**
`_wait_for_signal` took its two `signal_subscribe()` handles into locals
before the `try`/`finally` that unsubscribes them, so a failure in the
second left the first registered for the life of the connection with
nothing holding its handle. Collected into a list as they are made and
unsubscribed from that list, which is what `_request` already does.

- **`ConnectToEIS`'s fd reply was trusted in three ways it should not have
been, one of which handed out `-1` as the EIS fd.** The reply is `(h)` —
an *index* into an fd list carried out-of-band — and `_call_for_fd()`
passed the index straight to `g_unix_fd_list_get()`. Measured against
GLib 2.90.1 and the Gio-2.0.gir contract, that is wrong three times
over:

- The out fd list is **nullable**. A well-formed reply that attached no
fds arrives as `None`, and dereferencing it raised `AttributeError`
('NoneType' object has no attribute 'get') — a name no
`except PortalError` catches.
- A bad index is a **programmer error**, not a runtime failure.
`g_unix_fd_list_get()` asserts `index >= 0 && index < nfd`, logs
`GLib-GIO-CRITICAL`, and returns `-1` *without raising and without
setting a `GError`*. So the previous attempt at hardening this — an
`except GLib.Error` around the `get()`, reporting "no matching fd" —
could never fire for the case it was written for. The `-1` flowed out
as the session's `eis_fd` instead, into an
`ei.Sender.create_for_fd()` that has no guard against a negative one,
with `close()`'s `os.close(-1)` swallowing the resulting `EBADF` at
debug level. The fix is the bounds check the GIR itself prescribes,
against `get_length()` — `lookup()` would do it in one call but is
GLib 2.90+ only.
- The one failure `get()` *does* raise for is the dup it performs to
hand back an owned fd, i.e. running out of file descriptors. That is
still caught, and the message now says so rather than blaming the
index.

All three now raise `PortalProtocolError`, carrying the index as
`.payload`, so a caller's `except PortalError` covers the fd leg of the
negotiation as it already covered the signal payloads. The suite's
`FakeUnixFDList` grew the real semantics to match — it holds a list of
fds, returns `-1` for an out-of-range index and never raises — because
the old one ignored its index entirely, which made every index valid and
was why the gap went unnoticed.

## [0.8.1] - 2026-11-11

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

## Status

Beta (`0.8.1`), published on [PyPI](https://pypi.org/project/python-libei/)
Beta (`0.8.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
Expand Down
15 changes: 12 additions & 3 deletions docs/developers/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,9 +51,18 @@ deliberate:
instead, so text containing a NUL is not truncated.
- `ei_new()` — superseded by `ei_new_sender()` / `ei_new_receiver()`.
- `*_clock_set_now_func()`.
- The `*_get_context()` accessors, which have nothing to hand back: a context
is only ever created by its own `create_for_*()`, never wrapped from a raw
pointer.

One accessor pair sits on the line between bound and not. Of the
`*_get_context()` accessors the headers export, the two device variants —
`ei_device_get_context` and `eis_device_get_context` — *are* bound and *are*
used internally: when the caller gives `frame()` no `timestamp`, it reads
the device's own context to get one (`ei_now()` needs a context). A caller
who passes a timestamp never reaches the accessor. The seat, keymap and
client variants stay unbound, and what the
package never does with the two it binds is *wrap* the returned pointer into
a `Context` object: a context only ever reaches Python through its own
`create_for_*()`, never from a raw pointer, so there is no public
`Device.context` accessor to hand one back.

The gesture and stylus functions that libei's `main` branch adds -- 46 in
libei and 51 in libeis against 1.6.0's headers, counted 2026-09-30: the
Expand Down
2 changes: 1 addition & 1 deletion 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.8.1`) and the API is not frozen — expect renames
The package is beta (`0.8.2`) 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
13 changes: 9 additions & 4 deletions docs/recipes.md
Original file line number Diff line number Diff line change
Expand Up @@ -337,10 +337,10 @@ against the real library.

## Logging

libei's own diagnostics are routed into Python's `logging` — the `libei.ei`,
`libei.eis` and `libei.oeffis` loggers — rather than being written to stderr
by the C library. This is how you see the warnings that otherwise look like
nothing happening at all, `device is not an absolute pointer` among them:
libei's and libeis's own diagnostics are routed into Python's `logging` — the
`libei.ei` and `libei.eis` loggers — rather than being written to stderr by the
C library. This is how you see the warnings that otherwise look like nothing
happening at all, `device is not an absolute pointer` among them:

```python
import logging
Expand All @@ -352,3 +352,8 @@ At `DEBUG` this is a full protocol trace (every object, message and signature,
both directions — a few hundred lines for a single connect and one pointer
motion), which makes it the first thing to reach for when a negotiation
stalls. `WARNING` gets you just libei's complaints.

There is no equivalent for liboeffis: it exposes no log-handler entry point to
hook, so no C-library diagnostics reach the `libei.oeffis` logger. That logger
carries only this package's own messages — a single `DEBUG` line when an oeffis
event of an unrecognised type arrives — never routed C diagnostics.
2 changes: 1 addition & 1 deletion docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ import each from the module that raises it.
| `libei.portal` | `PortalTimeoutError` | A step was accepted and never answered. Carries `.step` and `.timeout` |
| `libei.portal` | `PortalDeniedError` | `CreateSession`, `SelectDevices` or `Start` came back non-zero — an explicit decline, or any other code the spec does not distinguish from one. Carries `.step` and `.message` |
| `libei.portal` | `PortalSessionClosedError` | The session was ended from the compositor's side while a wait was outstanding — a restart, the portal dying, capture revoked from a settings panel. Carries `.step` |
| `libei.portal` | `PortalProtocolError` | A portal signal's payload does not match the spec — either the `(session_handle, options)` shape or a value inside it (`activation_id`, `cursor_position`, `barrier_id`). Carries `.step`, `.payload`, and `.detail` (`None` for a shape fault, a phrase naming the field for a value fault) |
| `libei.portal` | `PortalProtocolError` | What the portal sent back does not match the spec. Either a signal's payload — the `(session_handle, options)` shape, or a value inside it (`activation_id`, `cursor_position`, `barrier_id`) — or `ConnectToEIS`'s fd reply: no fd list attached to it at all, an fd index outside the list it did attach, or the dup of that fd failing because the process is out of descriptors. Carries `.step`, `.payload` (the fd index, for the fd-reply cases), and `.detail` (`None` for a signal-shape fault, a phrase naming the field or the fd fault otherwise) |
| `libei.ei`, `libei.eis`, `libei.oeffis` | `LibraryNotFoundError` | The native library is missing or too old to export the function being called. A `RuntimeError`, and raised at the first *call* — see below |

Which of those to catch depends on the families, because they do not nest under
Expand Down
14 changes: 9 additions & 5 deletions docs/vs-snegg.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,11 +78,15 @@ mechanism ended up shaped the way they did.
logging-context accessors, `*_event_type_to_string()`, the
NUL-terminated `*_device_text_utf8()` (the `_with_length` form is bound
instead, so a str containing a NUL isn't silently truncated), and the
`*_get_context()` accessors, which have nothing to return: a context is
only ever created by its own `create_for_*()`, never wrapped from a raw
pointer. The README's "What's implemented" section says the same in
user-facing terms, so a caller finds out from the docs rather than from
an `AttributeError`.
seat, keymap and client `*_get_context()` accessors. (The two *device*
variants are bound and used internally by `frame()`, but none of the
family is ever surfaced: a context is only ever created by its own
`create_for_*()`, never wrapped from a raw pointer.) The README's
"What's implemented" section covers the same ground in user-facing
terms, so a caller finds out from the docs rather than from an
`AttributeError`; which of these are bound-but-internal rather than
unbound is spelled out in
[developers/architecture.md](developers/architecture.md).

- **Accessors check the event type.** libei's data accessors don't report a
mismatch to the caller: `ei_event_keyboard_get_key()` on a pointer event
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.8.1"
version = "0.8.2"
description = "Inject, receive and capture input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis, plus the RemoteDesktop and InputCapture portals"
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.8.1"
__version__ = "0.8.2"

__all__ = ["__version__"]
Loading
Loading