Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 89 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,23 @@ All notable changes to python-libei are recorded here. The format follows

### Added

- **`LibraryNotFoundError` is now part of `libei.ei`'s, `libei.eis`'s and
`libei.oeffis`'s public surface.** It has always been raised from all
three -- `_capi/loader.py` raises it the moment a `dlopen` fails, or an
installed library turns out too old to export a bound function -- and
`docs/troubleshooting.md` had been telling readers to write
`from libei.ei import Error, LibraryNotFoundError` since its exceptions
table went in. It was in no module's `__all__`, alone among the eight
classes that table names: catching `ei.LibraryNotFoundError` worked, but
`from libei.ei import *`, `pydoc`, an IDE's completion, and anything else
reading a module's declared surface did not see it, and the only
obviously public place to import it from was the private
`libei._capi.loader` it is defined in. Two of the three modules come from
the table; `libei.oeffis` was found while fixing those, `Oeffis.create()`
on a machine with no liboeffis being the same failure one module over.
Nothing moved to the package root either way: `libei/__init__.py` still
carries only `__version__`, as that page says.

- **`docs/troubleshooting.md` now names the exceptions, having been the page
for everything that *doesn't* raise.** Eight classes are raised from real
paths and were named in no user-facing text: `ei.Error` and `eis.Error` (22
Expand Down Expand Up @@ -36,6 +53,78 @@ All notable changes to python-libei are recorded here. The format follows
connection and lifecycle events, which have no getter and are read through
`event_type`.

### Changed

- **The docstring-completeness check now runs everywhere, and covers
`libei.portal`.** It lived in `tests/test_documented_examples.py`, whose
module-level `integration` mark skips the file where the native libraries
are absent -- so a check that reads source with `ast` and needs nothing
installed was skipping on exactly the machines where it was cheapest to
run. It now sits in `tests/test_documentation_shape.py`, beside the other
checks that need no native library, takes in classes as well as functions,
and includes `libei.portal`, which was never checked. Nothing had to be
written to make it pass: every public definition in all four modules
already carries a docstring, so this is a guard rather than a cleanup.

- **A new check ties the exceptions table to the modules it names.**
`tests/test_documentation_shape.py` now reads the table in
`docs/troubleshooting.md` and asserts that every class it pairs with a
module is both reachable from that module and listed in its `__all__` --
and that a class shared between modules is one class in all of them, which
is what makes one `except` clause cover every module that raises it. This
is the check that would have caught `LibraryNotFoundError` when the table
itself was written.

- **The documentation guards reach the files that were drifting.**
`tests/test_documentation_shape.py` compared the README's version line
against `libei.__version__` but not the developers page's, which is how
0.5.1 sat there through a release; both pages are compared now. The
module-docstring example check covered the two modules that used `::` and
read nothing at all from the two that did not -- both are covered now, all
four public modules. A new check reads every docstring in those modules
for the two defects below, neither of which is visible anywhere but in the
rendered text: a role split across a line break, and an unpaired backtick.
And `tests/test_portal.py` now asserts what `verification.md` claimed it
covered -- that `CreateSession` carries a `session_handle_token`, whose
absence crashes xdg-desktop-portal 1.22.1 outright.

### Fixed

- **`scripts/pre-commit-test.sh` failed its `tests` check on any interpreter
without the package installed.** The script runs `python -m pytest -q -rs`
with no `PYTHONPATH`, deliberately: CI's install step is one of the two
things it leaves to the runner. But `[tool.pytest.ini_options]` here had
only `testpaths`, so nothing put `src` on the path, and `tests/conftest.py`'s
`from libei import ei` died at collection -- reporting an ImportError for
the whole suite where pyguitest and pyguitest-recorder both set
`pythonpath = ["src"]` and just run. The other four checks passed, which is
what made it look like a test failure rather than a path one. Same setting
added here; a bare checkout now runs the suite with nothing installed, which
is also what makes a copied tree testable anywhere.

- **Four documentation defects, each invisible from the page it is on.**
`docs/developers/verification.md` opened with "the package is beta
(`0.5.1`)" a release after 0.5.2 shipped, and nothing compared that prose
to `pyproject.toml` the way the README's own version line is compared. The
same page and `docs/vs-snegg.md` both pointed a reader at "the README's
Troubleshooting section", which has never existed -- the GNOME 44
explanation they mean is in `docs/troubleshooting.md`, and both links now
go there. And `InputCaptureSession`'s own docstring broke a role across a
line, so `:meth:`wait_for_activation`` rendered as the literal text
":meth:" and a name rather than as a link. The README's module table also
promised that *each* module carries an `Error` exception and an
`EventType`/`DeviceCapability` enum, which holds for `ei` and `eis` only:
`oeffis` and `portal` raise their own classes and carry `DeviceType`
instead, so a reader writing `except oeffis.Error` was chasing a class
that does not exist. All four are corrected.

- **The two module docstrings that carry a usage example now mark it as
one.** `oeffis` and `portal` wrote their examples as plain indented
blocks, where `ei` and `eis` use the `::` a reST literal block needs --
which is also why the example check had never read either of them, since
the extractor looks for that marker. The blocks themselves were already
valid Python and unaffected.

## [0.5.2] - 2026-09-12

### Added
Expand Down
13 changes: 8 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,11 +70,14 @@ to get permission, then `ei` to inject.
| **Get permission**, and not be asked again | `libei.portal` | Same handshake over D-Bus directly, with `persist_mode` / `restore_token`. Needs PyGObject |
| **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`, 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

Expand Down
7 changes: 4 additions & 3 deletions docs/developers/verification.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# What has actually been verified

The package is beta (`0.5.1`) and the API is not frozen — expect renames
The package is beta (`0.5.2`) and the API is not frozen — expect renames
before 1.0. This page is what that qualifier covers, concretely: which paths
have been driven against real libraries, which have only ever been driven
against fakes, and which libei versions the whole thing has met.
Expand All @@ -27,8 +27,9 @@ a negotiation that fails part-way.

By hand:

- **`libei.oeffis`**, 2026-08-25. See the README's troubleshooting section for
what that run established about the GNOME 44 hangs.
- **`libei.oeffis`**, 2026-08-25. See
[troubleshooting.md](../troubleshooting.md#the-portal-dialog-appears-i-approve-it-and-nothing-happens)
for what that run established about the GNOME 44 hangs.
- **`libei.portal.RemoteDesktopSession`**, 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
Expand Down
8 changes: 4 additions & 4 deletions docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ import each from the module that raises it.
| `libei.portal` | `PortalVersionError` | The RemoteDesktop portal is too old to offer `ConnectToEIS` |
| `libei.portal` | `PortalTimeoutError` | A step was accepted and never answered. Carries `.step` and `.timeout` |
| `libei.portal` | `PortalDeniedError` | `CreateSession`, `SelectDevices` or `Start` came back non-zero — an explicit decline, or any other code the spec does not distinguish from one. Carries `.step` and `.message` |
| `libei.ei`, `libei.eis` | `LibraryNotFoundError` | The native library is missing or too old to export the function being called. A `RuntimeError`, and raised at the first *call* — see below |
| `libei.ei`, `libei.eis`, `libei.oeffis` | `LibraryNotFoundError` | The native library is missing or too old to export the function being called. A `RuntimeError`, and raised at the first *call* — see below |

Which of those to catch depends on the families, because they do not nest under
a single base:
Expand Down Expand Up @@ -116,9 +116,9 @@ a single base:
## `LibraryNotFoundError`

The native library is not installed, or is too old to export a function this
package binds. Check with `ei.is_available()`; the package name for your
distribution, and what to do when it does not match, is in
[install.md](install.md).
package binds. Check with `ei.is_available()`, or `oeffis.is_available()` for
a missing liboeffis; the package name for your distribution, and what to do
when it does not match, is in [install.md](install.md).

Because loading is lazy, this is raised at the first *call*, not at import —
so an application can import this package, discover the libraries are absent,
Expand Down
9 changes: 5 additions & 4 deletions docs/vs-snegg.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,10 +99,11 @@ project -- it needs an interactive consent dialog, which nothing here drives
programmatically. It was manually verified working on 2026-08-25 on GNOME
50.4 (`busctl monitor` trace: `CreateSession -> SelectDevices -> Start ->
ConnectToEIS`, 3/3 attempts, a few seconds each), after an earlier attempt on
GNOME 44 saw it hang. See the README's Troubleshooting section for the likely
explanation. Manual verification isn't the same guarantee automated coverage
would be, so treat `oeffis` as the least *automatically* verified part of
this package -- see the note in `tests/test_oeffis.py`.
GNOME 44 saw it hang. See
[troubleshooting.md](troubleshooting.md#the-portal-dialog-appears-i-approve-it-and-nothing-happens)
for the likely explanation. Manual verification isn't the same guarantee
automated coverage would be, so treat `oeffis` as the least *automatically*
verified part of this package -- see the note in `tests/test_oeffis.py`.

## Two things found while building the integration test

Expand Down
8 changes: 8 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,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",
]
Expand Down
4 changes: 4 additions & 0 deletions src/libei/ei.py
Original file line number Diff line number Diff line change
Expand Up @@ -1295,6 +1295,10 @@ def create_for_socket(
"KeyEvent",
"Keymap",
"KeymapType",
# Imported rather than defined here: every call bound through
# _capi.libei can raise it, so a caller importing from this module
# catches it from here too -- see docs/troubleshooting.md.
"LibraryNotFoundError",
"Ping",
"PointerAbsoluteEvent",
"PointerEvent",
Expand Down
4 changes: 4 additions & 0 deletions src/libei/eis.py
Original file line number Diff line number Diff line change
Expand Up @@ -1278,6 +1278,10 @@ def create_for_socket(cls, path: Path, flags: Sequence[Flag] = ()) -> Eis:
"KeyEvent",
"Keymap",
"KeymapType",
# Imported rather than defined here: every call bound through
# _capi.libeis can raise it, so a caller importing from this module
# catches it from here too -- see docs/troubleshooting.md.
"LibraryNotFoundError",
"Ping",
"PointerAbsoluteEvent",
"PointerEvent",
Expand Down
8 changes: 7 additions & 1 deletion src/libei/oeffis.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
This is the path a sandboxed or otherwise non-privileged client uses to get
an EI socket: it asks the portal, the user is shown a consent dialog, and on
approval this hands back a file descriptor to pass to
:meth:`libei.ei.Sender.create_for_fd`.
:meth:`libei.ei.Sender.create_for_fd`::

oeffis = Oeffis.create(devices=DeviceType.POINTER)
while True:
Expand Down Expand Up @@ -41,6 +41,7 @@
import os

from . import _capi
from ._capi.loader import LibraryNotFoundError

logger = logging.getLogger("libei.oeffis")

Expand Down Expand Up @@ -242,6 +243,11 @@ def create(
__all__ = [
"DeviceType",
"DisconnectedError",
# Imported rather than defined here: every call bound through
# _capi.liboeffis can raise it -- Oeffis.create() on a machine with no
# liboeffis is the ordinary one -- so a caller importing from this
# module catches it from here too. See docs/troubleshooting.md.
"LibraryNotFoundError",
"Oeffis",
"SessionClosedError",
"is_available",
Expand Down
6 changes: 3 additions & 3 deletions src/libei/portal.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
(https://libinput.pages.freedesktop.org/libei/api/group__liboeffis.html).
This module is that: the ``CreateSession`` -> ``SelectDevices`` -> ``Start``
-> ``ConnectToEIS`` sequence driven directly, with ``persist_mode`` and
``restore_token`` exposed as real parameters.
``restore_token`` exposed as real parameters::

with RemoteDesktopSession.negotiate(
devices=DeviceType.POINTER | DeviceType.KEYBOARD,
Expand Down Expand Up @@ -1154,8 +1154,8 @@ class InputCaptureSession:
direction: instead of injecting synthetic input, this receives real
input from the user's own devices once the compositor decides to divert
it here. That decision is the whole point of the protocol and is never
this session's to make -- see :meth:`enable` and :meth:`
wait_for_activation`.
this session's to make -- see :meth:`enable` and
:meth:`wait_for_activation`.

**Capturing is exclusive.** Once the compositor activates a capture,
the events it captures stop reaching the desktop entirely and are sent
Expand Down
Loading
Loading