python-libei 0.1.0__tar.gz → 0.3.0__tar.gz

{python_libei-0.1.0/src/python_libei.egg-info → python_libei-0.3.0}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: python-libei
-Version: 0.1.0
+Version: 0.3.0
 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 :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -25,6 +26,8 @@ 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"
@@ -133,8 +136,9 @@ pointer.
 
 ## Status
 
-Alpha (`0.1.0`), not yet on PyPI, and the API is not frozen — expect
-renames before 1.0. What that qualifier covers, concretely:
+Alpha (`0.3.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. What
+that qualifier covers, concretely:
 
 - The injection path — connect, bind, wait for a device, send events — is
   exercised end-to-end against the real libraries by
@@ -143,9 +147,20 @@ renames before 1.0. What that qualifier covers, concretely:
 - Text input, touch cancellation, ping/pong, keymap transfer, region mapping
   ids and `peek_event_type()` are each round-tripped through a real libeis
   server in `tests/test_integration_extras.py`.
-- The portal path (`libei.oeffis`) has only ever been verified by hand, since
-  it needs an interactive consent dialog that nothing here can drive. See
-  [Troubleshooting](#troubleshooting).
+- Both portal paths (`libei.oeffis` and `libei.portal`) can only ever be
+  verified by hand, since they need an interactive consent dialog that
+  nothing here can drive automatically — `tests/test_portal.py` covers
+  `libei.portal`'s orchestration (raceless subscribe-before-call, the
+  `session_handle_token` crash workaround, persist_mode/restore_token)
+  against a fake D-Bus connection only. `libei.oeffis` was verified by hand
+  on 2026-08-25 (see [Troubleshooting](#troubleshooting)), and
+  `libei.portal` on 2026-09-01 against a real GNOME Wayland session
+  (`RemoteDesktop` v2): a first run raised the consent dialog and was
+  approved (5.4s), a second replaying the `restore_token` was granted with
+  no dialog at all (0.2s), three devices resumed on the returned fd
+  (relative pointer, keyboard, absolute pointer — in that order, the device
+  race `ei`-side callers must handle), and `Session.Close()` was exercised.
+  No input was injected — emulation is `libei.ei`'s job.
 - Verified against libei 1.6.0 on Fedora 44 / GNOME 50.4, and against a
   locally built 1.2.1 (130 passed, 4 skipped — the 1.4 and 1.6 features
   gate themselves out). CI repeats the 1.2.1 run on Python 3.10-3.13, so
@@ -157,7 +172,7 @@ renames before 1.0. What that qualifier covers, concretely:
 | Instead of this | Why you might |
 | --- | --- |
 | [snegg](https://gitlab.freedesktop.org/whot/snegg) | The reference bindings, by libei's own author — closer to upstream, and first to get new API. Self-described as for "rapid prototyping" with an explicitly unstable API, and `import snegg.ei` fails outright where libei isn't installed. [`docs/vs-snegg.md`](docs/vs-snegg.md) covers the differences in detail. |
-| The portal's D-Bus API directly (`org.freedesktop.portal.RemoteDesktop`, via Gio or dbus-python) | No native library and no bindings at all — `NotifyPointerMotion`, `NotifyKeyboardKeycode` and friends are plain method calls. The catch is absolute motion: `NotifyPointerMotionAbsolute` needs a PipeWire stream id, which only exists after a second, separate ScreenCast consent dialog. libei has no such requirement. |
+| The RemoteDesktop portal's own D-Bus API directly (`NotifyPointerMotion`, `NotifyKeyboardKeycode`, …), bypassing libei/EI entirely | `libei.portal` already gets you the D-Bus session and its `persist_mode`/`restore_token` handling — reach past libei entirely only if you don't want the EI protocol at all. The catch if you do: `NotifyPointerMotionAbsolute` needs a PipeWire stream id, which only exists after a second, separate ScreenCast consent dialog. libei has no such requirement. |
 | `ydotool` and other `/dev/uinput` tools | Kernel-level, so they work under any compositor and need no portal session — at the cost of a privileged daemon, and of sidestepping the consent model that EI exists to enforce. |
 
 ## Requirements
@@ -165,6 +180,10 @@ renames before 1.0. What that qualifier covers, concretely:
 - Linux with a Wayland compositor (GNOME, KDE, Sway, …)
 - CPython 3.10 or newer (tested on 3.13)
 - The native libraries: on Fedora, `sudo dnf install libei libeis liboeffis`
+- `libei.portal` only: PyGObject (`pip install 'python-libei[portal]'`), plus
+  whatever GObject-introspection libraries your distro needs for `Gio` --
+  PyPI's PyGObject wheel supplies the Python side only. Not needed for
+  `libei.ei`, `libei.eis` or `libei.oeffis`.
 - 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
@@ -194,17 +213,29 @@ renames before 1.0. What that qualifier covers, concretely:
 
 ## Install
 
-Not published to PyPI yet — install from a checkout:
+From [PyPI](https://pypi.org/project/python-libei/):
 
 ```sh
-git clone https://github.com/ctrondlp/python-libei.git
-cd python-libei
-pip install .
+pip install python-libei
 ```
 
 The distribution is named `python-libei`, the import is `libei` -- so
 `pip show python-libei`, but `from libei import ei`.
 
+Pure Python, no build step: the wheel is `py3-none-any` and ctypes talks to
+the native libraries directly, so there is no compiler, no headers and no
+`libei-devel` involved at install time. What `pip` does *not* bring is the
+native libraries themselves -- see [Requirements](#requirements) above; on
+Fedora, `sudo dnf install libei libeis liboeffis`.
+
+To track `main` instead, or to hack on it, install from a checkout:
+
+```sh
+git clone https://github.com/ctrondlp/python-libei.git
+cd python-libei
+pip install .          # or `pip install -e '.[dev]'` to develop
+```
+
 Importing is always safe, even where the native libraries are missing — they
 are loaded on first use, not at import. Check before you rely on them:
 
@@ -288,23 +319,59 @@ several devices — see the absolute-positioning notes under
 call and exposes no options dict, so the two things that make an approval
 persist — `persist_mode` on `SelectDevices`, and the `restore_token` that
 comes back on `Start` — are unreachable through it. This is a limitation of
-the C library, not of these bindings; there is nothing here left to bind.
+the C library, not of these bindings; upstream's own docs say as much:
+liboeffis is "intentionally kept simple, any more complex needs should be
+handled by an application talking to DBus directly"
+([source](https://libinput.pages.freedesktop.org/libei/api/group__liboeffis.html)).
 
-What works is negotiating the portal yourself over D-Bus and handing the
-resulting fd to `Sender.create_for_fd()`, which does not care where the fd
-came from:
+`libei.portal` is that: the same `CreateSession` → `SelectDevices` → `Start`
+→ `ConnectToEIS` sequence, driven directly over D-Bus (needs PyGObject —
+`pip install 'python-libei[portal]'`), with `persist_mode`/`restore_token`
+as real parameters:
 
-1. `CreateSession` on `org.freedesktop.portal.RemoteDesktop`
-2. `SelectDevices` with `persist_mode` (1 = while running, 2 = until
-   revoked) and, on later runs, the saved `restore_token`
-3. `Start` — the response carries a fresh `restore_token`, which you store
-4. `ConnectToEIS` — the fd for `ei.Sender.create_for_fd()`
+```python
+from libei import ei, portal
+
+with portal.RemoteDesktopSession.negotiate(
+    devices=portal.DeviceType.POINTER,
+    persist_mode=portal.PersistMode.UNTIL_REVOKED,
+    restore_token=saved_token,  # None on the first run
+) as session:
+    save_somewhere(session.restore_token)  # a fresh token every time -- save it
+    sender = ei.Sender.create_for_fd(session.eis_fd, name="my-app")
+    ...  # inject input for as long as the session is needed
+```
 
 Save the token somewhere durable and pass it back next time; the portal then
 restores the session without prompting. Treat it as a credential — anyone
 holding it can reopen input injection on that desktop, so it belongs
 wherever you'd keep a password, and the decision to store it at all belongs
-to the application rather than to a library.
+to the application rather than to this library, which never writes it
+anywhere itself.
+
+Save whatever comes back on **every** run, not just the first: the portal is
+free to hand back a different token each time, and a caller that keeps only
+the original would eventually present a stale one. (On GNOME the same token
+comes back on each restore — that is one portal's behaviour, not a
+guarantee.) Passing `restore_token` *without* a `persist_mode` raises
+`ValueError`: the portal answers such a request with no token at all, so
+storing what came back would write `None` over the token you just spent.
+
+Three differences from `Oeffis` above worth knowing:
+
+- **Blocking, not event-driven.** `negotiate()` runs its own nested
+  `GLib.MainLoop` per D-Bus round trip and returns only once connected, or
+  raises `PortalVersionError` / `PortalDeniedError` / `PortalTimeoutError`.
+- **Bounded.** Each round trip gets `timeout` seconds (60 by default —
+  generous, since `Start` waits on a human answering a dialog). Without it a
+  portal that dies after accepting the call would wedge the calling thread
+  forever, which is the one thing `Oeffis`'s pollable fd protects against.
+- **Close it.** The portal session lives in xdg-desktop-portal and outlives
+  the object unless `Session.Close()` is called — `Gio.bus_get_sync()` hands
+  back GLib's *shared* connection, so dropping the session tears nothing
+  down, and a long-running process that negotiates repeatedly accumulates
+  live sessions. The `with` block above handles it; otherwise call
+  `session.close()`.
 
 ## Sending input
 
@@ -633,6 +700,7 @@ the capability you bound (`seat.capabilities`).
 | `libei.ei` | Clients: `Sender` (inject), `Receiver` (consume) |
 | `libei.eis` | Servers: `Eis`, for compositors and for testing clients |
 | `libei.oeffis` | Getting an EI fd from the desktop portal |
+| `libei.portal` | The same, over D-Bus directly, with `persist_mode`/`restore_token` |
 
 Each module has `is_available()`, an `Error` exception, and an `EventType` /
 `DeviceCapability` enum. `ei` and `eis` also share the shapes around them:
@@ -657,6 +725,12 @@ them in this order -- each one only makes sense once the one below it does.
 | [`_cobject.py`](src/libei/_cobject.py) | `CObject`: pointer ownership, refcounting, and the identity cache that every wrapper class inherits |
 | [`ei.py`](src/libei/ei.py), [`eis.py`](src/libei/eis.py), [`oeffis.py`](src/libei/oeffis.py) | The public API: Python classes, enums and dataclasses over the raw calls |
 
+[`portal.py`](src/libei/portal.py) sits outside this stack entirely -- there
+is no C library behind it, so no `_capi` binding and no `CObject`. It talks
+D-Bus directly through PyGObject (`Gio`/`GLib`, imported lazily the same way
+the C libraries are loaded lazily) and only ever produces a plain fd, which
+is where it hands off to `ei.Sender.create_for_fd()`.
+
 **Read `_cobject.py` first.** It is the smallest file with the most
 consequence: get `wrap()` vs `adopt()`, the `staticmethod()` wrapping of
 `_ref_func`/`_unref_func`, or the `_wrappable` flag wrong and the failure is
@@ -721,16 +795,17 @@ Versions are SemVer and live in two places -- `pyproject.toml` and
 `src/libei/__init__.py` -- which have to agree with each other and with the
 tag. Nothing enforces that yet.
 
-A release is an annotated, `v`-prefixed tag plus a GitHub Release:
+A release is an annotated, `v`-prefixed tag. Pushing it is the whole of it;
+PyPI is the only place a release is published, and no GitHub Release is cut:
 
 ```sh
-git tag -a v0.1.0 -m "0.1.0"
-git push origin v0.1.0
-gh release create v0.1.0 --generate-notes --prerelease
+git tag -a v0.2.0 -m "0.2.0"
+git push origin v0.2.0
 ```
 
-`--prerelease` while the API is unfrozen -- it keeps an alpha out of the
-"Latest release" slot.
+While the API is unfrozen, the pre-release signal lives in the version
+itself: a PEP 440 suffix (`0.2.0a1`) keeps a plain `pip install
+python-libei` off it, and a `0.x` version already says the API can move.
 
 Publishing runs from CI on a `v*` tag using PyPI
 [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC), so
@@ -739,22 +814,24 @@ job in `ci.yml` handles it, uploading the artifacts the `build` job already
 ran `twine check` over.
 
 That job depends on two pieces of configuration outside this repository,
-which have to exist before the first tag:
-
-1. On pypi.org, under Account settings -> Publishing, a **pending**
-   publisher -- the flow for a project that has no releases yet. Project
-   `python-libei`, owner `ctrondlp`, repository `python-libei`, workflow
-   `ci.yml`, environment `pypi`. Every field has to match the workflow
+both of which are in place as of `0.1.0`:
+
+1. On pypi.org, a trusted publisher on the `python-libei` project: owner
+   `ctrondlp`, repository `python-libei`, workflow `ci.yml`, environment
+   `pypi`. It started life as a **pending** publisher -- the flow for a
+   project with no releases yet -- and the first upload converted it into
+   an ordinary project-level one, so a fresh project is the only case that
+   needs the pending form again. Every field has to match the workflow
    exactly; a mismatch surfaces as a rejected credential at upload time,
    not when it is saved.
 2. A GitHub environment named `pypi`, in the repository settings. A
    required reviewer on it makes each publish a deliberate approval rather
    than a side effect of pushing a tag.
 
-Worth rehearsing on TestPyPI first: separate account, separate pending
-publisher, and `repository-url: https://test.pypi.org/legacy/` on the
-publish step. PyPI filenames are immutable, so a bad upload can only be
-yanked and superseded by a new version, never replaced.
+PyPI filenames are immutable, so a bad upload can only be yanked and
+superseded by a new version, never replaced -- worth rehearsing anything
+unusual on TestPyPI first (separate account, separate pending publisher,
+and `repository-url: https://test.pypi.org/legacy/` on the publish step).
 
 ## Design notes
 

{python_libei-0.1.0 → python_libei-0.3.0}/README.md

@@ -100,8 +100,9 @@ pointer.
 
 ## Status
 
-Alpha (`0.1.0`), not yet on PyPI, and the API is not frozen — expect
-renames before 1.0. What that qualifier covers, concretely:
+Alpha (`0.3.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. What
+that qualifier covers, concretely:
 
 - The injection path — connect, bind, wait for a device, send events — is
   exercised end-to-end against the real libraries by
@@ -110,9 +111,20 @@ renames before 1.0. What that qualifier covers, concretely:
 - Text input, touch cancellation, ping/pong, keymap transfer, region mapping
   ids and `peek_event_type()` are each round-tripped through a real libeis
   server in `tests/test_integration_extras.py`.
-- The portal path (`libei.oeffis`) has only ever been verified by hand, since
-  it needs an interactive consent dialog that nothing here can drive. See
-  [Troubleshooting](#troubleshooting).
+- Both portal paths (`libei.oeffis` and `libei.portal`) can only ever be
+  verified by hand, since they need an interactive consent dialog that
+  nothing here can drive automatically — `tests/test_portal.py` covers
+  `libei.portal`'s orchestration (raceless subscribe-before-call, the
+  `session_handle_token` crash workaround, persist_mode/restore_token)
+  against a fake D-Bus connection only. `libei.oeffis` was verified by hand
+  on 2026-08-25 (see [Troubleshooting](#troubleshooting)), and
+  `libei.portal` on 2026-09-01 against a real GNOME Wayland session
+  (`RemoteDesktop` v2): a first run raised the consent dialog and was
+  approved (5.4s), a second replaying the `restore_token` was granted with
+  no dialog at all (0.2s), three devices resumed on the returned fd
+  (relative pointer, keyboard, absolute pointer — in that order, the device
+  race `ei`-side callers must handle), and `Session.Close()` was exercised.
+  No input was injected — emulation is `libei.ei`'s job.
 - Verified against libei 1.6.0 on Fedora 44 / GNOME 50.4, and against a
   locally built 1.2.1 (130 passed, 4 skipped — the 1.4 and 1.6 features
   gate themselves out). CI repeats the 1.2.1 run on Python 3.10-3.13, so
@@ -124,7 +136,7 @@ renames before 1.0. What that qualifier covers, concretely:
 | Instead of this | Why you might |
 | --- | --- |
 | [snegg](https://gitlab.freedesktop.org/whot/snegg) | The reference bindings, by libei's own author — closer to upstream, and first to get new API. Self-described as for "rapid prototyping" with an explicitly unstable API, and `import snegg.ei` fails outright where libei isn't installed. [`docs/vs-snegg.md`](docs/vs-snegg.md) covers the differences in detail. |
-| The portal's D-Bus API directly (`org.freedesktop.portal.RemoteDesktop`, via Gio or dbus-python) | No native library and no bindings at all — `NotifyPointerMotion`, `NotifyKeyboardKeycode` and friends are plain method calls. The catch is absolute motion: `NotifyPointerMotionAbsolute` needs a PipeWire stream id, which only exists after a second, separate ScreenCast consent dialog. libei has no such requirement. |
+| The RemoteDesktop portal's own D-Bus API directly (`NotifyPointerMotion`, `NotifyKeyboardKeycode`, …), bypassing libei/EI entirely | `libei.portal` already gets you the D-Bus session and its `persist_mode`/`restore_token` handling — reach past libei entirely only if you don't want the EI protocol at all. The catch if you do: `NotifyPointerMotionAbsolute` needs a PipeWire stream id, which only exists after a second, separate ScreenCast consent dialog. libei has no such requirement. |
 | `ydotool` and other `/dev/uinput` tools | Kernel-level, so they work under any compositor and need no portal session — at the cost of a privileged daemon, and of sidestepping the consent model that EI exists to enforce. |
 
 ## Requirements
@@ -132,6 +144,10 @@ renames before 1.0. What that qualifier covers, concretely:
 - Linux with a Wayland compositor (GNOME, KDE, Sway, …)
 - CPython 3.10 or newer (tested on 3.13)
 - The native libraries: on Fedora, `sudo dnf install libei libeis liboeffis`
+- `libei.portal` only: PyGObject (`pip install 'python-libei[portal]'`), plus
+  whatever GObject-introspection libraries your distro needs for `Gio` --
+  PyPI's PyGObject wheel supplies the Python side only. Not needed for
+  `libei.ei`, `libei.eis` or `libei.oeffis`.
 - 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
@@ -161,17 +177,29 @@ renames before 1.0. What that qualifier covers, concretely:
 
 ## Install
 
-Not published to PyPI yet — install from a checkout:
+From [PyPI](https://pypi.org/project/python-libei/):
 
 ```sh
-git clone https://github.com/ctrondlp/python-libei.git
-cd python-libei
-pip install .
+pip install python-libei
 ```
 
 The distribution is named `python-libei`, the import is `libei` -- so
 `pip show python-libei`, but `from libei import ei`.
 
+Pure Python, no build step: the wheel is `py3-none-any` and ctypes talks to
+the native libraries directly, so there is no compiler, no headers and no
+`libei-devel` involved at install time. What `pip` does *not* bring is the
+native libraries themselves -- see [Requirements](#requirements) above; on
+Fedora, `sudo dnf install libei libeis liboeffis`.
+
+To track `main` instead, or to hack on it, install from a checkout:
+
+```sh
+git clone https://github.com/ctrondlp/python-libei.git
+cd python-libei
+pip install .          # or `pip install -e '.[dev]'` to develop
+```
+
 Importing is always safe, even where the native libraries are missing — they
 are loaded on first use, not at import. Check before you rely on them:
 
@@ -255,23 +283,59 @@ several devices — see the absolute-positioning notes under
 call and exposes no options dict, so the two things that make an approval
 persist — `persist_mode` on `SelectDevices`, and the `restore_token` that
 comes back on `Start` — are unreachable through it. This is a limitation of
-the C library, not of these bindings; there is nothing here left to bind.
+the C library, not of these bindings; upstream's own docs say as much:
+liboeffis is "intentionally kept simple, any more complex needs should be
+handled by an application talking to DBus directly"
+([source](https://libinput.pages.freedesktop.org/libei/api/group__liboeffis.html)).
 
-What works is negotiating the portal yourself over D-Bus and handing the
-resulting fd to `Sender.create_for_fd()`, which does not care where the fd
-came from:
+`libei.portal` is that: the same `CreateSession` → `SelectDevices` → `Start`
+→ `ConnectToEIS` sequence, driven directly over D-Bus (needs PyGObject —
+`pip install 'python-libei[portal]'`), with `persist_mode`/`restore_token`
+as real parameters:
 
-1. `CreateSession` on `org.freedesktop.portal.RemoteDesktop`
-2. `SelectDevices` with `persist_mode` (1 = while running, 2 = until
-   revoked) and, on later runs, the saved `restore_token`
-3. `Start` — the response carries a fresh `restore_token`, which you store
-4. `ConnectToEIS` — the fd for `ei.Sender.create_for_fd()`
+```python
+from libei import ei, portal
+
+with portal.RemoteDesktopSession.negotiate(
+    devices=portal.DeviceType.POINTER,
+    persist_mode=portal.PersistMode.UNTIL_REVOKED,
+    restore_token=saved_token,  # None on the first run
+) as session:
+    save_somewhere(session.restore_token)  # a fresh token every time -- save it
+    sender = ei.Sender.create_for_fd(session.eis_fd, name="my-app")
+    ...  # inject input for as long as the session is needed
+```
 
 Save the token somewhere durable and pass it back next time; the portal then
 restores the session without prompting. Treat it as a credential — anyone
 holding it can reopen input injection on that desktop, so it belongs
 wherever you'd keep a password, and the decision to store it at all belongs
-to the application rather than to a library.
+to the application rather than to this library, which never writes it
+anywhere itself.
+
+Save whatever comes back on **every** run, not just the first: the portal is
+free to hand back a different token each time, and a caller that keeps only
+the original would eventually present a stale one. (On GNOME the same token
+comes back on each restore — that is one portal's behaviour, not a
+guarantee.) Passing `restore_token` *without* a `persist_mode` raises
+`ValueError`: the portal answers such a request with no token at all, so
+storing what came back would write `None` over the token you just spent.
+
+Three differences from `Oeffis` above worth knowing:
+
+- **Blocking, not event-driven.** `negotiate()` runs its own nested
+  `GLib.MainLoop` per D-Bus round trip and returns only once connected, or
+  raises `PortalVersionError` / `PortalDeniedError` / `PortalTimeoutError`.
+- **Bounded.** Each round trip gets `timeout` seconds (60 by default —
+  generous, since `Start` waits on a human answering a dialog). Without it a
+  portal that dies after accepting the call would wedge the calling thread
+  forever, which is the one thing `Oeffis`'s pollable fd protects against.
+- **Close it.** The portal session lives in xdg-desktop-portal and outlives
+  the object unless `Session.Close()` is called — `Gio.bus_get_sync()` hands
+  back GLib's *shared* connection, so dropping the session tears nothing
+  down, and a long-running process that negotiates repeatedly accumulates
+  live sessions. The `with` block above handles it; otherwise call
+  `session.close()`.
 
 ## Sending input
 
@@ -600,6 +664,7 @@ the capability you bound (`seat.capabilities`).
 | `libei.ei` | Clients: `Sender` (inject), `Receiver` (consume) |
 | `libei.eis` | Servers: `Eis`, for compositors and for testing clients |
 | `libei.oeffis` | Getting an EI fd from the desktop portal |
+| `libei.portal` | The same, over D-Bus directly, with `persist_mode`/`restore_token` |
 
 Each module has `is_available()`, an `Error` exception, and an `EventType` /
 `DeviceCapability` enum. `ei` and `eis` also share the shapes around them:
@@ -624,6 +689,12 @@ them in this order -- each one only makes sense once the one below it does.
 | [`_cobject.py`](src/libei/_cobject.py) | `CObject`: pointer ownership, refcounting, and the identity cache that every wrapper class inherits |
 | [`ei.py`](src/libei/ei.py), [`eis.py`](src/libei/eis.py), [`oeffis.py`](src/libei/oeffis.py) | The public API: Python classes, enums and dataclasses over the raw calls |
 
+[`portal.py`](src/libei/portal.py) sits outside this stack entirely -- there
+is no C library behind it, so no `_capi` binding and no `CObject`. It talks
+D-Bus directly through PyGObject (`Gio`/`GLib`, imported lazily the same way
+the C libraries are loaded lazily) and only ever produces a plain fd, which
+is where it hands off to `ei.Sender.create_for_fd()`.
+
 **Read `_cobject.py` first.** It is the smallest file with the most
 consequence: get `wrap()` vs `adopt()`, the `staticmethod()` wrapping of
 `_ref_func`/`_unref_func`, or the `_wrappable` flag wrong and the failure is
@@ -688,16 +759,17 @@ Versions are SemVer and live in two places -- `pyproject.toml` and
 `src/libei/__init__.py` -- which have to agree with each other and with the
 tag. Nothing enforces that yet.
 
-A release is an annotated, `v`-prefixed tag plus a GitHub Release:
+A release is an annotated, `v`-prefixed tag. Pushing it is the whole of it;
+PyPI is the only place a release is published, and no GitHub Release is cut:
 
 ```sh
-git tag -a v0.1.0 -m "0.1.0"
-git push origin v0.1.0
-gh release create v0.1.0 --generate-notes --prerelease
+git tag -a v0.2.0 -m "0.2.0"
+git push origin v0.2.0
 ```
 
-`--prerelease` while the API is unfrozen -- it keeps an alpha out of the
-"Latest release" slot.
+While the API is unfrozen, the pre-release signal lives in the version
+itself: a PEP 440 suffix (`0.2.0a1`) keeps a plain `pip install
+python-libei` off it, and a `0.x` version already says the API can move.
 
 Publishing runs from CI on a `v*` tag using PyPI
 [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC), so
@@ -706,22 +778,24 @@ job in `ci.yml` handles it, uploading the artifacts the `build` job already
 ran `twine check` over.
 
 That job depends on two pieces of configuration outside this repository,
-which have to exist before the first tag:
-
-1. On pypi.org, under Account settings -> Publishing, a **pending**
-   publisher -- the flow for a project that has no releases yet. Project
-   `python-libei`, owner `ctrondlp`, repository `python-libei`, workflow
-   `ci.yml`, environment `pypi`. Every field has to match the workflow
+both of which are in place as of `0.1.0`:
+
+1. On pypi.org, a trusted publisher on the `python-libei` project: owner
+   `ctrondlp`, repository `python-libei`, workflow `ci.yml`, environment
+   `pypi`. It started life as a **pending** publisher -- the flow for a
+   project with no releases yet -- and the first upload converted it into
+   an ordinary project-level one, so a fresh project is the only case that
+   needs the pending form again. Every field has to match the workflow
    exactly; a mismatch surfaces as a rejected credential at upload time,
    not when it is saved.
 2. A GitHub environment named `pypi`, in the repository settings. A
    required reviewer on it makes each publish a deliberate approval rather
    than a side effect of pushing a tag.
 
-Worth rehearsing on TestPyPI first: separate account, separate pending
-publisher, and `repository-url: https://test.pypi.org/legacy/` on the
-publish step. PyPI filenames are immutable, so a bad upload can only be
-yanked and superseded by a new version, never replaced.
+PyPI filenames are immutable, so a bad upload can only be yanked and
+superseded by a new version, never replaced -- worth rehearsing anything
+unusual on TestPyPI first (separate account, separate pending publisher,
+and `repository-url: https://test.pypi.org/legacy/` on the publish step).
 
 ## Design notes
 

{python_libei-0.1.0 → python_libei-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-libei"
-version = "0.1.0"
+version = "0.3.0"
 description = "Inject and receive input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis"
 readme = "README.md"
 license = "MIT"
@@ -50,12 +50,18 @@ classifiers = [
 dependencies = []
 
 [project.optional-dependencies]
+# libei.portal negotiates the RemoteDesktop portal directly over D-Bus, which
+# needs PyGObject for Gio/GLib. The native GObject-introspection libraries
+# still have to come from the distro -- PyPI's PyGObject wheel only supplies
+# the Python side. Not needed for libei.ei/libei.eis/libei.oeffis.
+portal = ["PyGObject>=3.42"]
 dev = ["pytest>=7", "ruff>=0.6", "mypy>=1.11"]
 
 [project.urls]
 homepage = "https://github.com/ctrondlp/python-libei"
 repository = "https://github.com/ctrondlp/python-libei"
 issues = "https://github.com/ctrondlp/python-libei/issues"
+changelog = "https://github.com/ctrondlp/python-libei/blob/main/CHANGELOG.md"
 
 [tool.setuptools.packages.find]
 where = ["src"]
@@ -95,3 +101,12 @@ strict = true
 # Every property in ei.py/eis.py/oeffis.py re-types a raw C call's result,
 # so this fires everywhere in the wrapper layer for no actionable reason.
 warn_return_any = false
+
+# PyGObject is an optional extra (see [project.optional-dependencies].portal),
+# so `gi` may or may not be importable where mypy runs. Without this, the two
+# error codes differ by environment -- import-untyped when PyGObject is
+# installed, import-not-found when it isn't -- and an inline ignore pinned to
+# either one fails in the other. libei.portal already treats gi as Any.
+[[tool.mypy.overrides]]
+module = ["gi.*"]
+ignore_missing_imports = true

{python_libei-0.1.0 → python_libei-0.3.0}/src/libei/__init__.py

@@ -13,6 +13,9 @@ Use the submodules directly:
   drive a test harness for the ``ei`` module without a real compositor)
 - :mod:`libei.oeffis` -- negotiate an EI connection through the
   ``org.freedesktop.portal.RemoteDesktop`` XDG desktop portal
+- :mod:`libei.portal` -- negotiate that same portal directly over D-Bus
+  instead, for ``persist_mode``/``restore_token`` support liboeffis's C API
+  doesn't expose
 
 Scope, in short: this needs a compositor speaking EI/EIS -- there is no X11
 fallback. Pointer (relative and absolute), button, keyboard, scroll, touch
@@ -26,6 +29,6 @@ the full breakdown, including which features need which libei version.
 Alpha: the API is not frozen.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 
 __all__ = ["__version__"]