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
31 changes: 31 additions & 0 deletions .editorconfig
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# What an editor should do with the files in this repository, whatever editor
# that is -- VS Code, PyCharm, Vim, Emacs, Sublime and the rest read this file.
# Every setting below is the one the tree is already written in, not a
# preference being imposed on it.
#
# Line endings are the half of this that matters: a file saved with CRLF comes
# back as a whole-file diff to everyone else, and a CRLF shell script will not
# run on Linux. Git cannot see an editor's settings, so this file is paired
# with `.gitattributes`, which makes git normalize what it stores; this is what
# an editor is told before it writes.
#
# Measured rather than assumed, when this was written: every tracked file has
# LF in the index and no tracked file contains a tab.

root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
indent_style = space
indent_size = 4
trim_trailing_whitespace = true

[*.{yml,yaml,json}]
indent_size = 2

[*.md]
# Two trailing spaces are a hard line break in Markdown; trimming them would
# join lines that are meant to be apart.
trim_trailing_whitespace = false
27 changes: 27 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Line endings and binary-ness, decided by git rather than by whichever editor
# or platform last touched a file. The companion to `.editorconfig`: that one
# tells an editor what to write, and this one makes git normalize what it
# stores, which is the half an editor's settings cannot reach.
#
# Why it earns its place: this package is a Linux library (libei is) that is
# also edited from Windows, where a global `core.autocrlf` would otherwise
# check these files out with CRLF -- and a shell script with CRLF endings
# fails on Linux with a confusing "bad interpreter" error. Every tracked file
# already has LF in the index -- measured, not assumed -- so there is nothing
# to renormalize for this to take effect.
#
# `text=auto` lets git decide what is text; `eol=lf` is what it puts in the
# working tree even on Windows.
* text=auto eol=lf

# Not text at all: git must never translate these.
*.png binary
*.gif binary
*.jpg binary
*.jpeg binary
*.pdf binary
*.so binary
*.pyc binary
*.whl binary
*.zip binary
*.tar.gz binary
79 changes: 79 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,62 @@ All notable changes to python-libei are recorded here. The format follows

## [Unreleased]

## [0.6.1] - 2026-10-01

### Changed

- **The package metadata and README now say `libei.portal` captures input, and
the README counts its modules right.** `InputCaptureSession` -- receiving the
user's real pointer and keyboard through the InputCapture portal -- was in the
module docstring and nowhere a reader looks: not the PyPI description, not the
keywords, and not the README's table of what to use for what. The description
now names it, `input-capture` and `eis` join the keywords, and the table has a
row that says, as `docs/developers/verification.md` does, that only its
negotiation half has been run against a real desktop. Also the `POSIX`
operating-system classifier the other two packages carry, a `documentation` URL
and a link to pyguitest, its main consumer. The README said "Five modules"
where there are four (`ei`, `eis`, `oeffis`, `portal`; the table has five rows).
`InputCaptureSession`'s docstring said "Never live-tested", which the
verification log contradicts for its negotiation half; it now says half.

### Fixed

- **Using a released event raised `ctypes.ArgumentError`, not the documented
`RuntimeError`.** Each event is released as the loop moves on, and the README
and `docs/recipes.md` promise a `RuntimeError` if one is used afterwards. What
a caller actually got, from a real call, was
`ArgumentError: argument 1: RuntimeError: Event has already been released` --
ctypes wraps anything raised while converting an argument and keeps only its
text, so `except RuntimeError` missed it. The unit test passed because it read
`_as_parameter_` directly and never crossed ctypes; found by probing the real
library for the README's claims. `LazyLibrary` now re-raises the original
`RuntimeError` when an argument is a released object, and an ordinary bad
argument is still ctypes' own error.

- **Six bindings named no libei version, so an old library read as a mystery.**
`ei_touch_cancel`, `ei_event_touch_get_is_cancel`, `ei_event_pong_get_ping` and
their libeis counterparts arrived in libei 1.4, and
`eis_backend_socket_get_client_pid` in 1.5; none carried the `# libei X.Y+`
marker the other gated declarations do. Found by checking every declaration
against the headers of 1.0.0, 1.2.1, 1.4.0, 1.5.0 and 1.6.0. Behaviour was
already right -- the README's version table had them correctly -- so this is
the source catching up with it.

- **The docs said forgetting `frame()` means nothing happens, silently. It is
only true without `stop_emulating()`.** Measured against libei 1.2.1 and 1.6.0:
a motion queued and then followed by `stop_emulating()` is delivered, in a
`FRAME` libei adds itself, and logged as an error --
`Bug: ei_device_stop_emulating: missing call to ei_device_frame()`. Only a
queue that is never stopped is dropped with no log line at all. The README,
getting-started and troubleshooting now say so. The same probing corrected
two more claims: an event sent to a device lacking the capability is dropped
with a `Bug: ... device is not a keyboard` error log rather than "silently",
and the wrong-accessor read libei answers with zeros is likewise logged at
error level rather than "a line the caller never sees". The README's list of
versions the suite has been run against named 1.5.0, which
`docs/developers/verification.md` has no record of, and contradicted its own
Status section on CI's 1.2.1; both now agree.

- **The test suite ran nothing at all off Linux and FreeBSD.** `tests/test_loader.py`
raised at module level when `ctypes.util.find_library("c")` found no C library,
which pytest reports as a *collection* error -- so on Windows `pytest -q -rs`
Expand All @@ -23,6 +77,31 @@ All notable changes to python-libei are recorded here. The format follows
stylus protocol has landed there too. Still none of it is in a release, so still
none of it is bound.

### Tests

- **The bindings are checked against the real headers and libraries.**
`tests/test_abi.py` compares every declared function's argument count and
argument and return classes (pointer, 4- or 8-byte int, double, bool, void)
with the upstream prototype, every Python enum member with its C enumerator
value, and every declaration with the installed library's exports, where a
missing one must carry a version marker. There are no `ctypes.Structure`
bindings, so there is no layout to check. It needs the headers, via
`LIBEI_SOURCE_DIR`, and otherwise skips; see CONTRIBUTING.md. Clean against
the public headers of 1.0.0, 1.2.1, 1.4.0, 1.5.0 and 1.6.0, and against the
installed 1.6.0 (Fedora 45) and 1.2.1 (Ubuntu 24.04) libraries.
`LazyLibrary` now records what is declared on it (`declared`, `soname`) for this.
- **Every event accessor against every event type.**
`tests/test_event_accessors.py` reads the accessor list from the source, so a
new one is covered automatically, and checks that each raises `TypeError`
before any C accessor is called for every wrong type, on both the client and
server side, and that an accessor added without a guard fails. Previously one
wrong type per library was pinned.
- **Forgetting `frame()` and using a released event, against the real library.**
`tests/test_integration_frame.py` pins the four behaviours above and
`tests/test_integration_lifetime.py` the released-event error; the loader tests
gain missing-symbol behaviour (named, repeatable, the rest still working) and
one-open-under-concurrent-first-calls.

## [0.6.0] - 2026-09-22

### Added
Expand Down
18 changes: 18 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,24 @@ LD_LIBRARY_PATH=$PWD/prefix/lib64 pytest -q -rs # from this checkout

Expect passes plus skips, never failures or hangs.

### Checking the bindings against the headers

`tests/test_abi.py` compares every binding with the upstream prototypes and
enums, but only when it can find the headers. Point `LIBEI_SOURCE_DIR` at an
upstream checkout or release tarball (the directory holding `meson.build`):

```sh
for v in 1.0.0 1.2.1 1.4.0 1.6.0; do
curl -sL https://gitlab.freedesktop.org/libinput/libei/-/archive/$v/libei-$v.tar.gz | tar xz
LIBEI_SOURCE_DIR=$PWD/libei-$v pytest tests/test_abi.py -q
done
```

A failure there means a wrong argument count or width, or a wrong enum value --
or a function declared without the `# libei X.Y+` marker on its `lib.function(`
line saying which release added it. Without the headers, only the check against
the installed libraries runs, and the rest skips.

A separate job installs the package with no native libraries at all and
imports it, which is the property the lazy loader exists to provide. What has
and has not been verified, and against which libei versions, is in
Expand Down
44 changes: 29 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,11 @@ device.start_emulating().pointer_motion(5, 0).frame().stop_emulating()
```

**The one concept:** events queue up, and **`frame()` is what sends them** as
one logical hardware event. Forget it and nothing happens — no exception, no
warning, no movement. Fill the package, then post it.
one logical hardware event. Forget it and the motion is usually lost — no
exception, no warning, no movement. (Ending the chain with `stop_emulating()`
makes libei frame the queue for you, but it logs an error-level `Bug:` line
when it does; see [Things that will bite you](#things-that-will-bite-you).) Fill
the package, then post it.

New here? [docs/getting-started.md](docs/getting-started.md) is install
through a first real pointer motion, in five minutes.
Expand Down Expand Up @@ -59,15 +62,16 @@ than a widget-tree back door:

## Which API do I need?

Five modules, and most callers need exactly two of them: `oeffis` or `portal`
to get permission, then `ei` to inject.
Four modules (`ei`, `eis`, `oeffis`, `portal`), and most callers need exactly
two of them: `oeffis` or `portal` to get permission, then `ei` to inject.

| You want to… | Use | Notes |
| --- | --- | --- |
| **Inject input** into a desktop | `libei.ei` → `Sender` | The automation case. This is what the quick start below does |
| **Consume input** from a compositor | `libei.ei` → `Receiver` | Compositor-side or input-capture code; same connection dance |
| **Get permission**, simply | `libei.oeffis` | One call, pollable fd, no dependencies. The consent dialog appears on **every** run |
| **Get permission**, and not be asked again | `libei.portal` | Same handshake over D-Bus directly, with `persist_mode` / `restore_token`. Needs PyGObject |
| **Capture the user's real input** | `libei.portal` → `InputCaptureSession` | The read direction, through the InputCapture portal: once the compositor decides to, the user's pointer and keyboard are diverted to you over EIS. Exclusive while active, so hold it briefly. Only its negotiation half has been run against a real desktop — see [verification](docs/developers/verification.md) |
| **Be the server**, for tests or a compositor | `libei.eis` | Drives your client code with no real compositor and no consent dialog |

Each module has `is_available()`. `ei` and `eis` share the shapes around them:
Expand Down Expand Up @@ -130,7 +134,7 @@ and why, is in

## Status

Beta (`0.6.0`), published on [PyPI](https://pypi.org/project/python-libei/)
Beta (`0.6.1`), published on [PyPI](https://pypi.org/project/python-libei/)
since `0.1.0`, and **the API is not frozen** — expect renames before 1.0.

The injection path is exercised end to end against the real libraries by the
Expand Down Expand Up @@ -171,9 +175,13 @@ Exactly what was run, when, and against which versions:
- libei 1.0.0 or newer for the core: connecting, binding a seat, and
sending pointer, button, keyboard, scroll and touch input all use symbols
that have existed with a stable signature since 1.0.0, and upstream keeps
API/ABI back-compatible within the 1.x series. Only 1.5.0 and 1.6.0 have
actually been run against -- 1.6.0 on both Fedora 44 and FreeBSD 15, where
the injection path passes the full suite with nothing skipped.
API/ABI back-compatible within the 1.x series. The suite has been run
against 1.2.1 (Ubuntu 24.04, in CI) and 1.6.0 -- the latter on Fedora 44 and
45 and FreeBSD 15, where the injection path passes the full suite with
nothing skipped. Every binding's name, argument types and return type, and
every enum value, is also checked against the upstream headers of 1.0.0,
1.2.1, 1.4.0, 1.5.0 and 1.6.0 (`tests/test_abi.py`), which is the only
coverage 1.0.0, 1.4.0 and 1.5.0 have had.

Newer libei buys you more, per feature:

Expand Down Expand Up @@ -331,8 +339,12 @@ All four, with working code:
soon as the loop moves on, and using it afterwards raises `RuntimeError`.
Objects you pull *off* an event (`event.device`, `event.seat`) are safe to
keep — copy out `event.pointer_event` and friends rather than the event.
- **`frame()` or nothing happens.** Events queue up until a `frame()` commits
them.
- **`frame()` or the input is lost.** Events queue up until a `frame()` commits
them, and queued events that are never framed are dropped without an
exception or a log line. The one exception is a chain that ends in
`stop_emulating()`: libei frames what is queued, delivers it, and logs
`Bug: ei_device_stop_emulating: missing call to ei_device_frame()` at error
level. Measured against libei 1.2.1 and 1.6.0; don't rely on it.
- **`bind()` needs at least one capability.** Binding an empty set sends
nothing, so the device you are waiting for never arrives; this raises
`ValueError` rather than hanging.
Expand All @@ -341,20 +353,22 @@ All four, with working code:
- **One seat can resume several devices.** Bind both `POINTER` and
`POINTER_ABSOLUTE` and GNOME gives you two, relative first. Taking
whichever resumes first is a coin flip — select on `device.capabilities`
instead. Sending an event the device lacks the capability for is silently
ignored, which makes this look like the injection simply not working.
instead. Sending an event the device lacks the capability for is dropped with
no exception — libei only logs an error-level `Bug: ... device is not a
keyboard` line — which makes this look like the injection simply not working.
- **Read the accessor that matches the event type.** `event.key_event` on a
`POINTER_MOTION` event raises `TypeError` naming both types. libei itself
would have returned `KeyEvent(key=0, is_press=False)` — a real-looking
value — while logging a `Bug:` line the caller never sees, so branch on
`event_type` first. `TOUCH_UP` has its own `touch_up_event`, since it
value — and raised nothing, only logging a `Bug:` line at error level, so
branch on `event_type` first. `TOUCH_UP` has its own `touch_up_event`, since it
carries no coordinates.
- **`GESTURES` and `STYLUS` are not in any released libei.** They match
upstream `main` and are here ready for it, but 1.6.0's capability enum
stops at `TEXT`. Binding them against a shipping library silently does
nothing — no error, no device, no events.

Nearly all of these fail *silently*, which is why
Nearly all of these fail without raising — some only log an error-level `Bug:`
line, some not even that — which is why
[docs/troubleshooting.md](docs/troubleshooting.md) is a checklist rather than
a list of error messages. Start there when nothing happens.

Expand Down
27 changes: 25 additions & 2 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.6.0`) and the API is not frozen — expect renames
The package is beta (`0.6.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 @@ -79,7 +79,30 @@ By hand:
and 1.6 features gating themselves out.
- CI repeats the 1.2.1 run on Python 3.10–3.13, so the 1.0.0 core floor is
exercised on a real old build rather than asserted.
- **1.0–1.1 and 1.3 have never been run against.**
- Re-run 2026-09-30 against **1.6.0** on Fedora 45 (libei 1.6.0-3, under Python
3.15rc2) and against Ubuntu 24.04's **1.2.1** in a container: the full suite
passes on both, the 1.4 and 1.6 features gating themselves out on 1.2.1.
- **1.0–1.1 and 1.3 have never been run against** -- and neither has 1.4 or 1.5
at runtime. What they have had is the header check below.

### Checked against the headers

`tests/test_abi.py` compares every bound function's argument count, argument
classes and return class (pointer, 4-byte int, 8-byte int, double, bool, void)
with the upstream prototype, and every Python enum member's value with the C
enumerator. It needs the headers, so it runs only when `LIBEI_SOURCE_DIR` names
an upstream checkout (or an installed `libei-dev` provides them). Run on
2026-09-30 against the public headers of **1.0.0, 1.2.1, 1.4.0, 1.5.0 and
1.6.0**, with the installed 1.6.0 and 1.2.1 libraries checked for every
declared export: clean on all five once six declarations were marked with the
release that added them (touch cancellation and `pong_get_ping` on both sides
in 1.4, `eis_backend_socket_get_client_pid` in 1.5). They had no marker, so the
version each one needs was missing from the source -- an omission that cost
nothing on 1.6 and would have presented as an unexplained missing symbol on an
older library.

There are no `ctypes.Structure` bindings, so there is no layout to verify;
every object is an opaque pointer and every value crosses as a scalar.

A separate CI job installs the package with no native libraries at all and
imports it, which is the property the lazy loader exists to provide.
Expand Down
11 changes: 8 additions & 3 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,9 +37,14 @@ them as one logical hardware event**:
device.start_emulating().pointer_motion(5, 0).frame().stop_emulating()
```

Forget `frame()` and nothing happens. No exception, no warning, no movement —
which is the single most common reason a first attempt appears to do nothing
at all. Each method returns the device, so they chain.
Forget `frame()` and the motion is usually lost: queued events that are never
framed go nowhere, with no exception, no warning and no movement — the most
common reason a first attempt appears to do nothing at all. The one exception
is a chain that ends in `stop_emulating()`, as above: libei frames what is
queued for you, the pointer moves, and it logs an error-level
`Bug: ei_device_stop_emulating: missing call to ei_device_frame()`. Do not rely
on that; call `frame()` and the log stays quiet. Each method returns the
device, so they chain.

## 3. The five words you need

Expand Down
5 changes: 4 additions & 1 deletion docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,10 @@ error messages.
Work down it in order. The first three account for most cases.

1. **Did you call `frame()`?** Events queue until a frame commits them.
Without one, nothing is ever sent. No exception, no warning.
Without one they are never sent, with no exception and no warning — unless
you then called `stop_emulating()`, when libei frames them itself and logs
`Bug: ei_device_stop_emulating: missing call to ei_device_frame()` at error
level. If you see that line, add the `frame()`.

2. **Did you wait for `DEVICE_RESUMED`, not `DEVICE_ADDED`?** A device arrives
paused. libei calls sending events before it resumes "a client bug", and
Expand Down
Loading
Loading