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

libei/_capi/libei.py

@@ -128,7 +128,7 @@ event_scroll_get_discrete_dy = lib.function(
 event_touch_get_id = lib.function("ei_event_touch_get_id", (c_void_p,), c_uint32)
 event_touch_get_x = lib.function("ei_event_touch_get_x", (c_void_p,), c_double)
 event_touch_get_y = lib.function("ei_event_touch_get_y", (c_void_p,), c_double)
-event_touch_get_is_cancel = lib.function(
+event_touch_get_is_cancel = lib.function(  # libei 1.4+
     "ei_event_touch_get_is_cancel", (c_void_p,), c_bool
 )
 event_text_get_utf8 = lib.function(  # libei 1.6+
@@ -141,7 +141,9 @@ event_text_get_keysym_is_press = lib.function(  # libei 1.6+
     "ei_event_text_get_keysym_is_press", (c_void_p,), c_bool
 )
 # Borrowed reference -- the event still owns it, so wrap() rather than adopt().
-event_pong_get_ping = lib.function("ei_event_pong_get_ping", (c_void_p,), c_void_p)
+event_pong_get_ping = lib.function(  # libei 1.4+
+    "ei_event_pong_get_ping", (c_void_p,), c_void_p
+)
 
 device_ref = lib.function("ei_device_ref", (c_void_p,), c_void_p)
 device_unref = lib.function("ei_device_unref", (c_void_p,), c_void_p)
@@ -236,7 +238,7 @@ touch_get_device = lib.function("ei_touch_get_device", (c_void_p,), c_void_p)
 touch_down = lib.function("ei_touch_down", (c_void_p, c_double, c_double), None)
 touch_motion = lib.function("ei_touch_motion", (c_void_p, c_double, c_double), None)
 touch_up = lib.function("ei_touch_up", (c_void_p,), None)
-touch_cancel = lib.function("ei_touch_cancel", (c_void_p,), None)
+touch_cancel = lib.function("ei_touch_cancel", (c_void_p,), None)  # libei 1.4+
 
 # ei_new_ping() returns an owned reference; ei_ping() then triggers the round
 # trip that comes back as an EI_EVENT_PONG.

libei/_capi/libeis.py

@@ -104,7 +104,7 @@ event_scroll_get_discrete_dy = lib.function(
 event_touch_get_id = lib.function("eis_event_touch_get_id", (c_void_p,), c_uint32)
 event_touch_get_x = lib.function("eis_event_touch_get_x", (c_void_p,), c_double)
 event_touch_get_y = lib.function("eis_event_touch_get_y", (c_void_p,), c_double)
-event_touch_get_is_cancel = lib.function(
+event_touch_get_is_cancel = lib.function(  # libei 1.4+
     "eis_event_touch_get_is_cancel", (c_void_p,), c_bool
 )
 event_text_get_utf8 = lib.function(  # libei 1.6+
@@ -117,14 +117,16 @@ event_text_get_keysym_is_press = lib.function(  # libei 1.6+
     "eis_event_text_get_keysym_is_press", (c_void_p,), c_bool
 )
 # Borrowed reference -- the event still owns it, so wrap() rather than adopt().
-event_pong_get_ping = lib.function("eis_event_pong_get_ping", (c_void_p,), c_void_p)
+event_pong_get_ping = lib.function(  # libei 1.4+
+    "eis_event_pong_get_ping", (c_void_p,), c_void_p
+)
 
 client_ref = lib.function("eis_client_ref", (c_void_p,), c_void_p)
 client_unref = lib.function("eis_client_unref", (c_void_p,), c_void_p)
 client_is_sender = lib.function("eis_client_is_sender", (c_void_p,), c_bool)
 # pid_t, i.e. a 32-bit signed int on Linux. Socket backend only, and
 # negative errno on failure.
-backend_socket_get_client_pid = lib.function(
+backend_socket_get_client_pid = lib.function(  # libei 1.5+
     "eis_backend_socket_get_client_pid", (c_void_p,), c_int32
 )
 client_get_name = lib.function("eis_client_get_name", (c_void_p,), c_char_p)
@@ -277,7 +279,7 @@ touch_get_device = lib.function("eis_touch_get_device", (c_void_p,), c_void_p)
 touch_down = lib.function("eis_touch_down", (c_void_p, c_double, c_double), None)
 touch_motion = lib.function("eis_touch_motion", (c_void_p, c_double, c_double), None)
 touch_up = lib.function("eis_touch_up", (c_void_p,), None)
-touch_cancel = lib.function("eis_touch_cancel", (c_void_p,), None)
+touch_cancel = lib.function("eis_touch_cancel", (c_void_p,), None)  # libei 1.4+
 
 ping = lib.function("eis_ping", (c_void_p,), None)  # libei 1.4+
 ping_get_id = lib.function("eis_ping_get_id", (c_void_p,), c_uint64)  # libei 1.4+

libei/_capi/loader.py

@@ -30,6 +30,7 @@ class LazyLibrary:
         self._lib: ctypes.CDLL | None = None
         self._load_error: OSError | None = None
         self._lock = threading.Lock()
+        self._declared: dict[str, tuple[tuple[type, ...], type | None]] = {}
 
     def _ensure_loaded(self) -> ctypes.CDLL:
         """Return the opened library, opening it on first call.
@@ -75,6 +76,21 @@ class LazyLibrary:
             return False
         return True
 
+    @property
+    def soname(self) -> str:
+        """The shared library this binds, as it is passed to ``dlopen``."""
+        return self._soname
+
+    @property
+    def declared(self) -> dict[str, tuple[tuple[type, ...], type | None]]:
+        """Every function bound so far: C name -> (argtypes, restype).
+
+        Read by the ABI tests, which compare it with the library's exports and
+        with the upstream headers. Declaring a binding records it here and does
+        nothing else -- the library is still not opened until a call.
+        """
+        return dict(self._declared)
+
     def function(
         self,
         name: str,
@@ -94,6 +110,7 @@ class LazyLibrary:
         # the dict is chosen only because "absent from the dict" already
         # means "not resolved yet", with no None sentinel to confuse with a
         # legitimately-None value.
+        self._declared[name] = (tuple(argtypes), restype)
         cache: dict[str, Any] = {}
 
         def call(*args: Any) -> Any:
@@ -113,7 +130,23 @@ class LazyLibrary:
                 bound.argtypes = list(argtypes)
                 bound.restype = restype
                 cache["f"] = bound
-            return bound(*args)
+            try:
+                return bound(*args)
+            except ctypes.ArgumentError:
+                # ctypes turns *any* exception raised while converting an
+                # argument into an ArgumentError carrying only its text -- no
+                # __cause__, no __context__. For a released object that loses
+                # the RuntimeError its ``_as_parameter_`` raised, so a caller
+                # catching RuntimeError (as documented) would miss it. Ask the
+                # arguments again and re-raise the real one.
+                for arg in args:
+                    try:
+                        arg._as_parameter_  # noqa: B018 - evaluated for its error
+                    except RuntimeError as released:
+                        raise released from None
+                    except AttributeError:
+                        continue
+                raise
 
         call.__name__ = name
         return call

libei/portal.py

@@ -1176,12 +1176,13 @@ class InputCaptureSession:
     about, and this cannot release on a caller's behalf during cleanup
     without risking racing a capture that only just started.
 
-    **Never live-tested.** Every other class in this module that talks to a
-    real portal carries a hand-verification note in its own docstring; this
-    one does not, because verifying it means a developer clicking through
-    the consent dialog *and* accepting that their pointer will be diverted
-    away from their own desktop for the length of the test -- not something
-    to trigger without asking first, unlike everything else here. Designed
+    **Only half live-tested.** The negotiation -- consent dialog, EIS fd,
+    zones, ``Session.Close()`` -- was run against a real GNOME session on
+    libei's own hand-verification terms (see
+    ``docs/developers/verification.md``); the *capture* half never has been,
+    because verifying it means a developer accepting that their pointer will
+    be diverted away from their own desktop for the length of the test -- not
+    something to trigger without asking first, unlike everything else here. Designed
     against ``/usr/share/dbus-1/interfaces/org.freedesktop.portal.
     InputCapture.xml`` (the shipped portal spec, not the header alone) and
     unit-tested against a fake connection reproducing that spec's documented

{python_libei-0.6.0.dist-info → python_libei-0.6.1.dist-info}/METADATA

@@ -1,18 +1,21 @@
 Metadata-Version: 2.4
 Name: python-libei
-Version: 0.6.0
-Summary: Inject and receive input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis
+Version: 0.6.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
 Project-URL: homepage, https://github.com/ctrondlp/python-libei
 Project-URL: repository, https://github.com/ctrondlp/python-libei
 Project-URL: issues, https://github.com/ctrondlp/python-libei/issues
+Project-URL: documentation, https://github.com/ctrondlp/python-libei/tree/main/docs
+Project-URL: pyguitest, https://github.com/ctrondlp/pyguitest
 Project-URL: changelog, https://github.com/ctrondlp/python-libei/blob/main/CHANGELOG.md
-Keywords: wayland,libei,libeis,liboeffis,input,input-emulation,emulated-input,portal,xdg-desktop-portal,remote-desktop,automation,gui-testing,accessibility,ctypes
+Keywords: wayland,libei,libeis,liboeffis,input,input-emulation,emulated-input,input-capture,eis,portal,xdg-desktop-portal,remote-desktop,automation,gui-testing,accessibility,ctypes
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: POSIX :: BSD :: FreeBSD
 Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: POSIX
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.10
@@ -53,8 +56,11 @@ device.start_emulating().pointer_motion(5, 0).frame().stop_emulating()
 ```
 
 **The one concept:** events queue up, and **`frame()` is what sends them** as
-one logical hardware event. Forget it and nothing happens — no exception, no
-warning, no movement. Fill the package, then post it.
+one logical hardware event. Forget it and the motion is usually lost — no
+exception, no warning, no movement. (Ending the chain with `stop_emulating()`
+makes libei frame the queue for you, but it logs an error-level `Bug:` line
+when it does; see [Things that will bite you](#things-that-will-bite-you).) Fill
+the package, then post it.
 
 New here? [docs/getting-started.md](docs/getting-started.md) is install
 through a first real pointer motion, in five minutes.
@@ -96,8 +102,8 @@ than a widget-tree back door:
 
 ## Which API do I need?
 
-Five modules, and most callers need exactly two of them: `oeffis` or `portal`
-to get permission, then `ei` to inject.
+Four modules (`ei`, `eis`, `oeffis`, `portal`), and most callers need exactly
+two of them: `oeffis` or `portal` to get permission, then `ei` to inject.
 
 | You want to… | Use | Notes |
 | --- | --- | --- |
@@ -105,6 +111,7 @@ to get permission, then `ei` to inject.
 | **Consume input** from a compositor | `libei.ei` → `Receiver` | Compositor-side or input-capture code; same connection dance |
 | **Get permission**, simply | `libei.oeffis` | One call, pollable fd, no dependencies. The consent dialog appears on **every** run |
 | **Get permission**, and not be asked again | `libei.portal` | Same handshake over D-Bus directly, with `persist_mode` / `restore_token`. Needs PyGObject |
+| **Capture the user's real input** | `libei.portal` → `InputCaptureSession` | The read direction, through the InputCapture portal: once the compositor decides to, the user's pointer and keyboard are diverted to you over EIS. Exclusive while active, so hold it briefly. Only its negotiation half has been run against a real desktop — see [verification](docs/developers/verification.md) |
 | **Be the server**, for tests or a compositor | `libei.eis` | Drives your client code with no real compositor and no consent dialog |
 
 Each module has `is_available()`. `ei` and `eis` share the shapes around them:
@@ -143,8 +150,9 @@ because a skimming reader could otherwise take them as supported. 1.6.0's own
 `enum ei_device_capability` stops at `TEXT`, and its `enum ei_event_type`
 stops at `EI_EVENT_TEXT_UTF8` — so the swipe/pinch/hold/stylus members of
 `EventType` cannot arrive either. The values here match upstream `main`
-exactly, so they are ready for whatever release adds them. The 22
-gesture/stylus accessor functions `main` adds are deliberately not bound:
+exactly, so they are ready for whatever release adds them. The gesture
+and stylus functions `main` adds -- 46 in libei and 51 in libeis against
+1.6.0's headers, counted 2026-09-30 -- are deliberately not bound:
 nothing that ships today exports them, so nothing here could be verified
 against a real library, which is the bar every other binding in this package
 was held to.
@@ -166,7 +174,7 @@ and why, is in
 
 ## Status
 
-Beta (`0.6.0`), published on [PyPI](https://pypi.org/project/python-libei/)
+Beta (`0.6.1`), published on [PyPI](https://pypi.org/project/python-libei/)
 since `0.1.0`, and **the API is not frozen** — expect renames before 1.0.
 
 The injection path is exercised end to end against the real libraries by the
@@ -207,9 +215,13 @@ Exactly what was run, when, and against which versions:
 - libei 1.0.0 or newer for the core: connecting, binding a seat, and
   sending pointer, button, keyboard, scroll and touch input all use symbols
   that have existed with a stable signature since 1.0.0, and upstream keeps
-  API/ABI back-compatible within the 1.x series. Only 1.5.0 and 1.6.0 have
-  actually been run against -- 1.6.0 on both Fedora 44 and FreeBSD 15, where
-  the injection path passes the full suite with nothing skipped.
+  API/ABI back-compatible within the 1.x series. The suite has been run
+  against 1.2.1 (Ubuntu 24.04, in CI) and 1.6.0 -- the latter on Fedora 44 and
+  45 and FreeBSD 15, where the injection path passes the full suite with
+  nothing skipped. Every binding's name, argument types and return type, and
+  every enum value, is also checked against the upstream headers of 1.0.0,
+  1.2.1, 1.4.0, 1.5.0 and 1.6.0 (`tests/test_abi.py`), which is the only
+  coverage 1.0.0, 1.4.0 and 1.5.0 have had.
 
   Newer libei buys you more, per feature:
 
@@ -367,8 +379,12 @@ All four, with working code:
   soon as the loop moves on, and using it afterwards raises `RuntimeError`.
   Objects you pull *off* an event (`event.device`, `event.seat`) are safe to
   keep — copy out `event.pointer_event` and friends rather than the event.
-- **`frame()` or nothing happens.** Events queue up until a `frame()` commits
-  them.
+- **`frame()` or the input is lost.** Events queue up until a `frame()` commits
+  them, and queued events that are never framed are dropped without an
+  exception or a log line. The one exception is a chain that ends in
+  `stop_emulating()`: libei frames what is queued, delivers it, and logs
+  `Bug: ei_device_stop_emulating: missing call to ei_device_frame()` at error
+  level. Measured against libei 1.2.1 and 1.6.0; don't rely on it.
 - **`bind()` needs at least one capability.** Binding an empty set sends
   nothing, so the device you are waiting for never arrives; this raises
   `ValueError` rather than hanging.
@@ -377,20 +393,22 @@ All four, with working code:
 - **One seat can resume several devices.** Bind both `POINTER` and
   `POINTER_ABSOLUTE` and GNOME gives you two, relative first. Taking
   whichever resumes first is a coin flip — select on `device.capabilities`
-  instead. Sending an event the device lacks the capability for is silently
-  ignored, which makes this look like the injection simply not working.
+  instead. Sending an event the device lacks the capability for is dropped with
+  no exception — libei only logs an error-level `Bug: ... device is not a
+  keyboard` line — which makes this look like the injection simply not working.
 - **Read the accessor that matches the event type.** `event.key_event` on a
   `POINTER_MOTION` event raises `TypeError` naming both types. libei itself
   would have returned `KeyEvent(key=0, is_press=False)` — a real-looking
-  value — while logging a `Bug:` line the caller never sees, so branch on
-  `event_type` first. `TOUCH_UP` has its own `touch_up_event`, since it
+  value — and raised nothing, only logging a `Bug:` line at error level, so
+  branch on `event_type` first. `TOUCH_UP` has its own `touch_up_event`, since it
   carries no coordinates.
 - **`GESTURES` and `STYLUS` are not in any released libei.** They match
   upstream `main` and are here ready for it, but 1.6.0's capability enum
   stops at `TEXT`. Binding them against a shipping library silently does
   nothing — no error, no device, no events.
 
-Nearly all of these fail *silently*, which is why
+Nearly all of these fail without raising — some only log an error-level `Bug:`
+line, some not even that — which is why
 [docs/troubleshooting.md](docs/troubleshooting.md) is a checklist rather than
 a list of error messages. Start there when nothing happens.
 

python_libei-0.6.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+libei/__init__.py,sha256=OP-aoBP8bXNhL8q3gXxVL4FtWLhVyaBlmoQEInBdhp4,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/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.6.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-libei/__init__.py,sha256=ypdFYwFMulRHAB3iYKc2NfCvMRvAq9TUFuwQN9b3PWw,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=eTYzNkA_65VaUlbSkATiXmOA8c6_uUDle2c2lUgZZHY,69698
-libei/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-libei/_capi/__init__.py,sha256=raISSWSV9hAcE92DcLCz-vUb1IPcsmxRZaS-iAoQJBE,211
-libei/_capi/libei.py,sha256=gpp42bhqPonhVD2zmFWCl4rdk_lm4XvD_7W2Rw5RsuI,11308
-libei/_capi/libeis.py,sha256=jQR0Z0YN9qa71mAcSJ__-UaoF8PsVsBs8OXwjfqstFk,13080
-libei/_capi/liboeffis.py,sha256=V8jdmJm3qOQUzzNiCAXt4Jr2JY11Y4-w6NIfIxbxGI4,1218
-libei/_capi/loader.py,sha256=QD1xQJo05q4eSWhOCRpAWOlzHD5fcnHtI6yQyy4rKs0,5052
-python_libei-0.6.0.dist-info/licenses/LICENSE,sha256=l6xbMU6Y-JZDzmBciBj-J5t6h6jNg_Bcyp4bHxDepqU,1074
-python_libei-0.6.0.dist-info/METADATA,sha256=NC7ygbrH78TjzREhLvF7-FSz8kNgf8tPE21NZQiykp4,20963
-python_libei-0.6.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_libei-0.6.0.dist-info/top_level.txt,sha256=_DQXzGjDsUBENI_cNkiOxPB4xi8coCbQS1lq18FMudQ,6
-python_libei-0.6.0.dist-info/RECORD,,