From 3de9151ef57719a66122668223deddac3f467746 Mon Sep 17 00:00:00 2001 From: "Dennis K. Paulsen" Date: Sun, 20 Sep 2026 10:22:44 -0500 Subject: [PATCH] docs: document libei's exceptions and each event type's getter --- CHANGELOG.md | 31 ++++++++++++++++++++++++++++ docs/recipes.md | 32 ++++++++++++++++++++++------- docs/troubleshooting.md | 45 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 101 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1b3bb03..5a0f7be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,37 @@ All notable changes to python-libei are recorded here. The format follows [semantic versioning](https://semver.org/spec/v2.0.0.html) — with the usual 0.x caveat that the API may still change between minor versions. +## [Unreleased] + +### Added + +- **`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 + raise sites between them, two classes sharing no ancestor, carrying + `.errno` where libei reported one), `portal.PortalError` (18 sites, + the "session is closed" path among them) with its three subclasses, and + `oeffis.DisconnectedError`/`SessionClosedError` from a session that ends + under the caller. Only the three portal subclasses appeared anywhere, and + only inside one sentence of `recipes.md`; the two `Error` classes and both + oeffis ones appeared on no page at all — so the names a caller writes in an + `except` clause were exactly the names the docs did not carry. The new + section gives what each is raised for and what nests under what: + `except PortalError` covers its three, `except DisconnectedError` covers + `SessionClosedError`, and `ei.Error`/`eis.Error` cover nothing but + themselves. + +- **`docs/recipes.md` pairs every event type with the getter that reads it.** + The page listed twelve getters in a sentence and never said which event each + one belongs to — the pairing the `TypeError` beside them exists to enforce, + and the reason `keyboard_xkb_modifiers` reads oddly, being the only getter + not named after the class it unwraps. Two more were missing from the + sentence entirely: `pong`, which is used two paragraphs below it, and + `emulating_sequence`. All fourteen are now a table with the fields each + returns and the libei version where one is needed, followed by the + connection and lifecycle events, which have no getter and are read through + `event_type`. + ## [0.5.2] - 2026-09-12 ### Added diff --git a/docs/recipes.md b/docs/recipes.md index 981bc30..d27e74e 100644 --- a/docs/recipes.md +++ b/docs/recipes.md @@ -231,13 +231,31 @@ for event in receiver.events: print(motion.dx, motion.dy) ``` -Each event type has its own getter — `key_event`, `button_event`, -`pointer_event`, `pointer_absolute_event`, `scroll_event`, -`scroll_discrete_event`, `scroll_stop_event`, `touch_event` and -`touch_up_event`, `text_utf8_event`, `text_keysym_event` and -`keyboard_xkb_modifiers` — and **each checks the event's type before reading**, -raising `TypeError` rather than handing back the zero-filled result libei -would give for a mismatch. +Which getter goes with which event is fixed, and **each checks the event's +type before reading**, raising `TypeError` rather than handing back the +zero-filled result libei would give for a mismatch: + +| `event_type` | Getter | You get | +| --- | --- | --- | +| `KEYBOARD_KEY` | `key_event` | `KeyEvent(key, is_press)` — a Linux `KEY_*` code | +| `KEYBOARD_MODIFIERS` | `keyboard_xkb_modifiers` | `XkbModifiersEvent(depressed, latched, locked, group)`, the only getter not named after the class it unwraps | +| `BUTTON_BUTTON` | `button_event` | `ButtonEvent(button, is_press)` — a Linux `BTN_*` code | +| `POINTER_MOTION` | `pointer_event` | `PointerEvent(dx, dy)` | +| `POINTER_MOTION_ABSOLUTE` | `pointer_absolute_event` | `PointerAbsoluteEvent(x, y)`, in the emitting device's `Region` space | +| `SCROLL_DELTA` | `scroll_event` | `ScrollEvent(dx, dy)` — smooth, in logical pixels | +| `SCROLL_DISCRETE` | `scroll_discrete_event` | `ScrollDiscreteEvent(dx, dy)` — detents, 120 to each | +| `SCROLL_STOP`, `SCROLL_CANCEL` | `scroll_stop_event` | `ScrollStopEvent(stop_x, stop_y)` | +| `TOUCH_DOWN`, `TOUCH_MOTION` | `touch_event` | `TouchEvent(touchid, x, y)` | +| `TOUCH_UP` | `touch_up_event` | `TouchUpEvent(touchid, is_cancel)` | +| `TEXT_UTF8` | `text_utf8_event` | `TextUtf8Event(text)` — libei 1.6 | +| `TEXT_KEYSYM` | `text_keysym_event` | `TextKeysymEvent(keysym, is_press)` — libei 1.6 | +| `PONG` | `pong` | the `Ping` this answers — libei 1.4 | +| `DEVICE_START_EMULATING` | `emulating_sequence` | the sequence number of that transaction | + +The lifecycle events — `CONNECT`, `DISCONNECT`, `SEAT_ADDED`, `SEAT_REMOVED`, +`DEVICE_ADDED`, `DEVICE_REMOVED`, `DEVICE_PAUSED`, `DEVICE_RESUMED`, `SYNC`, +`FRAME` and `DEVICE_STOP_EMULATING` — have no getter: read them through +`event_type`, plus `event.device` or `event.seat` where they concern one. Event types this package has never heard of do not raise: `event_type` returns a plain `int`, because libei's own header says the enum "is not exhaustive". diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 726cd7c..16b1d0c 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -68,6 +68,51 @@ Work down it in order. The first three account for most cases. lines for one connect and one motion, and it is the right tool when a negotiation stalls rather than fails. +## When it does raise: which name you are catching + +Everything above is about calls that fail without saying anything. This is the +other half — the names to put in an `except` clause. None of them is exported +from the package root (`libei/__init__.py` exports only `__version__`), so +import each from the module that raises it. + +| Module | Class | Raised for | +| --- | --- | --- | +| `libei.ei` | `Error` | A native call failed: a constructor returned NULL, or `set_fd()`/`set_socket()` returned a negative errno. Carries `.message` and `.errno`, the latter `None` for a bare NULL | +| `libei.eis` | `Error` | The same, on the server side. A separate class, not a subclass of the above | +| `libei.oeffis` | `DisconnectedError` | The portal session ended under the caller — an error, or the request being denied. `.message` holds libei's own wording, and is `None` where it had none | +| `libei.oeffis` | `SessionClosedError` | The portal closed the session deliberately. A `DisconnectedError` subclass, with the message fixed at `Session closed` | +| `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 | + +Which of those to catch depends on the families, because they do not nest under +a single base: + +- **`except PortalError`** covers `PortalVersionError`, `PortalTimeoutError` + and `PortalDeniedError`. `PortalTimeoutError` is the one to think about before + treating it as a failure: the call is still outstanding, and by far the most + common cause is a consent dialog a user has not answered yet. +- **`except DisconnectedError`** covers `SessionClosedError` too. That one is + not an error in libei's view — the session ended normally — which is why it + has its own class rather than reusing its base. +- **`ei.Error` and `eis.Error` have no common ancestor**, so "catch anything + libei raises" is a tuple, not one name: + + ```python + from libei.ei import Error, LibraryNotFoundError + from libei.oeffis import DisconnectedError + from libei.portal import PortalError + + try: + ... + except (Error, PortalError, DisconnectedError, LibraryNotFoundError): + ... + ``` + + A receiver, or a process implementing both sides, wants `libei.eis.Error` in + that tuple as well. + ## `LibraryNotFoundError` The native library is not installed, or is too old to export a function this