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
60 changes: 59 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,65 @@ All notable changes to python-libei are recorded here. The format follows

## [Unreleased]

## [0.8.0] - 2026-10-20
### Added

- **A socketpair round-trip covering the event accessors no test reached.**
Found by asking which public names never appear in any test file: the
scroll, button, absolute-motion and emulating-sequence accessors on
`eis.Event`, `ei.Event.keyboard_xkb_modifiers`, and
`eis.Device.device_type`/`height` were all unexercised. Each is a ctypes
binding to a separate C symbol, so an unexercised one is where a wrong
symbol name or a wrong `restype` hides -- a mistake reading cannot catch,
only letting the library answer. Every binding was in fact correct, and
on libei 1.6 every value round-trips exactly (button 272, scroll
3.5/-2.0, discrete 120/-240, absolute 100/200, sequence 4242, modifiers
4/0/2/0). Driven in one negotiation rather than one test apiece, because
the handshake is the expensive part and the values then have to agree
within the same frame.

The absolute leg needed a region to be configured on the device. libei
1.0.0's `ei_device_pointer_motion_absolute` ends in
`if (!ei_device_in_region(device, x, y)) return;`, and with no region the
list it walks is empty, so the event was *silently* dropped -- no log, no
error, just an event that never arrived. Local libei 1.6 delivered it
anyway, which is why this only showed up on the CI runners' 1.0.x.

### Documented

- **`eis.Event.emulating_sequence` reads 0 on every libei before 1.6, no
matter what the client sent.** `eis_queue_device_start_emulating_event()`
built the event and never copied the sequence into it, so the getter
returned a zeroed struct field; upstream added the one missing
assignment in libei 1.6.0 (commit `98cd152`) and in no earlier tag.
Measured 0 on 1.2.1, 1.3.901 and 1.5.0, and 4242 on 1.6.0 -- which
covers Ubuntu 24.04 and Debian 13, so it is what most users of this
package will see. The accessor and its binding are correct; there is
simply nothing in the event to read, and because the symbol is exported
from the 1.0.0 floor up there is nothing to raise either, leaving a 0
indistinguishable from a client that really sent 0. Now stated on the
property and in the README beside `Event.touch_up_event`, the other
accessor that degrades rather than raising. The client-side
`ei.Event.emulating_sequence` is unaffected -- libei has always stored
it -- so only the EIS leg of the new round-trip test is version-gated,
and it asserts the 0 rather than skipping, which keeps the documented
claim under test on an old library instead of merely unchallenged.
`tests/conftest.py` grew `has_symbol()` for that branch: the existing
`requires_symbol` mark cannot see this class of difference, where the
symbol is present on every version and only its answer changed.

### Fixed

- **`ei_region_convert_point` was marked as needing libei 1.1, and does
not.** It is declared in libei 1.0.0's own public header and implemented
there; the marker put it alongside its genuine 1.1 neighbours
`ei_region_get_mapping_id` and `ei_device_region_at`. The weekly
declared-floor job is what caught it -- building libei 1.0.0 from source
found the symbol present where the marker promised it would be absent --
which is the job working as intended rather than a flake. The README's
version table no longer tells a reader on a 1.0.x build that
`Region.convert_point()` is out of reach, and every remaining marker was
swept against 1.0.0's real headers: 17 `ei_` and 18 `eis_` markers, none
of them contradicted.

### Added

Expand Down
20 changes: 15 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -188,17 +188,27 @@ Exactly what was run, when, and against which versions:

| Needs | For |
| --- | --- |
| 1.1 | `Region.mapping_id`, `Region.convert_point()`, `Device.region_at()` |
| 1.1 | `Region.mapping_id`, `Device.region_at()` |
| 1.4 | ping/pong round trips (`Context.new_ping()`), `Context.disconnect()`, touch cancellation (`Touch.cancel()`) |
| 1.5 | `eis.Client.pid` |
| 1.6 | `Device.text_utf8()` / `text_keysym()` and TEXT events, `Seat.request_device()`, `Eis.set_flag()` |

Nothing is resolved until it is called, so a build without one of these
costs you only that call — it raises `LibraryNotFoundError` naming the
missing symbol, while the rest of the package keeps working. The one
exception is `Event.touch_up_event`, which degrades instead of raising:
on libei older than 1.4 it reports `is_cancel=False`, since a library
with no notion of cancellation genuinely never sends one.
missing symbol, while the rest of the package keeps working. Two
accessors degrade instead of raising, because every supported version
exports the symbol and only the answer changed — so there is nothing to
resolve and nothing to report:

- `Event.touch_up_event` reports `is_cancel=False` on libei older than
1.4, since a library with no notion of cancellation genuinely never
sends one.
- `eis.Event.emulating_sequence` reads 0 on libei older than 1.6
whatever the client sent: libeis queued the start_emulating event
without ever copying the sequence into it, until 1.6.0 added the
missing assignment. A 0 on an older build is indistinguishable from a
client that really sent 0. The client-side
`ei.Event.emulating_sequence` is unaffected.

These versions were established by building libei 1.2.1 and diffing its
exported symbols against every binding here, not by reading `@since`
Expand Down
8 changes: 7 additions & 1 deletion src/libei/_capi/libei.py
Original file line number Diff line number Diff line change
Expand Up @@ -219,7 +219,13 @@
"ei_region_get_mapping_id", (c_void_p,), c_char_p
)
# x and y are in/out parameters, overwritten only when the point is inside.
region_convert_point = lib.function( # libei 1.1+
# No version marker: this one is in libei 1.0.0's own public header and
# implemented there, so every libei at or above the declared floor exports
# it. It carried `# libei 1.1+` alongside its genuine 1.1 neighbours
# `ei_region_get_mapping_id` and `ei_device_region_at`, and the weekly
# floor job caught it -- building 1.0.0 from source found the symbol
# present where the marker promised it would be absent.
region_convert_point = lib.function(
"ei_region_convert_point",
(c_void_p, POINTER(c_double), POINTER(c_double)),
c_bool,
Expand Down
13 changes: 12 additions & 1 deletion src/libei/eis.py
Original file line number Diff line number Diff line change
Expand Up @@ -944,7 +944,18 @@ def seat_capabilities(self) -> tuple[DeviceCapability, ...]:

@property
def emulating_sequence(self) -> int:
"""Sequence number of the start_emulating transaction."""
"""Sequence number of the start_emulating transaction.

Reads 0 on libei older than 1.6, whatever the client sent. libeis
queued the event without ever copying the sequence into it, so the
getter returned a zeroed struct field; upstream added the missing
assignment in libei 1.6.0. Every version from this package's 1.0.0
floor up exports the symbol, so there is nothing to raise and no
way to tell an old library apart from a client that genuinely sent
0 -- treat a 0 here as "unknown" unless you know both ends are on
1.6. :attr:`libei.ei.Event.emulating_sequence`, the receiver side
of the same transaction, is unaffected: libei has always stored it.
"""
self._require("emulating_sequence", EventType.DEVICE_START_EMULATING)
return _capi.libeis.event_emulating_get_sequence(self)

Expand Down
30 changes: 23 additions & 7 deletions tests/conftest.py
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,23 @@ def pytest_configure(config: pytest.Config) -> None:
)


def has_symbol(soname: str, symbol: str) -> bool:
"""Whether the installed native library exports ``symbol``.

The boolean behind :func:`requires_symbol`, split out for the cases
that must not skip. A test whose *subject* is present on every version
but whose *expected value* changed with one needs to run either way and
branch on the version -- see the sequence assertion in
``test_integration_socketpair.py`` -- and for that a mark is no use.
"""
import ctypes

try:
return hasattr(ctypes.CDLL(soname), symbol)
except OSError:
return False


def requires_symbol(soname: str, symbol: str) -> pytest.MarkDecorator:
"""Skip unless the installed native library exports ``symbol``.

Expand All @@ -41,13 +58,12 @@ def requires_symbol(soname: str, symbol: str) -> pytest.MarkDecorator:
and then silently produces no device, so a test waiting on one hangs
until its timeout and fails rather than skipping. Checking the symbol
up front decides before any negotiation starts.
"""
import ctypes

try:
present = hasattr(ctypes.CDLL(soname), symbol)
except OSError:
present = False
Only use this where the symbol's *absence* is the thing being handled.
Where an older library exports the symbol and answers wrongly, this
gate is blind -- reach for :func:`has_symbol` and a branch instead.
"""
return pytest.mark.skipif(
not present, reason=f"{soname} does not export {symbol} (libei too old)"
not has_symbol(soname, symbol),
reason=f"{soname} does not export {symbol} (libei too old)",
)
13 changes: 12 additions & 1 deletion tests/test_documentation_shape.py
Original file line number Diff line number Diff line change
Expand Up @@ -219,7 +219,18 @@ def test_readme_version_gated_features_are_named_with_their_versions() -> None:
("request_device", "1.6"),
("new_ping", "1.4"),
("disconnect", "1.4"),
("convert_point", "1.1"),
# `region_at`, not `convert_point`: the latter is in libei 1.0.0's
# own header, so it is not version-gated and the README no longer
# claims it is. `region_at` genuinely arrives in 1.1 and keeps that
# row pinned.
("region_at", "1.1"),
# Not in the table above it -- the table's entries raise
# `LibraryNotFoundError` on an older build, and this one cannot,
# since every supported version exports the symbol and the old
# ones merely answer 0. It is documented alongside
# `touch_up_event` as the other accessor that degrades silently,
# which is the part a reader has to be told.
("emulating_sequence", "1.6"),
):
assert feature in readme, f"{feature} is no longer documented"
assert version in readme, f"README no longer states the {version} requirement"
Expand Down
183 changes: 182 additions & 1 deletion tests/test_integration_socketpair.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,33 @@

import pytest

from conftest import requires_libei
from conftest import has_symbol, requires_libei
from libei import ei, eis

pytestmark = [pytest.mark.integration, requires_libei]

# What the client sends as its start_emulating sequence, and what the server
# should read back for it. They are the same number only on libei 1.6+:
# below that, libeis built the start_emulating event and never copied the
# sequence into it, so the getter returned a zeroed struct field for every
# client no matter what was sent. Upstream added the missing assignment in
# libei commit 98cd152, released in 1.6.0 and in no earlier tag -- measured
# 0 on 1.2.1, 1.3.901 and 1.5.0, 4242 on 1.6.0.
#
# `requires_symbol` cannot express this, which is why `has_symbol` exists:
# every version from the 1.0.0 floor up exports
# `eis_event_emulating_get_sequence`, the old ones just answer wrongly.
# `eis_set_flag` is 1.6-only and stands in for the version -- and it is a
# libeis symbol, so the library being asked is the one that answers.
#
# Decided here at import rather than in the test body both because that is
# where the suite's other version gates live, and because a branch down in
# that already-long negotiation costs more than it is worth.
_SENT_EMULATING_SEQUENCE = 4242
_READ_EMULATING_SEQUENCE = (
_SENT_EMULATING_SEQUENCE if has_symbol("libeis.so.1", "eis_set_flag") else 0
)


def test_client_connects() -> None:
server = eis.Eis.create_for_fd()
Expand Down Expand Up @@ -123,3 +145,162 @@ def test_pointer_motion_round_trips_through_negotiated_device() -> None:

assert received_motion is not None, "server never received a pointer motion event"
assert received_motion == eis.PointerEvent(dx=7, dy=3)


def test_the_accessors_no_other_test_reaches_round_trip() -> None:
"""One negotiation that drives every event accessor the suite had missed.

Found by asking which public names never appear in any test file: the
scroll, button, absolute-motion and emulating-sequence accessors on
``eis.Event``, ``ei.Event.keyboard_xkb_modifiers``, and
``eis.Device.device_type``/``height`` were all unexercised. Each is a
ctypes binding to a separate C symbol, so an unexercised one is exactly
where a wrong symbol name or a wrong ``restype`` hides -- the kind of
mistake that cannot be caught by reading, only by letting the library
answer.

Driven in one negotiation rather than one test apiece because the
expensive part is the handshake, not the assertions, and because the
values then have to survive the *same* frame: a wrong binding that
happened to return a plausible number in isolation still has to agree
with the five others here.

The modifier half goes the other way round from the rest. The server
*sends* xkb modifiers (``eis.Device.keyboard_xkb_modifiers``) and the
client *receives* them (``ei.Event.keyboard_xkb_modifiers``) -- two
different members that share a name, which is the protocol's shape and
not a duplication.
"""
server = eis.Eis.create_for_fd()
client_fd = server.add_client()
sender = ei.Sender.create_for_fd(client_fd, name="accessor-probe")

caps = (
eis.DeviceCapability.POINTER,
eis.DeviceCapability.POINTER_ABSOLUTE,
eis.DeviceCapability.BUTTON,
eis.DeviceCapability.SCROLL,
eis.DeviceCapability.KEYBOARD,
)
client_caps = (
ei.DeviceCapability.POINTER,
ei.DeviceCapability.POINTER_ABSOLUTE,
ei.DeviceCapability.BUTTON,
ei.DeviceCapability.SCROLL,
ei.DeviceCapability.KEYBOARD,
)

seen: dict[str, object] = {}
wanted = {
"button",
"scroll",
"scroll_discrete",
"absolute",
"sequence",
"modifiers",
}
device_created = False
emulated = False

deadline = time.monotonic() + 30.0
fds: dict[int, eis.Eis | ei.Sender] = {server.fd: server, sender.fd: sender}

while not wanted <= seen.keys() and time.monotonic() < deadline:
ready, _, _ = select.select(list(fds), [], [], 0.2)
for fd in ready:
fds[fd].dispatch()

for server_event in server.events:
kind = server_event.event_type
if kind is eis.EventType.CLIENT_CONNECT:
server_event.client.connect()
seat = server_event.client.new_seat("accessor-seat")
seat.configure_capabilities(caps)
seat.add()
elif kind is eis.EventType.SEAT_BIND and not device_created:
device_created = True
assert server_event.seat is not None
server_device = server_event.seat.new_device()
# The region is not decoration: absolute motion is defined
# *in the device's region*, so a device configured with
# POINTER_ABSOLUTE and no region has nowhere to put the
# point and libeis drops the event. Local libei 1.6 happened
# to deliver it anyway; the libei the CI runners install did
# not, and the stricter behaviour is the correct one to write
# against. (100, 200) sits inside this rectangle, and
# `mapping_id` is deliberately left unset -- it needs libei
# 1.1, which the declared-floor job does not have.
# No `size`: libeis refuses one on a VIRTUAL device
# ("Device type physical required for size"), and the region
# is what an absolute device actually needs.
server_device.configure(
name="accessor-device",
capabilities=caps,
regions=(eis.ConfigureRegion(offset=(0, 0), size=(1920, 1080)),),
)
server_device.add()
server_device.resume()
seen["device_type"] = server_device.device_type
seen["height"] = server_device.height
# The server-to-client direction, which has no event on this
# side to observe -- the assertion for it is on the client.
server_device.keyboard_xkb_modifiers(4, 0, 2, 0)
elif kind is eis.EventType.BUTTON_BUTTON:
seen["button"] = server_event.button_event
elif kind is eis.EventType.SCROLL_DELTA:
seen["scroll"] = server_event.scroll_event
elif kind is eis.EventType.SCROLL_DISCRETE:
seen["scroll_discrete"] = server_event.scroll_discrete_event
elif kind is eis.EventType.POINTER_MOTION_ABSOLUTE:
seen["absolute"] = server_event.pointer_absolute_event
elif kind is eis.EventType.DEVICE_START_EMULATING:
seen["sequence"] = server_event.emulating_sequence

for sender_event in sender.events:
kind = sender_event.event_type
if kind is ei.EventType.SEAT_ADDED and sender_event.seat is not None:
sender_event.seat.bind(client_caps)
elif kind is ei.EventType.KEYBOARD_MODIFIERS:
seen["modifiers"] = sender_event.keyboard_xkb_modifiers
elif (
kind is ei.EventType.DEVICE_ADDED
and sender_event.device is not None
and not emulated
):
emulated = True
client_device = sender_event.device
client_device.start_emulating(sequence=_SENT_EMULATING_SEQUENCE)
client_device.button(272, True)
client_device.scroll_delta(3.5, -2.0)
client_device.scroll_discrete(120, -240)
client_device.pointer_motion_absolute(100.0, 200.0)
client_device.frame()
client_device.stop_emulating()

missing = sorted(wanted - seen.keys())
assert not missing, f"never observed: {missing}"

assert seen["button"] == eis.ButtonEvent(button=272, is_press=True)
assert seen["scroll"] == eis.ScrollEvent(dx=3.5, dy=-2.0)
assert seen["scroll_discrete"] == eis.ScrollDiscreteEvent(dx=120, dy=-240)
assert seen["absolute"] == eis.PointerAbsoluteEvent(x=100.0, y=200.0)
# The read itself stays unconditional -- calling the getter is what
# proves its symbol name and restype, which is this test's whole point.
# Only the expected value is version-dependent; see
# `_READ_EMULATING_SEQUENCE` above for why. Asserting the 0 below 1.6
# rather than skipping is deliberate: it is what
# `eis.Event.emulating_sequence` documents, so an old library keeps
# that claim under test instead of leaving it unchallenged.
assert seen["sequence"] == _READ_EMULATING_SEQUENCE
assert seen["modifiers"] == ei.XkbModifiersEvent(
depressed=4, latched=0, locked=2, group=0
)
# `height` is 0 here, and exactly 0 is the right assertion rather than a
# type check: it reports a *configured size*, which libeis accepts only
# on a PHYSICAL device, so a VIRTUAL one like this is unsized by
# definition. The region above does not change it -- a region is where
# the device maps to, not how big the device is. device_type is whatever
# libeis assigns a device this package created, so only its being a real
# member of the enum is claimed.
assert seen["device_type"] in tuple(eis.DeviceType)
assert seen["height"] == 0
Loading