Repository navigation
docs: document libei's exceptions and each event type's getter #10
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||
|---|---|---|---|---|---|---|---|---|
|
|
@@ -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 | | ||||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win 🔎 Supported by static analysis🏁 Script executed: sed -n '228,265p' docs/recipes.md
rg -n 'SEAT_BIND|seat_capabilities|class EventType|class Event|def .*capabil|DEVICE_START_EMULATING|event_type' src/libei/eis.pyRepository: ctrondlp/python-libei Length of output: 3748 🏁 Script executed: nl -ba docs/recipes.md | sed -n '236,260p'
printf '\n--- src/libei/eis.py ---\n'
nl -ba src/libei/eis.py | sed -n '60,84p;858,952p'Repository: ctrondlp/python-libei Length of output: 7033 Document The event table omits the public Proposed fix | `DEVICE_START_EMULATING` | `emulating_sequence` | the sequence number of that transaction |
+| `SEAT_BIND` | `seat_capabilities` | the requested `DeviceCapability` values |📝 Committable suggestion
Suggested change
🤖 Prompt for AI Agents |
||||||||
|
|
||||||||
| 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". | ||||||||
|
|
||||||||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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 | | ||
|
Comment on lines
+84
to
+87
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win 🔎 Supported by static analysis🏁 Script executed: sed -n '65,125p' docs/troubleshooting.md
sed -n '130,230p' src/libei/portal.py
rg -n 'PortalError|PortalVersionError|PortalTimeoutError|PortalDeniedError|zones|set_pointer_barriers|persist|persistence' src/libei/portal.pyRepository: ctrondlp/python-libei Length of output: 13664 Complete the portal exception table.
Add a 🤖 Prompt for AI Agents |
||
|
|
||
| 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): | ||
|
Comment on lines
+99
to
+109
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win Narrow the “catch anything libei raises” claim. This tuple catches 🤖 Prompt for AI Agents |
||
| ... | ||
| ``` | ||
|
|
||
| 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 | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🔎 Supported by static analysis
🏁 Script executed:
Repository: ctrondlp/python-libei
Length of output: 3456
Remove the exclusive “only” claim. The
PONGrow mapspongtoPing, so use “a getter not named after the class it unwraps” instead.🤖 Prompt for AI Agents