python-libei 0.7.0__py3-none-any.whl → 0.8.1__py3-none-any.whl

libei/__init__.py

@@ -31,6 +31,6 @@ the full breakdown, including which features need which libei version.
 Beta: the API is not frozen.
 """
 
-__version__ = "0.7.0"
+__version__ = "0.8.1"
 
 __all__ = ["__version__"]

libei/_capi/libei.py

@@ -219,7 +219,13 @@ region_get_mapping_id = lib.function(  # libei 1.1+
     "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,

libei/ei.py

@@ -372,8 +372,7 @@ class Region(CObject):
 
         Returns the point with the region's offset subtracted, or ``None``
         if it falls outside the region -- which is also how you test
-        membership without a second :meth:`contains` call. Requires
-        libei 1.1.
+        membership without a second :meth:`contains` call.
         """
         # x/y are in-out parameters: libei overwrites them only when the
         # point is inside, so the return value has to gate reading them.
@@ -1127,7 +1126,10 @@ class Context(CObject):
             pointer = _capi.libei.get_event(self)
             if not pointer:
                 break
-            event = Event.wrap(pointer)
+            # adopt(), not wrap(): ei_get_event() transfers ownership of
+            # the returned reference to the caller, and the unref in
+            # release() below is the one that balances it.
+            event = Event.adopt(pointer)
             assert event is not None
             # try/finally, not a bare call after yield: breaking out of a
             # `for event in ctx.events:` loop (or an exception propagating

libei/eis.py

@@ -944,7 +944,18 @@ class Event(CObject):
 
     @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)
 
@@ -1150,7 +1161,10 @@ class Eis(CObject):
             pointer = _capi.libeis.get_event(self)
             if not pointer:
                 break
-            event = Event.wrap(pointer)
+            # adopt(), not wrap(): eis_get_event() transfers ownership of
+            # the returned reference to the caller, and the unref in
+            # release() below is the one that balances it.
+            event = Event.adopt(pointer)
             assert event is not None
             # See ei.Context.events: try/finally so release() still runs
             # if the caller breaks out of the loop (GeneratorExit at the
@@ -1168,9 +1182,11 @@ class Eis(CObject):
     def set_flag(self, flag: Flag) -> None:
         """Change this context's protocol behavior. Requires libei 1.6.
 
-        Must be called before the backend is set up, so in practice
-        before :meth:`create_for_fd` / :meth:`create_for_socket` -- which
-        also means this is only reachable on a context built by hand.
+        Must be called before the backend is set up, so the supported
+        way to use it is the ``flags`` parameter of
+        :meth:`create_for_fd` / :meth:`create_for_socket`, which apply
+        each flag at exactly that point; calling it directly only works
+        on a context built by hand, before its backend is set up.
         Takes one flag, never a bitmask; call it again for another.
         """
         result = _capi.libeis.set_flag(self, flag)

libei/portal.py

@@ -90,6 +90,8 @@ __all__ = [
     "PortalVersionError",
     "PortalDeniedError",
     "PortalTimeoutError",
+    "PortalSessionClosedError",
+    "PortalProtocolError",
     "RemoteDesktopSession",
     "Activation",
     "InputCaptureSession",
@@ -185,6 +187,53 @@ class PortalDeniedError(PortalError):
         self.message = message
 
 
+class PortalProtocolError(PortalError):
+    """A portal signal arrived with a payload that does not match the spec.
+
+    Every signal :func:`_wait_for_signal` waits on is specified as
+    ``(o session_handle, a{sv} options)``, and two kinds of mismatch used
+    to fail in two different, equally unhelpful ways. The *shape* being
+    wrong -- an empty tuple, a non-string handle, a wrong-length tuple, a
+    non-dict options -- either raised ``IndexError`` *inside* the GLib
+    signal callback, where PyGI prints the traceback to stderr and
+    swallows it so the wait hung invisibly (unboundedly, with
+    ``timeout=None``), or slipped through to the caller and crashed it with
+    ``ValueError``/``AttributeError``. A *value* inside a correctly-shaped
+    options being wrong -- an ``activation_id`` that is not an integer, a
+    ``cursor_position`` that is not two numbers -- crashed the caller later
+    still, doing arithmetic on it. Both now end the wait with this error.
+
+    ``detail`` distinguishes the two: ``None`` for a shape fault (the
+    default message names the expected shape), a phrase for a value fault
+    (naming the field). ``payload`` is whatever best shows the fault -- the
+    whole signal tuple for a shape fault, the options dict for a value one.
+
+    :func:`_request` raises it the same way for a ``Request``'s
+    ``Response`` reply that does not match its own ``(u response, a{sv}
+    results)`` shape, and :meth:`InputCaptureSession.zones` for a result
+    value that is not the type the spec gives it -- always with a
+    ``detail`` phrase, since the default shape message above is specific
+    to the session signals. ``step`` is then the method name, matching the
+    sibling errors raised from the same call.
+    """
+
+    def __init__(self, step: str, payload: object, detail: str | None = None) -> None:
+        """Name the signal, what arrived, and -- for a value fault -- which."""
+        reason = detail or (
+            "the portal spec gives it the shape (session_handle, options dict)"
+        )
+        super().__init__(
+            f"{step} arrived with a malformed payload: {reason}, got {payload!r}"
+        )
+        # `step` mirrors the attribute every sibling portal error raised
+        # from the same `_wait_for_signal` call site carries
+        # (PortalTimeoutError, PortalSessionClosedError), so a caller that
+        # catches PortalError and reads `.step` works across all of them.
+        self.step = step
+        self.payload = payload
+        self.detail = detail
+
+
 class PortalSessionClosedError(PortalError):
     """The portal session ended while something was still waiting on it.
 
@@ -416,6 +465,18 @@ def _request(
     for 60 seconds means the answer arrives inside 60 seconds, not inside
     however many 60-second waits the sequence happens to be built from.
 
+    A ``Response`` whose payload does not match the spec's ``(u response,
+    a{sv} results)`` shape raises :class:`PortalProtocolError` rather than
+    being unpacked on faith -- the same hardening `_wait_for_signal`
+    applies to the signals it waits on, and for the same two reasons: a
+    wrong-arity payload used to raise inside the GLib callback, where PyGI
+    swallows it, degrading the step to a full-timeout
+    :class:`PortalTimeoutError`; a non-dict ``results`` instead slipped
+    through to the caller, whose ``.get()`` crashed with a raw
+    ``AttributeError`` past ``except PortalError``. The guarantee callers
+    rely on is therefore structural: what this returns is always an
+    ``int`` code and a ``dict`` of results.
+
     ``trailing_args``, appended after ``options`` in the call's parameter
     tuple, exists for ``InputCapture.SetPointerBarriers`` -- the one
     Request-returning method in either portal whose ``options`` is not its
@@ -433,12 +494,28 @@ def _request(
 
     loop = GLib.MainLoop()
     result: dict[str, Any] = {}
+    malformed: dict[str, Any] = {}
     subscriptions: list[Any] = []
     # Set inside the timeout callback rather than inferred from an empty
     # `result` afterwards: a Response carrying no results is legitimate
     # (SelectDevices answers with an empty dict), so "did the loop end
     # because it timed out" has to be recorded, not deduced.
     timed_out = False
+    # Distinct from `timed_out`: whether `on_timeout` ran at all, either
+    # path -- the flag the cleanup below keys "already removed?" on. See
+    # the matching pair in `_wait_for_signal`.
+    timeout_fired = False
+
+    def _settled() -> bool:
+        """Whether some terminal outcome has already been recorded.
+
+        Same role as in `_wait_for_signal`: GLib dispatches every source
+        ready in one main-context iteration regardless of an earlier
+        ``loop.quit()``, so a Response and the deadline can both fire in
+        the same poll -- the first recorded outcome wins, and a delivered
+        reply is never dropped for a timeout (or vice versa).
+        """
+        return bool(result) or bool(malformed) or timed_out
 
     def on_response(
         _conn: Any,
@@ -450,14 +527,42 @@ def _request(
         *_a: Any,
     ) -> None:
         """Record the first reply and quit the loop; later replies are ignored."""
-        if result:  # both subscriptions may fire; the first reply wins
+        if _settled():  # both subscriptions may fire; the first reply wins
             return
-        result["code"], result["results"] = params.unpack()
+        args = params.unpack()
+        # Checked here, raised only after the loop: this runs inside a
+        # GLib callback, where PyGI prints an exception to stderr and
+        # swallows it -- a bare raise on a malformed Response would leave
+        # the loop running until the full timeout, misreported as
+        # PortalTimeoutError; a non-dict `results` let through instead
+        # crashed the caller's `.get()` with a raw AttributeError past
+        # `except PortalError`. Same hardening `_wait_for_signal` applies
+        # to the signals it waits on.
+        if (
+            not isinstance(args, tuple)
+            or len(args) != 2
+            or isinstance(args[0], bool)
+            or not isinstance(args[0], int)
+            or not isinstance(args[1], dict)
+        ):
+            malformed["args"] = args
+            loop.quit()
+            return
+        result["code"], result["results"] = args
         loop.quit()
 
     def on_timeout() -> bool:
         """Stop the loop and record that it timed out rather than finished."""
-        nonlocal timed_out
+        nonlocal timed_out, timeout_fired
+        # Set first, before the early return: GLib removes the source the
+        # moment this returns False (which both paths do), so the finally
+        # block keys "already removed" on this, not on `timed_out` -- see
+        # the same dance in `_wait_for_signal`.
+        timeout_fired = True
+        if _settled():
+            # A Response delivered in the same poll as the deadline has
+            # already recorded its outcome; do not overwrite it.
+            return False
         timed_out = True
         loop.quit()
         return False  # one-shot; GLib removes the source when this is False
@@ -501,12 +606,14 @@ def _request(
         handle = _returned_handle(reply)
         if handle is not None and handle != expected_path:
             subscribe(handle)
-        # `if not result` because a synchronous answer (a fast
+        # `if not _settled()` because a synchronous answer (a fast
         # non-interactive Response, or a test double) can arrive during the
         # call above, before run() is reached -- and quit() on a loop that
         # is not running yet does not stop the later run(), so running it
-        # then would block with the reply already delivered.
-        if not result:
+        # then would block with the reply already delivered. A malformed
+        # synchronous reply counts: it too has already quit a loop that
+        # was not running yet.
+        if not _settled():
             timeout_source = GLib.timeout_add(_msec_until(deadline), on_timeout)
             try:
                 loop.run()
@@ -518,12 +625,27 @@ def _request(
                 # fixed for _wait_for_signal below. Only remove it when the
                 # *Response* woke the loop instead; leaving a live source in
                 # that case holds a reference to this closure and fires it
-                # into a dead loop on some later request.
-                if not timed_out:
+                # into a dead loop on some later request. Keyed on
+                # `timeout_fired` (did on_timeout run), not `timed_out` (did
+                # the wait time out): a Response landing in the same poll as
+                # the deadline runs on_timeout down its `_settled` early
+                # return, which removes the source yet leaves `timed_out`
+                # False.
+                if not timeout_fired:
                     GLib.source_remove(timeout_source)
     finally:
         for subscription in subscriptions:
             connection.signal_unsubscribe(subscription)
+    # Mirrors `_signal_outcome`: only one of these is ever set (every
+    # callback checks `_settled()` first), so the order here only decides
+    # between genuinely simultaneous dispatches.
+    if malformed:
+        raise PortalProtocolError(
+            method,
+            malformed["args"],
+            "the Request's Response signal is specified as "
+            "(uint response, results dict)",
+        )
     if timed_out:
         raise PortalTimeoutError(method, timeout)
     return result["code"], result["results"]
@@ -1021,6 +1143,114 @@ def _create_input_capture_session_v1(
     return session_handle
 
 
+def _classify_signal_payload(
+    args: tuple[Any, ...], session_handle: str, signal: str
+) -> str:
+    """How `_wait_for_signal` should treat one unpacked signal payload.
+
+    ``"take"`` -- it is this session's, correctly shaped, record it.
+    ``"drop"`` -- another session's; keep waiting (logged, since a dropped
+    signal is otherwise indistinguishable from one that never fired).
+    ``"malformed"`` -- not the ``(o session_handle, a{sv} options)`` shape
+    the spec gives every signal here.
+
+    Two shape checks with the session filter between them, so how a
+    malformed payload is treated depends on how it is broken. A payload
+    whose *options* are the wrong shape (the second check) is reached only
+    after the filter has matched its handle, so another session's is already
+    dropped before that check runs -- it is raised only for this session. A
+    payload with no first element, or one that is not a string, cannot be
+    matched to any session at all: there is no handle to compare it with, so
+    it is malformed for every possible waiter and is raised here whichever
+    session it might have been meant for -- the filter cannot run before it,
+    only after. In the single-session process this almost always is, the
+    distinction never arises.
+    """
+    if not args or not isinstance(args[0], str):
+        return "malformed"
+    if args[0] != session_handle:
+        logger.debug(
+            "ignoring %s for session %s while waiting for %s",
+            signal,
+            args[0],
+            session_handle,
+        )
+        return "drop"
+    if len(args) != 2 or not isinstance(args[1], dict):
+        return "malformed"
+    return "take"
+
+
+def _spec_int(value: Any) -> int:
+    """``int(value)`` for a spec ``u``/``i``, refusing a silent truncation.
+
+    A portal integer field arrives as a Python ``int``. A malformed portal
+    that put a ``d`` (double) there would still reach ``int()``, and
+    ``int(0.9) == 0`` / ``int(1.9) == 1`` truncates it *silently* -- a zone
+    coordinate or a refused barrier id quietly becomes a different,
+    valid-looking value rather than an error. Reject any ``float``
+    (``inf``/``nan`` included) with the ``ValueError`` the surrounding
+    guards already turn into a :class:`PortalProtocolError`, so an off-spec
+    fractional value is refused on the same footing as a non-numeric one.
+    """
+    if isinstance(value, float):
+        raise ValueError("a fractional value where the spec gives an integer")
+    return int(value)
+
+
+def _deactivation_id(options: dict[str, Any], signal: str) -> int:
+    """The ``activation_id`` from Deactivated's options, as the spec's ``u``.
+
+    ``_wait_for_signal`` checks the payload's *shape* -- that options is a
+    dict -- but not the types of the values in it. ``activation_id`` is a
+    ``u``, and a non-conforming portal that put something else there would
+    crash the caller with ``ValueError``/``TypeError``/``OverflowError``
+    past the shape check. Converting it here turns that into the same typed
+    :class:`PortalProtocolError` the shape check raises, so a caller that
+    guards against malformed signals catches one error, not two.
+    """
+    try:
+        return _spec_int(options.get("activation_id", 0))
+    except (ValueError, TypeError, OverflowError) as exc:
+        raise PortalProtocolError(
+            signal, options, "activation_id is not an integer"
+        ) from exc
+
+
+def _activation_from_options(options: dict[str, Any], signal: str) -> Activation:
+    """Build an :class:`Activation` from Activated's options, spec-typed.
+
+    The companion to the shape check in ``_wait_for_signal`` for the value
+    level: every field the portal spec types is converted here under one
+    guard, so a non-conforming value in any of them -- an ``activation_id``
+    that is not a ``u``, a ``cursor_position`` that is not two ``d``s, a
+    ``barrier_id`` that is not a ``u`` -- becomes the same typed
+    :class:`PortalProtocolError` rather than a crash in the caller later,
+    doing arithmetic on a string. One guard rather than three means the
+    next field added to the signal is validated by construction, not by a
+    fourth hand-rolled check nobody remembers to write.
+    """
+    try:
+        activation_id = _spec_int(options.get("activation_id", 0))
+        cursor = options.get("cursor_position")
+        if cursor is None:
+            cursor_position = None
+        else:
+            cx, cy = cursor  # (dd): exactly two, or this unpacking raises
+            cursor_position = (float(cx), float(cy))
+        barrier = options.get("barrier_id")
+        barrier_id = None if barrier is None else _spec_int(barrier)
+    except (ValueError, TypeError, OverflowError) as exc:
+        raise PortalProtocolError(
+            signal, options, "an option value is not the type the spec gives it"
+        ) from exc
+    return Activation(
+        activation_id=activation_id,
+        cursor_position=cursor_position,
+        barrier_id=barrier_id,
+    )
+
+
 def _wait_for_signal(
     connection: Any,
     Gio: Any,
@@ -1056,12 +1286,41 @@ def _wait_for_signal(
     D-Bus specification restricts plain ``arg0=`` match rules to arguments
     of type STRING, and this one is an OBJECT_PATH, which is the same shape
     of silent non-delivery all over again.
+
+    A payload that does not match the spec's ``(o session_handle, a{sv}
+    options)`` shape raises :class:`PortalProtocolError` rather than being
+    unpacked on faith -- see that class for why the alternative was not an
+    exception but a hang.
     """
     loop = GLib.MainLoop()
     result: dict[str, Any] = {}
+    malformed: dict[str, Any] = {}
     timed_out = False
+    # Distinct from `timed_out`: whether `on_timeout` ran at all, either
+    # path. `on_timeout` returns False whichever branch it takes, and False
+    # is what makes GLib deregister the source -- so the finally block must
+    # key its "already removed?" check on "did on_timeout fire", not on "did
+    # the wait time out". When a signal and the deadline land in the same
+    # poll, on_timeout takes the `_settled()` early return (leaving
+    # `timed_out` False) yet its False return still removed the source;
+    # keying on `timed_out` there would double-remove it and trip the very
+    # "Source ID N was not found" critical the guard exists to avoid.
+    timeout_fired = False
     session_closed = False
 
+    def _settled() -> bool:
+        """Whether some terminal outcome has already been recorded.
+
+        GLib dispatches every source ready in one main-context iteration,
+        regardless of an earlier ``loop.quit()``, so two outcomes -- a
+        signal and the timeout, a signal and Closed -- can both fire in the
+        same poll. Every callback checks this first so the *first* recorded
+        outcome wins and the post-loop raise order is never handed a second
+        one to misreport (a delivered activation dropped for a timeout, a
+        protocol fault overwritten by session-closed).
+        """
+        return bool(result) or bool(malformed) or timed_out or session_closed
+
     def on_closed(*_args: Any) -> None:
         """End the wait: a closed session can never deliver the signal.
 
@@ -1076,7 +1335,7 @@ def _wait_for_signal(
         that merely had not fired yet.
         """
         nonlocal session_closed
-        if result:
+        if _settled():
             return
         logger.debug("session %s closed while waiting for %s", session_handle, signal)
         session_closed = True
@@ -1092,21 +1351,22 @@ def _wait_for_signal(
         *_a: Any,
     ) -> None:
         """Record the first matching signal; anything else is logged and dropped."""
-        if result:  # a subscription that outlives its own wait can fire twice
+        if _settled():  # a subscription outliving its wait fires twice
             return
         args = params.unpack()
-        if args[0] != session_handle:
-            # Logged, not silently dropped: this filter can hide a signal
-            # that *did* arrive just as effectively as the wrong-path
-            # subscription above did, and the two are indistinguishable
-            # from the outside -- both look exactly like a compositor that
-            # never fired. One debug line is what tells them apart.
-            logger.debug(
-                "ignoring %s for session %s while waiting for %s",
-                signal,
-                args[0],
-                session_handle,
-            )
+        # The verdict is computed by `_classify_signal_payload`, but ACTED
+        # on here and the error raised only after the loop, because this
+        # runs inside a GLib callback: PyGI prints an exception raised here
+        # to stderr and swallows it, so a bare raise on a malformed payload
+        # would leave the loop running -- a timeout at best, an unbounded
+        # hang with timeout=None, both indistinguishable from a compositor
+        # that never fired.
+        verdict = _classify_signal_payload(args, session_handle, signal)
+        if verdict == "drop":
+            return
+        if verdict == "malformed":
+            malformed["args"] = args
+            loop.quit()
             return
         logger.debug("received %s for session %s", signal, session_handle)
         result["args"] = args
@@ -1114,7 +1374,16 @@ def _wait_for_signal(
 
     def on_timeout() -> bool:
         """Stop the loop and record that it timed out rather than finished."""
-        nonlocal timed_out
+        nonlocal timed_out, timeout_fired
+        # Set first, before the early return: GLib removes the source the
+        # moment this returns False (which both paths do), so the finally
+        # block keys "already removed" on this, not on `timed_out`.
+        timeout_fired = True
+        if _settled():
+            # A signal delivered in the same poll as the deadline has
+            # already recorded its outcome; the timeout must not overwrite
+            # a real activation with PortalTimeoutError.
+            return False
         timed_out = True
         loop.quit()
         return False
@@ -1148,7 +1417,7 @@ def _wait_for_signal(
         session_handle,
     )
     try:
-        if not result and not session_closed:
+        if not result and not session_closed and not malformed:
             timeout_source = None
             if timeout is not None:
                 timeout_source = GLib.timeout_add(int(timeout * 1000), on_timeout)
@@ -1164,13 +1433,41 @@ def _wait_for_signal(
                 # every real timeout this session hit, never against
                 # test_portal.py's fake GLib.source_remove, which just
                 # clears pending_timeout with no complaint either way.
-                if timeout_source is not None and not timed_out:
+                # Keyed on `timeout_fired` (did on_timeout run), not
+                # `timed_out` (did the wait time out): a signal landing in
+                # the same poll as the deadline runs on_timeout down its
+                # `_settled` early return, which removes the source yet
+                # leaves `timed_out` False.
+                if timeout_source is not None and not timeout_fired:
                     GLib.source_remove(timeout_source)
     finally:
         connection.signal_unsubscribe(subscription)
         connection.signal_unsubscribe(closed_subscription)
+    return _signal_outcome(
+        signal, timeout, result, malformed, timed_out, session_closed
+    )
+
+
+def _signal_outcome(
+    signal: str,
+    timeout: float | None,
+    result: dict[str, Any],
+    malformed: dict[str, Any],
+    timed_out: bool,
+    session_closed: bool,
+) -> tuple[Any, ...]:
+    """Raise for the terminal outcome `_wait_for_signal` recorded, or return it.
+
+    Order is load-bearing and matches the callbacks' `_settled` guard:
+    whichever outcome was recorded first is the only one set, so this order
+    only ever decides between genuinely simultaneous dispatches, where a
+    session that has closed or a payload that was malformed is the more
+    useful answer than "timed out".
+    """
     if session_closed:
         raise PortalSessionClosedError(signal)
+    if malformed:
+        raise PortalProtocolError(signal, malformed["args"])
     if timed_out:
         # timed_out is only ever set inside on_timeout, itself only ever
         # registered when timeout is not None -- so this always holds, but
@@ -1408,9 +1705,26 @@ class InputCaptureSession:
         )
         if code != 0:
             raise PortalDeniedError("GetZones")
-        zone_set = results.get("zone_set", 0)
-        zones = [tuple(z) for z in results.get("zones", [])]
-        return int(zone_set), zones
+        # `results` is a dict by `_request`'s own guarantee; the *values*
+        # are still the portal's to malform. The spec types them --
+        # `zone_set` is a `u`, `zones` an `a(uuii)` -- so convert them
+        # under one guard, the same way `_activation_from_options` covers
+        # the Activated signal's values: a non-conforming value becomes
+        # the typed PortalProtocolError rather than a raw
+        # TypeError/ValueError past `except PortalError` in the caller.
+        try:
+            zone_set = _spec_int(results.get("zone_set", 0))
+            zones = [
+                (_spec_int(w), _spec_int(h), _spec_int(x), _spec_int(y))
+                for w, h, x, y in results.get("zones", [])
+            ]
+        except (ValueError, TypeError, OverflowError) as exc:
+            raise PortalProtocolError(
+                "GetZones",
+                results,
+                "a result value is not the type the spec gives it",
+            ) from exc
+        return zone_set, zones
 
     def set_pointer_barriers(
         self,
@@ -1459,7 +1773,19 @@ class InputCaptureSession:
         )
         if code != 0:
             raise PortalDeniedError("SetPointerBarriers")
-        failed = list(results.get("failed_barriers", []))
+        # `results` is a dict by `_request`'s own guarantee; the *value* at
+        # `failed_barriers` (an `au` per the spec) is not. A non-iterable
+        # there would crash the caller with a raw TypeError past
+        # `except PortalError` -- the same value-level hole `zones()` guards
+        # -- so a malformed one becomes the typed PortalProtocolError.
+        try:
+            failed = [_spec_int(b) for b in results.get("failed_barriers", [])]
+        except (ValueError, TypeError, OverflowError) as exc:
+            raise PortalProtocolError(
+                "SetPointerBarriers",
+                results,
+                "a result value is not the type the spec gives it",
+            ) from exc
         # A partially-refused set is the quiet failure here: the call
         # succeeds, some barriers stand, and an edge the caller believes is
         # armed simply never triggers. Callers see only the returned list,
@@ -1497,12 +1823,7 @@ class InputCaptureSession:
             self.session_handle,
             timeout,
         )
-        cursor = options.get("cursor_position")
-        return Activation(
-            activation_id=int(options.get("activation_id", 0)),
-            cursor_position=tuple(cursor) if cursor is not None else None,
-            barrier_id=options.get("barrier_id"),
-        )
+        return _activation_from_options(options, "Activated")
 
     def wait_for_deactivation(self, timeout: float | None = None) -> int:
         """Block until the current capture ends, returning its activation_id."""
@@ -1520,7 +1841,7 @@ class InputCaptureSession:
             self.session_handle,
             timeout,
         )
-        return int(options.get("activation_id", 0))
+        return _deactivation_id(options, "Deactivated")
 
     def close(self) -> None:
         """End the portal session, and close the EIS fd if unclaimed.

{python_libei-0.7.0.dist-info → python_libei-0.8.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-libei
-Version: 0.7.0
+Version: 0.8.1
 Summary: Inject, receive and capture input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis, plus the RemoteDesktop and InputCapture portals
 Author: Dennis K. Paulsen
 License-Expression: MIT
@@ -175,7 +175,7 @@ and why, is in
 
 ## Status
 
-Beta (`0.7.0`), published on [PyPI](https://pypi.org/project/python-libei/)
+Beta (`0.8.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
@@ -228,17 +228,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`

python_libei-0.8.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+libei/__init__.py,sha256=7fJVf_RPxcEEeOM2YTQHtJPP3ilPhFREQKNmCoJqOL4,1858
+libei/_cobject.py,sha256=XjbUNJpZ87jAyPWh6dmRslk6cMy831oMRFhWmfjLDFo,13344
+libei/ei.py,sha256=3oaZ4dxo-ytBHtES3_1_LUca2ZbR8r3SwA50Rj0hGxo,49541
+libei/eis.py,sha256=kcFi6vfw9F9uBt6Bz-blGD-0M6mLEMTYDCgC_SKK7vU,46843
+libei/oeffis.py,sha256=gJHR90s9VhQrgkjWUMDx-lxZ8qKxkttnqbx_xo-7oxs,10035
+libei/portal.py,sha256=95f3I5q8BF2ehGP6LEEMzRKTisrwBxkf20rY1MvD1ic,88168
+libei/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+libei/_capi/__init__.py,sha256=raISSWSV9hAcE92DcLCz-vUb1IPcsmxRZaS-iAoQJBE,211
+libei/_capi/libei.py,sha256=AQgVZ2ZsHH8rywwcmq1EJ-IauuNHbBMhwauMelX83yE,11754
+libei/_capi/libeis.py,sha256=C_Uh7DwNncFC8A4wuMhviAj5C_TUmKHtLJYq0Qhhz1E,13142
+libei/_capi/liboeffis.py,sha256=V8jdmJm3qOQUzzNiCAXt4Jr2JY11Y4-w6NIfIxbxGI4,1218
+libei/_capi/loader.py,sha256=xW67uk35ckgeFaheDGrHC05ZM5w_cxBGvX5lG_GUSu8,6625
+python_libei-0.8.1.dist-info/licenses/LICENSE,sha256=l6xbMU6Y-JZDzmBciBj-J5t6h6jNg_Bcyp4bHxDepqU,1074
+python_libei-0.8.1.dist-info/METADATA,sha256=gGc0OayDeot7yFnA2wmURo_xZjjr1UoQxpK7mdynrWk,23364
+python_libei-0.8.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+python_libei-0.8.1.dist-info/top_level.txt,sha256=_DQXzGjDsUBENI_cNkiOxPB4xi8coCbQS1lq18FMudQ,6
+python_libei-0.8.1.dist-info/RECORD,,

{python_libei-0.7.0.dist-info → python_libei-0.8.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (84.0.0)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

python_libei-0.7.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-libei/__init__.py,sha256=3Ru2esZsveT5oIlBPJ_6DH8RsRoofVvvf27WZafcOZg,1858
-libei/_cobject.py,sha256=XjbUNJpZ87jAyPWh6dmRslk6cMy831oMRFhWmfjLDFo,13344
-libei/ei.py,sha256=W4akKc_BNVfL0FroSXLGD1Z_L3OmYjZT5QDHNnEtMP8,49367
-libei/eis.py,sha256=X_umAaAAbAMC9d2RdnMReeJZI61WsnKz3cySY5YrGr0,45841
-libei/oeffis.py,sha256=gJHR90s9VhQrgkjWUMDx-lxZ8qKxkttnqbx_xo-7oxs,10035
-libei/portal.py,sha256=Q2GbZBUnKJZ90WJtDtpkcgQbvsCLY6xJwngmYRg5qQ0,72089
-libei/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-libei/_capi/__init__.py,sha256=raISSWSV9hAcE92DcLCz-vUb1IPcsmxRZaS-iAoQJBE,211
-libei/_capi/libei.py,sha256=qsccHa_komCxtvPYi6AobszhFbEG2qA8QYJJVr8SaGM,11356
-libei/_capi/libeis.py,sha256=C_Uh7DwNncFC8A4wuMhviAj5C_TUmKHtLJYq0Qhhz1E,13142
-libei/_capi/liboeffis.py,sha256=V8jdmJm3qOQUzzNiCAXt4Jr2JY11Y4-w6NIfIxbxGI4,1218
-libei/_capi/loader.py,sha256=xW67uk35ckgeFaheDGrHC05ZM5w_cxBGvX5lG_GUSu8,6625
-python_libei-0.7.0.dist-info/licenses/LICENSE,sha256=l6xbMU6Y-JZDzmBciBj-J5t6h6jNg_Bcyp4bHxDepqU,1074
-python_libei-0.7.0.dist-info/METADATA,sha256=kCY_c4mpI43wAk_72MFq1yyv3VZm8r9NBaexaQzgWCg,22882
-python_libei-0.7.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_libei-0.7.0.dist-info/top_level.txt,sha256=_DQXzGjDsUBENI_cNkiOxPB4xi8coCbQS1lq18FMudQ,6
-python_libei-0.7.0.dist-info/RECORD,,