python-libei 0.5.2__tar.gz → 0.6.1__tar.gz

{python_libei-0.5.2/src/python_libei.egg-info → python_libei-0.6.1}/PKG-INFO

@@ -1,18 +1,21 @@
 Metadata-Version: 2.4
 Name: python-libei
-Version: 0.5.2
-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
@@ -37,6 +40,10 @@ Dynamic: license-file
 
 # python-libei
 
+[![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)
+
 Python bindings for [libei, libeis and liboeffis](https://libinput.pages.freedesktop.org/libei/) —
 the Wayland input-emulation libraries. Use this to **move the pointer, click,
 type, or scroll on a Wayland desktop** from Python, the way `xdotool` did on
@@ -49,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.
@@ -92,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 |
 | --- | --- | --- |
@@ -101,13 +111,18 @@ 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()`, an `Error` exception, and an `EventType` /
-`DeviceCapability` enum. `ei` and `eis` also share the shapes around them:
-`Device`, `Seat`, `Region`, `Keymap`, `Touch`, `Ping`, `Event`, and the frozen
-dataclasses its accessors return. The package ships `py.typed`, so callers
-type-check against real annotations rather than `Any`.
+Each module has `is_available()`. `ei` and `eis` share the shapes around them:
+an `Error` exception, an `EventType` and `DeviceCapability` enum, and `Device`,
+`Seat`, `Region`, `Keymap`, `Touch`, `Ping`, `Event` with the frozen dataclasses
+its accessors return. `oeffis` and `portal` are smaller — `DeviceType`, no
+`EventType` or `DeviceCapability`, `Activation` as the one frozen result a
+portal wait hands back, and their own exception classes rather than an `Error`.
+[docs/troubleshooting.md](docs/troubleshooting.md) names every class they raise.
+The package ships `py.typed`, so callers type-check against real
+annotations rather than `Any`.
 
 ## What's implemented
 
@@ -135,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.
@@ -149,14 +165,16 @@ Beyond sending input, the wrapper also covers ping/pong round trips
 (`Device.keymap`), region mapping ids and coordinate conversion,
 `Context.disconnect()`, `Context.peek_event_type()`, and
 `Seat.request_device()`. On the server side, `libei.eis` mirrors all of it and
-adds `Eis.set_flag()` and `Client.pid`. Underneath, the ctypes layer binds 250
+adds `Eis.set_flag()` (with the `Flag` values it takes), `Client.pid`, and
+`Device.configure()` with the `ConfigureRegion` descriptions it accepts.
+Underneath, the ctypes layer binds 250
 of the 302 functions the three libraries export as of 1.6.0; what is left out,
 and why, is in
 [docs/developers/architecture.md](docs/developers/architecture.md#what-is-bound-and-what-is-deliberately-not).
 
 ## Status
 
-Beta (`0.5.2`), 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
@@ -197,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:
 
@@ -357,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.
@@ -367,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.
 
@@ -394,8 +422,10 @@ a list of error messages. Start there when nothing happens.
   happens" checklist
 - [docs/vs-snegg.md](docs/vs-snegg.md) — how this differs from the reference
   bindings, and two signature issues found by cross-checking the C source
-- [docs/developers/](docs/developers/) — the four-layer architecture, and what
-  has actually been verified against which libei versions
+- [docs/developers/architecture.md](docs/developers/architecture.md) and
+  [docs/developers/verification.md](docs/developers/verification.md) — the
+  four-layer architecture, and what has actually been verified against which
+  libei versions
 - [CONTRIBUTING.md](CONTRIBUTING.md) — setup, checks, testing against an old
   libei, releasing
 

python_libei-0.5.2/PKG-INFO → python_libei-0.6.1/README.md

@@ -1,42 +1,9 @@
-Metadata-Version: 2.4
-Name: python-libei
-Version: 0.5.2
-Summary: Inject and receive input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis
-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: 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
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: POSIX :: BSD :: FreeBSD
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Desktop Environment
-Classifier: Topic :: Software Development :: Libraries
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: Software Development :: Testing
-Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Provides-Extra: portal
-Requires-Dist: PyGObject>=3.42; extra == "portal"
-Provides-Extra: dev
-Requires-Dist: pytest>=7; extra == "dev"
-Requires-Dist: ruff>=0.6; extra == "dev"
-Requires-Dist: mypy>=1.11; extra == "dev"
-Dynamic: license-file
-
 # python-libei
 
+[![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)
+
 Python bindings for [libei, libeis and liboeffis](https://libinput.pages.freedesktop.org/libei/) —
 the Wayland input-emulation libraries. Use this to **move the pointer, click,
 type, or scroll on a Wayland desktop** from Python, the way `xdotool` did on
@@ -49,8 +16,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.
@@ -92,8 +62,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 |
 | --- | --- | --- |
@@ -101,13 +71,18 @@ 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()`, an `Error` exception, and an `EventType` /
-`DeviceCapability` enum. `ei` and `eis` also share the shapes around them:
-`Device`, `Seat`, `Region`, `Keymap`, `Touch`, `Ping`, `Event`, and the frozen
-dataclasses its accessors return. The package ships `py.typed`, so callers
-type-check against real annotations rather than `Any`.
+Each module has `is_available()`. `ei` and `eis` share the shapes around them:
+an `Error` exception, an `EventType` and `DeviceCapability` enum, and `Device`,
+`Seat`, `Region`, `Keymap`, `Touch`, `Ping`, `Event` with the frozen dataclasses
+its accessors return. `oeffis` and `portal` are smaller — `DeviceType`, no
+`EventType` or `DeviceCapability`, `Activation` as the one frozen result a
+portal wait hands back, and their own exception classes rather than an `Error`.
+[docs/troubleshooting.md](docs/troubleshooting.md) names every class they raise.
+The package ships `py.typed`, so callers type-check against real
+annotations rather than `Any`.
 
 ## What's implemented
 
@@ -135,8 +110,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.
@@ -149,14 +125,16 @@ Beyond sending input, the wrapper also covers ping/pong round trips
 (`Device.keymap`), region mapping ids and coordinate conversion,
 `Context.disconnect()`, `Context.peek_event_type()`, and
 `Seat.request_device()`. On the server side, `libei.eis` mirrors all of it and
-adds `Eis.set_flag()` and `Client.pid`. Underneath, the ctypes layer binds 250
+adds `Eis.set_flag()` (with the `Flag` values it takes), `Client.pid`, and
+`Device.configure()` with the `ConfigureRegion` descriptions it accepts.
+Underneath, the ctypes layer binds 250
 of the 302 functions the three libraries export as of 1.6.0; what is left out,
 and why, is in
 [docs/developers/architecture.md](docs/developers/architecture.md#what-is-bound-and-what-is-deliberately-not).
 
 ## Status
 
-Beta (`0.5.2`), 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
@@ -197,9 +175,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:
 
@@ -357,8 +339,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.
@@ -367,20 +353,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.
 
@@ -394,8 +382,10 @@ a list of error messages. Start there when nothing happens.
   happens" checklist
 - [docs/vs-snegg.md](docs/vs-snegg.md) — how this differs from the reference
   bindings, and two signature issues found by cross-checking the C source
-- [docs/developers/](docs/developers/) — the four-layer architecture, and what
-  has actually been verified against which libei versions
+- [docs/developers/architecture.md](docs/developers/architecture.md) and
+  [docs/developers/verification.md](docs/developers/verification.md) — the
+  four-layer architecture, and what has actually been verified against which
+  libei versions
 - [CONTRIBUTING.md](CONTRIBUTING.md) — setup, checks, testing against an old
   libei, releasing
 

{python_libei-0.5.2 → python_libei-0.6.1}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-libei"
-version = "0.5.2"
-description = "Inject and receive input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis"
+version = "0.6.1"
+description = "Inject, receive and capture input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis, plus the RemoteDesktop and InputCapture portals"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
@@ -18,6 +18,8 @@ keywords = [
     "input",
     "input-emulation",
     "emulated-input",
+    "input-capture",
+    "eis",
     "portal",
     "xdg-desktop-portal",
     "remote-desktop",
@@ -31,6 +33,7 @@ classifiers = [
     "Intended Audience :: Developers",
     "Operating System :: POSIX :: BSD :: FreeBSD",
     "Operating System :: POSIX :: Linux",
+    "Operating System :: POSIX",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
     "Programming Language :: Python :: 3.10",
@@ -62,6 +65,8 @@ dev = ["pytest>=7", "ruff>=0.6", "mypy>=1.11"]
 homepage = "https://github.com/ctrondlp/python-libei"
 repository = "https://github.com/ctrondlp/python-libei"
 issues = "https://github.com/ctrondlp/python-libei/issues"
+documentation = "https://github.com/ctrondlp/python-libei/tree/main/docs"
+pyguitest = "https://github.com/ctrondlp/pyguitest"
 changelog = "https://github.com/ctrondlp/python-libei/blob/main/CHANGELOG.md"
 
 [tool.setuptools.packages.find]
@@ -73,6 +78,14 @@ libei = ["py.typed"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+# The suite imports `libei` from the checkout rather than requiring an
+# install, so `scripts/pre-commit-test.sh` runs on an interpreter with only
+# the dev tools in it -- which is what that script's own header asks for, and
+# what pyguitest and pyguitest-recorder already do. CI installs the package,
+# so the installed path is still covered there. Without this, conftest's
+# `from libei import ei` fails at collection and the whole check reports an
+# ImportError instead of running anything.
+pythonpath = ["src"]
 markers = [
     "integration: requires the real libei/libeis/liboeffis shared libraries to be installed",
 ]

{python_libei-0.5.2 → python_libei-0.6.1}/src/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.5.2"
+__version__ = "0.6.1"
 
 __all__ = ["__version__"]

{python_libei-0.5.2 → python_libei-0.6.1}/src/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.

{python_libei-0.5.2 → python_libei-0.6.1}/src/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+

{python_libei-0.5.2 → python_libei-0.6.1}/src/libei/_capi/loader.py

@@ -25,12 +25,19 @@ class LazyLibrary:
     """A ctypes.CDLL that only opens the library on first real use."""
 
     def __init__(self, soname: str) -> None:
+        """Remember the soname; nothing is opened until first use."""
         self._soname = soname
         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.
+
+        Raises LibraryNotFoundError on every later call too after a failure:
+        the failed load is cached rather than retried.
+        """
         # Double-checked: the unlocked read is the fast path taken by every
         # call after the first, and the repeated check inside the lock is
         # what makes it safe -- two threads can both fall through the first
@@ -69,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,
@@ -88,9 +110,11 @@ 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:
+            """Resolve the C function on first call, then pass straight through."""
             # Resolution happens here, on first call, not at bind time --
             # that is the whole point of this module (see its docstring).
             bound = cache.get("f")
@@ -106,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

{python_libei-0.5.2 → python_libei-0.6.1}/src/libei/_cobject.py

@@ -66,6 +66,7 @@ class CObject:
     _instances_lock: ClassVar[threading.RLock]
 
     def __init_subclass__(cls, **kwargs: Any) -> None:
+        """Give each wrapper hierarchy one identity cache, shared by subclasses."""
         super().__init_subclass__(**kwargs)
         # One cache per wrapper *hierarchy*, not per class. Only a root
         # wrapper class -- one whose only CObject ancestor is CObject
@@ -98,6 +99,7 @@ class CObject:
             cls._instances_lock = threading.RLock()
 
     def __init__(self, pointer: int, *, _adopt: bool = False) -> None:
+        """Take a reference on a non-NULL pointer and cache this wrapper for it."""
         if not pointer:
             raise ValueError(f"{type(self).__name__} cannot wrap a NULL pointer")
         self._pointer = pointer
@@ -121,6 +123,7 @@ class CObject:
 
     @property
     def _as_parameter_(self) -> int:
+        """The raw pointer ctypes passes to C -- an error once it is released."""
         if self._pointer == 0:
             raise RuntimeError(
                 f"{type(self).__name__} has already been released; "
@@ -159,6 +162,7 @@ class CObject:
 
     @classmethod
     def _get_or_create(cls: type[T], pointer: int | None, *, adopt: bool) -> T | None:
+        """The wrapper already caching this pointer, or a new one; None for NULL."""
         if not pointer:
             return None
         if not cls._wrappable:
@@ -232,6 +236,7 @@ class CObject:
         return cls._get_or_create(pointer, adopt=True)
 
     def __eq__(self, other: object) -> bool:
+        """Equal when the types match and the wrapped pointers are the same."""
         if not isinstance(other, CObject):
             return NotImplemented
         if type(self) is not type(other):
@@ -245,6 +250,7 @@ class CObject:
         return self._pointer == other._pointer
 
     def __hash__(self) -> int:
+        """Stable for the object's life: the original pointer, not the live one."""
         # Deliberately keyed on _hash_key, not _pointer: release() zeroes
         # _pointer, and an object whose hash changes mid-life vanishes
         # from any set or dict it was placed in. Two wrappers can share a