python-libei 0.6.1__py3-none-any.whl → 0.8.0__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.6.1"
+__version__ = "0.8.0"
 
 __all__ = ["__version__"]

libei/portal.py

@@ -90,6 +90,8 @@ __all__ = [
     "PortalVersionError",
     "PortalDeniedError",
     "PortalTimeoutError",
+    "PortalSessionClosedError",
+    "PortalProtocolError",
     "RemoteDesktopSession",
     "Activation",
     "InputCaptureSession",
@@ -185,6 +187,67 @@ 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.
+    """
+
+    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.
+
+    The ``org.freedesktop.portal.Session`` interface emits ``Closed`` when
+    the compositor or the portal ends a session from its side -- a
+    compositor restart, the portal process dying, a session revoked from a
+    settings panel. Distinct from :class:`PortalTimeoutError` (the session
+    is fine, the signal just has not come) and from
+    :class:`PortalDeniedError` (a request was answered, negatively): here
+    there is no session left to answer anything, so the wait that raised
+    this can never be satisfied by waiting longer.
+    """
+
+    def __init__(self, step: str) -> None:
+        """Name what was being waited for when the session went away."""
+        super().__init__(
+            f"the portal session was closed while waiting for {step}; "
+            "the compositor or portal ended it from its side"
+        )
+        self.step = step
+
+
 def _gio() -> tuple[Any, Any] | None:
     """Import Gio and GLib, or return None.
 
@@ -999,6 +1062,98 @@ 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 _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``
+    (the last from ``int(float('inf'))``) 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 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 = 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 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,
@@ -1034,10 +1189,60 @@ 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.
+
+        ``Closed`` is emitted on the **session object's own path** (unlike
+        ``Activated``/``Deactivated``, which fire on the portal object --
+        see above), so the subscription below uses ``session_handle`` as
+        the path and needs no payload filtering: any ``Closed`` there is
+        this session's. Without this subscription, a wait with
+        ``timeout=None`` on a session the compositor has ended -- a
+        compositor restart, the portal dying, capture revoked from a
+        settings panel -- blocked forever, indistinguishable from a signal
+        that merely had not fired yet.
+        """
+        nonlocal session_closed
+        if _settled():
+            return
+        logger.debug("session %s closed while waiting for %s", session_handle, signal)
+        session_closed = True
+        loop.quit()
 
     def on_signal(
         _conn: Any,
@@ -1049,21 +1254,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
@@ -1071,7 +1277,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
@@ -1086,6 +1301,16 @@ def _wait_for_signal(
         on_signal,
         None,
     )
+    closed_subscription = connection.signal_subscribe(
+        busname,
+        _SESSION_INTERFACE,
+        "Closed",
+        session_handle,
+        None,
+        Gio.DBusSignalFlags.NONE,
+        on_closed,
+        None,
+    )
     logger.debug(
         "waiting up to %s for %s.%s on %s for session %s",
         "forever" if timeout is None else f"{timeout:g}s",
@@ -1095,7 +1320,7 @@ def _wait_for_signal(
         session_handle,
     )
     try:
-        if not result:
+        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)
@@ -1111,10 +1336,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
@@ -1441,12 +1697,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."""
@@ -1464,7 +1715,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.6.1.dist-info → python_libei-0.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-libei
-Version: 0.6.1
+Version: 0.8.0
 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
@@ -40,6 +40,7 @@ Dynamic: license-file
 
 # python-libei
 
+[![Contributing](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)](https://github.com/ctrondlp/python-libei/blob/main/CONTRIBUTING.md)
 [![CI](https://github.com/ctrondlp/python-libei/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ctrondlp/python-libei/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/python-libei)](https://pypi.org/project/python-libei/)
 [![License](https://img.shields.io/pypi/l/python-libei)](https://github.com/ctrondlp/python-libei/blob/main/LICENSE)
@@ -174,7 +175,7 @@ and why, is in
 
 ## Status
 
-Beta (`0.6.1`), published on [PyPI](https://pypi.org/project/python-libei/)
+Beta (`0.8.0`), 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

{python_libei-0.6.1.dist-info → python_libei-0.8.0.dist-info}/RECORD

@@ -1,17 +1,17 @@
-libei/__init__.py,sha256=OP-aoBP8bXNhL8q3gXxVL4FtWLhVyaBlmoQEInBdhp4,1858
+libei/__init__.py,sha256=8k-acXmeIea963zVksZW5Ymby8ZYL_aO6B4o7g4_Y9w,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=XC_FsKueIpcmAPZ4TDXJgFhucJNeMEO2byTJHG3GMmI,69756
+libei/portal.py,sha256=FdtVdUUKrq2GOcDBtunLCISw7RYO4Mwyk3ci26OH330,81621
 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.6.1.dist-info/licenses/LICENSE,sha256=l6xbMU6Y-JZDzmBciBj-J5t6h6jNg_Bcyp4bHxDepqU,1074
-python_libei-0.6.1.dist-info/METADATA,sha256=nV9GTh7ArlrDPXyPTt4fGHJiPP22J9bmA2e8v-mDgp0,22728
-python_libei-0.6.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_libei-0.6.1.dist-info/top_level.txt,sha256=_DQXzGjDsUBENI_cNkiOxPB4xi8coCbQS1lq18FMudQ,6
-python_libei-0.6.1.dist-info/RECORD,,
+python_libei-0.8.0.dist-info/licenses/LICENSE,sha256=l6xbMU6Y-JZDzmBciBj-J5t6h6jNg_Bcyp4bHxDepqU,1074
+python_libei-0.8.0.dist-info/METADATA,sha256=SNey10DqR4IKZ_T_XCKmafkR0ioMfxHbdbaSl9IWG-c,22882
+python_libei-0.8.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+python_libei-0.8.0.dist-info/top_level.txt,sha256=_DQXzGjDsUBENI_cNkiOxPB4xi8coCbQS1lq18FMudQ,6
+python_libei-0.8.0.dist-info/RECORD,,

{python_libei-0.6.1.dist-info → python_libei-0.8.0.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