diff --git a/CHANGELOG.md b/CHANGELOG.md index 2ca338f..10b8bc3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/README.md b/README.md index bf01de6..80d75ee 100644 --- a/README.md +++ b/README.md @@ -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` diff --git a/src/libei/_capi/libei.py b/src/libei/_capi/libei.py index e6255a4..25ccfc3 100644 --- a/src/libei/_capi/libei.py +++ b/src/libei/_capi/libei.py @@ -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, diff --git a/src/libei/eis.py b/src/libei/eis.py index 68d6311..4a03631 100644 --- a/src/libei/eis.py +++ b/src/libei/eis.py @@ -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) diff --git a/tests/conftest.py b/tests/conftest.py index 6b054d6..2a05f12 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -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``. @@ -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)", ) diff --git a/tests/test_documentation_shape.py b/tests/test_documentation_shape.py index cc24794..059cf40 100644 --- a/tests/test_documentation_shape.py +++ b/tests/test_documentation_shape.py @@ -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" diff --git a/tests/test_integration_socketpair.py b/tests/test_integration_socketpair.py index e41614e..d2f3800 100644 --- a/tests/test_integration_socketpair.py +++ b/tests/test_integration_socketpair.py @@ -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() @@ -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