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

{python_libei-0.5.2 → python_libei-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-libei
-Version: 0.5.2
+Version: 0.6.0
 Summary: Inject and receive input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis
 Author: Dennis K. Paulsen
 License-Expression: MIT
@@ -37,6 +37,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
@@ -103,11 +107,15 @@ 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`, `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
 
@@ -149,14 +157,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.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.
 
 The injection path is exercised end to end against the real libraries by the
@@ -394,8 +404,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.0}/README.md

@@ -1,5 +1,9 @@
 # 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
@@ -66,11 +70,15 @@ 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`, `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
 
@@ -112,14 +120,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.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.
 
 The injection path is exercised end to end against the real libraries by the
@@ -357,8 +367,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.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-libei"
-version = "0.5.2"
+version = "0.6.0"
 description = "Inject and receive input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis"
 readme = "README.md"
 license = "MIT"
@@ -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",
 ]

{python_libei-0.5.2 → python_libei-0.6.0}/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.0"
 
 __all__ = ["__version__"]

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

@@ -25,12 +25,18 @@ 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()
 
     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
@@ -91,6 +97,7 @@ class LazyLibrary:
         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")

{python_libei-0.5.2 → python_libei-0.6.0}/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

{python_libei-0.5.2 → python_libei-0.6.0}/src/libei/ei.py

@@ -67,6 +67,7 @@ _emulating_sequence = itertools.count(1)
 
 
 def _next_emulating_sequence() -> int:
+    """The next emulating-event sequence number: 32-bit, and never 0."""
     # Masked into uint32 to match the C parameter. libei asks callers to
     # keep wraparound detection "reasonable"; skipping 0 keeps the value
     # away from anything that might read as unset.
@@ -192,6 +193,8 @@ class KeymapType(enum.IntEnum):
 
 
 class _LogPriority(enum.IntEnum):
+    """The log levels, as the integers the C library passes to its handler."""
+
     DEBUG = 10
     INFO = 20
     WARNING = 30
@@ -329,6 +332,7 @@ class Region(CObject):
     _unref_func = staticmethod(_capi.libei.region_unref)
 
     def __repr__(self) -> str:
+        """The size and position, as WxH+X+Y."""
         w, h = self.dimension
         x, y = self.position
         return f"<Region {w}x{h}+{x}+{y}>"
@@ -510,6 +514,7 @@ class Device(CObject):
     _unref_func = staticmethod(_capi.libei.device_unref)
 
     def __repr__(self) -> str:
+        """Name, device type and capabilities -- what tells two devices apart."""
         caps = "|".join(c.name or str(c.value) for c in self.capabilities)
         return f"<Device {self.name!r} {self.device_type.name} {caps}>"
 
@@ -692,6 +697,7 @@ class Seat(CObject):
     _unref_func = staticmethod(_capi.libei.seat_unref)
 
     def __repr__(self) -> str:
+        """The seat's name and capabilities."""
         caps = "|".join(c.name or str(c.value) for c in self.capabilities)
         return f"<Seat {self.name!r} {caps}>"
 
@@ -774,6 +780,7 @@ class Ping(CObject):
     _unref_func = staticmethod(_capi.libei.ping_unref)
 
     def __repr__(self) -> str:
+        """The ping's id, which is all a ping carries."""
         return f"<Ping {self.id}>"
 
     @property
@@ -801,6 +808,7 @@ class Event(CObject):
     _unref_func = staticmethod(_capi.libei.event_unref)
 
     def __repr__(self) -> str:
+        """The event type by name, or the raw value for one we do not model."""
         event_type = self.event_type
         label = event_type.name if isinstance(event_type, EventType) else event_type
         return f"<Event {label}>"
@@ -1008,6 +1016,11 @@ class Event(CObject):
 
 
 def _log_callback(_ei: int, priority: int, message: bytes, _context: int) -> None:
+    """Forward libei's log lines into the logging module.
+
+    Runs inside a ctypes callback, where an exception is printed to stderr
+    and then dropped, so every lookup below falls back rather than raising.
+    """
     # Look up the raw int, not _LogPriority(priority): constructing the
     # enum from an unrecognized value raises ValueError immediately, which
     # would happen *before* .get()'s default ever gets a chance to apply
@@ -1227,6 +1240,7 @@ class Sender(Context):
 
     @classmethod
     def _new(cls) -> int:
+        """A new sender from the C library, or an error if it returned NULL."""
         pointer = _capi.libei.new_sender(c_void_p(None))
         if not pointer:
             raise Error("ei_new_sender() returned NULL")
@@ -1250,6 +1264,7 @@ class Receiver(Context):
 
     @classmethod
     def _new(cls) -> int:
+        """A new receiver from the C library, or an error if it returned NULL."""
         pointer = _capi.libei.new_receiver(c_void_p(None))
         if not pointer:
             raise Error("ei_new_receiver() returned NULL")
@@ -1280,6 +1295,10 @@ __all__ = [
     "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",

{python_libei-0.5.2 → python_libei-0.6.0}/src/libei/eis.py

@@ -159,6 +159,8 @@ class Flag(enum.IntEnum):
 
 
 class _LogPriority(enum.IntEnum):
+    """The log levels, as the integers libeis passes to its log handler."""
+
     DEBUG = 10
     INFO = 20
     WARNING = 30
@@ -456,6 +458,7 @@ class Device(CObject):
     _unref_func = staticmethod(_capi.libeis.device_unref)
 
     def __repr__(self) -> str:
+        """Name, device type and capabilities -- what tells two devices apart."""
         caps = "|".join(c.name or str(c.value) for c in self.capabilities)
         return f"<Device {self.name!r} {self.device_type.name} {caps}>"
 
@@ -709,6 +712,7 @@ class Seat(CObject):
     _unref_func = staticmethod(_capi.libeis.seat_unref)
 
     def __repr__(self) -> str:
+        """The seat's name and capabilities."""
         caps = "|".join(c.name or str(c.value) for c in self.capabilities)
         return f"<Seat {self.name!r} {caps}>"
 
@@ -770,6 +774,7 @@ class Client(CObject):
     _unref_func = staticmethod(_capi.libeis.client_unref)
 
     def __repr__(self) -> str:
+        """The client's name and which side of the protocol it is on."""
         return f"<Client {self.name!r} sender={self.is_sender}>"
 
     @property
@@ -840,6 +845,7 @@ class Ping(CObject):
     _unref_func = staticmethod(_capi.libeis.ping_unref)
 
     def __repr__(self) -> str:
+        """The ping's id, which is all a ping carries."""
         return f"<Ping {self.id}>"
 
     @property
@@ -867,6 +873,7 @@ class Event(CObject):
     _unref_func = staticmethod(_capi.libeis.event_unref)
 
     def __repr__(self) -> str:
+        """The event type by name, or the raw value for one we do not model."""
         event_type = self.event_type
         label = event_type.name if isinstance(event_type, EventType) else event_type
         return f"<Event {label}>"
@@ -1079,6 +1086,11 @@ class Event(CObject):
 
 
 def _log_callback(_eis: int, priority: int, message: bytes, _context: int) -> None:
+    """Forward libeis's log lines into the logging module.
+
+    The same constraint as ei.py's callback of that name: it runs inside a
+    ctypes callback, so it falls back rather than raising.
+    """
     # See ei.py's _log_callback: look up the raw int, not
     # _LogPriority(priority), which would raise ValueError before .get()'s
     # default could apply -- silently, since this runs inside a ctypes
@@ -1208,6 +1220,7 @@ class Eis(CObject):
 
     @classmethod
     def _new(cls) -> int:
+        """A new server from the C library, or an error if it returned NULL."""
         pointer = _capi.libeis.new(c_void_p(None))
         if not pointer:
             raise Error("eis_new() returned NULL")
@@ -1265,6 +1278,10 @@ __all__ = [
     "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",

{python_libei-0.5.2 → python_libei-0.6.0}/src/libei/oeffis.py

@@ -6,7 +6,7 @@ Negotiates an EIS connection through the
 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:
@@ -41,6 +41,7 @@ import logging
 import os
 
 from . import _capi
+from ._capi.loader import LibraryNotFoundError
 
 logger = logging.getLogger("libei.oeffis")
 
@@ -122,6 +123,11 @@ class Oeffis:
         self._state = _EventType.NONE
 
     def __del__(self) -> None:
+        """Release the session, closing the EIS fd if nobody claimed it.
+
+        Safe on a half-built object: __init__ can raise before every
+        attribute exists, and this still runs.
+        """
         # getattr() with defaults rather than plain attribute access:
         # __init__ raises DisconnectedError when oeffis_new() returns NULL,
         # and Python still calls __del__ on the half-built object, where
@@ -237,6 +243,11 @@ class Oeffis:
 __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",

{python_libei-0.5.2 → python_libei-0.6.0}/src/libei/portal.py

@@ -21,7 +21,7 @@ should be handled by an application talking to DBus directly"
 (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,
@@ -427,18 +427,21 @@ def _request(
         params: Any,
         *_a: Any,
     ) -> None:
+        """Record the first reply and quit the loop; later replies are ignored."""
         if result:  # both subscriptions may fire; the first reply wins
             return
         result["code"], result["results"] = params.unpack()
         loop.quit()
 
     def on_timeout() -> bool:
+        """Stop the loop and record that it timed out rather than finished."""
         nonlocal timed_out
         timed_out = True
         loop.quit()
         return False  # one-shot; GLib removes the source when this is False
 
     def subscribe(path: str) -> None:
+        """Subscribe to Response on one path, keeping the handle alive."""
         subscriptions.append(
             connection.signal_subscribe(
                 busname,
@@ -685,12 +688,20 @@ class RemoteDesktopSession:
             self._connection = None
 
     def __enter__(self) -> RemoteDesktopSession:
+        """Return self: entering performs no action of its own."""
         return self
 
     def __exit__(self, *_exc: Any) -> None:
+        """Close the session on the way out, whatever happened."""
         self.close()
 
     def __del__(self) -> None:
+        """Close the fd only: __del__ can run during interpreter shutdown.
+
+        A synchronous D-Bus round trip there may hang or fail with nothing
+        left able to report it, so the D-Bus half of close() is deliberately
+        not attempted.
+        """
         # Deliberately only the fd, not the D-Bus half of close(): __del__
         # can run during interpreter shutdown, where a synchronous D-Bus
         # round trip may hang or fail in ways nothing can report. Closing an
@@ -1037,6 +1048,7 @@ def _wait_for_signal(
         params: Any,
         *_a: Any,
     ) -> None:
+        """Record the first matching signal; anything else is logged and dropped."""
         if result:  # a subscription that outlives its own wait can fire twice
             return
         args = params.unpack()
@@ -1058,6 +1070,7 @@ def _wait_for_signal(
         loop.quit()
 
     def on_timeout() -> bool:
+        """Stop the loop and record that it timed out rather than finished."""
         nonlocal timed_out
         timed_out = True
         loop.quit()
@@ -1141,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
@@ -1487,12 +1500,15 @@ class InputCaptureSession:
             self._connection = None
 
     def __enter__(self) -> InputCaptureSession:
+        """Return self: entering performs no action of its own."""
         return self
 
     def __exit__(self, *_exc: Any) -> None:
+        """Close the session on the way out, whatever happened."""
         self.close()
 
     def __del__(self) -> None:
+        """Close the fd only, for the reason RemoteDesktopSession.__del__ gives."""
         # See RemoteDesktopSession.__del__ for why this closes only the fd.
         if getattr(self, "_eis_fd_claimed", True):
             return

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-libei
-Version: 0.5.2
+Version: 0.6.0
 Summary: Inject and receive input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis
 Author: Dennis K. Paulsen
 License-Expression: MIT
@@ -37,6 +37,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
@@ -103,11 +107,15 @@ 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`, `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
 
@@ -149,14 +157,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.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.
 
 The injection path is exercised end to end against the real libraries by the
@@ -394,8 +404,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.0}/tests/test_documentation_shape.py

@@ -9,16 +9,24 @@ that documentation defects still get caught in that environment.
 from __future__ import annotations
 
 import ast
+import importlib
 import re
 import textwrap
 from pathlib import Path
 
 import pytest
 
-from libei import ei, eis
+from libei import ei, eis, oeffis, portal
 
 _PROJECT_ROOT = Path(__file__).resolve().parent.parent
 _README = _PROJECT_ROOT / "README.md"
+_TROUBLESHOOTING = _PROJECT_ROOT / "docs" / "troubleshooting.md"
+
+# The modules a reader can import a public name from -- what the reference
+# pages name, and whose docstrings carry the examples worth checking.
+_PUBLIC_MODULES = ("libei.ei", "libei.eis", "libei.oeffis", "libei.portal")
+
+_EXCEPTION_HEADING = "## When it does raise: which name you are catching"
 
 
 def _readme_python_blocks() -> list[str]:
@@ -50,14 +58,22 @@ def test_readme_examples_are_valid_python() -> None:
             pytest.fail(f"README example is not valid Python ({exc}):\n{block}")
 
 
-@pytest.mark.parametrize("module", [ei, eis])
-def test_module_docstring_examples_are_valid_python(module: object) -> None:
+@pytest.mark.parametrize("module_name", _PUBLIC_MODULES)
+def test_module_docstring_examples_are_valid_python(module_name: str) -> None:
+    # Every module with an example has to write it as the ``::`` literal
+    # block the extractor reads, and the block has to parse. oeffis and
+    # portal wrote theirs as a plain indented block, so neither example was
+    # ever extracted here -- or evaluated as reST, where a literal block
+    # needs the marker.
+    module = importlib.import_module(module_name)
     source = _docstring_example(module.__doc__ or "")
-    assert source.strip(), f"{module.__name__} docstring has no example"  # type: ignore[attr-defined]
+    assert source.strip(), f"{module_name} docstring has no ``::`` example"
     try:
-        compile(source, f"<{module.__name__} docstring>", "exec")  # type: ignore[attr-defined]
+        compile(source, f"<{module_name} docstring>", "exec")
     except SyntaxError as exc:
-        pytest.fail(f"docstring example is not valid Python ({exc}):\n{source}")
+        pytest.fail(
+            f"{module_name} docstring example is not valid Python ({exc}):\n{source}"
+        )
 
 
 def _emulating_examples() -> list[str]:
@@ -295,8 +311,33 @@ def test_relative_links_point_at_something_that_exists() -> None:
             path = target.split("#", 1)[0]
             if not path:
                 continue
-            assert (page.parent / path).exists(), (
-                f"{page.name} links to {path}, which does not exist"
+            linked = page.parent / path
+            assert linked.exists(), f"{page.name} links to {path}, which does not exist"
+            if linked.is_dir():
+                # A directory is a page only where it has a README. Without one
+                # the link lands the reader on a file listing, which is what
+                # the README's own links to `docs/developers/` did until they
+                # named the two pages in it -- and `exists()` alone cannot tell
+                # the two apart.
+                assert (linked / "README.md").exists(), (
+                    f"{page.name} links to the directory {path}, which has no "
+                    "README to land on"
+                )
+
+
+def test_every_public_name_is_named_on_some_page() -> None:
+    # A name in a module's __all__ is its declared surface, and these pages are
+    # where a reader looks for it: three names were public and reached no page
+    # at all, so the only place to learn they existed was the source they are
+    # defined in. Read from __all__ rather than dir(), since what is being
+    # guarded is "declared public", not "happens to have an attribute".
+    text = "\n".join(
+        page.read_text(encoding="utf-8") for page in _documentation_pages()
+    )
+    for module in (ei, eis, oeffis, portal):
+        for name in module.__all__:
+            assert name in text, (
+                f"{module.__name__}.{name} is public but named on no page"
             )
 
 
@@ -314,12 +355,124 @@ def test_each_pages_own_contents_resolves() -> None:
             )
 
 
-def test_readme_status_names_the_current_version() -> None:
-    # The Status section states the version in prose; a bump that leaves it
-    # behind is how a README starts describing a release that no longer
-    # exists.
+@pytest.mark.parametrize("page", ["README.md", "docs/developers/verification.md"])
+def test_status_pages_name_the_current_version(page: str) -> None:
+    # Both state the version in prose, and nothing keeps them in step with
+    # pyproject.toml -- so a bump that touches one and not the other ships a
+    # page describing a release that no longer exists. The developers page
+    # sat a whole release behind exactly that way: 0.5.1 while
+    # pyproject.toml, libei.__version__ and the README all said 0.5.2.
     import libei
 
-    assert f"`{libei.__version__}`" in _README.read_text(), (
-        f"README does not mention the current version {libei.__version__}"
+    assert f"`{libei.__version__}`" in (_PROJECT_ROOT / page).read_text(), (
+        f"{page} does not mention the current version {libei.__version__}"
     )
+
+
+def _documented_exceptions() -> list[tuple[list[str], list[str]]]:
+    """The (modules, classes) of each row of the exception table.
+
+    Only the table under :data:`_EXCEPTION_HEADING` is read, so a table
+    added to that page elsewhere cannot quietly become part of this check.
+    """
+    _, _, after = _TROUBLESHOOTING.read_text().partition(_EXCEPTION_HEADING)
+    section = after.split("\n## ", 1)[0]
+    rows: list[tuple[list[str], list[str]]] = []
+    for line in section.splitlines():
+        if not line.startswith("|"):
+            continue
+        cells = [cell.strip() for cell in line.strip("|").split("|")]
+        if len(cells) < 2 or cells[0] in ("Module", "") or cells[0].strip("- ") == "":
+            continue
+        rows.append(
+            (
+                [name.strip(" `") for name in cells[0].split(",")],
+                [name.strip(" `") for name in cells[1].split(",")],
+            )
+        )
+    return rows
+
+
+def test_documented_exceptions_are_part_of_the_public_api() -> None:
+    # The page says which module to import each exception from, so each has
+    # to be part of that module's declared surface rather than an attribute
+    # it happens to carry. LibraryNotFoundError was importable from
+    # libei.ei and libei.eis but listed in neither __all__ -- which left the
+    # private libei._capi.loader as the only place it was obviously public.
+    rows = _documented_exceptions()
+    assert rows, "no exception table found in docs/troubleshooting.md"
+    for modules, classes in rows:
+        for class_name in classes:
+            found: dict[str, object] = {}
+            for module_name in modules:
+                module = importlib.import_module(module_name)
+                assert hasattr(module, class_name), f"{module_name} has no {class_name}"
+                assert class_name in module.__all__, (
+                    f"{module_name}.{class_name} is documented as importable from "
+                    "there, but is missing from that module's __all__"
+                )
+                found[module_name] = getattr(module, class_name)
+            # A row may name two modules for one class, and Error is a
+            # separate class on each side -- so a shared row is the only
+            # thing that has to resolve to one object.
+            assert len({id(cls) for cls in found.values()}) == 1, (
+                f"the row for {class_name} names {modules}, which do not agree "
+                "on what that class is"
+            )
+
+
+@pytest.mark.parametrize("module_name", _PUBLIC_MODULES)
+def test_public_api_is_documented(module_name: str) -> None:
+    # The package ships py.typed and is meant to be consumed as a
+    # dependency, so every public callable needs at least a one-line
+    # docstring. This started at 3/64 and 6/74. It reads source text and
+    # needs nothing installed, so it belongs here rather than in
+    # test_documented_examples.py, whose module-level `integration` mark
+    # skipped it on exactly the machines where it was cheapest to run.
+    module = importlib.import_module(module_name)
+    source_path = module.__file__
+    assert source_path is not None, f"{module_name} has no source file to read"
+    tree = ast.parse(Path(source_path).read_text())
+    undocumented = [
+        node.name
+        for node in ast.walk(tree)
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef))
+        and not node.name.startswith("_")
+        and not ast.get_docstring(node)
+    ]
+    assert not undocumented, (
+        f"{module_name} has undocumented public definitions: "
+        f"{sorted(set(undocumented))}"
+    )
+
+
+# A role whose name starts on the next line renders as literal text wherever
+# the docstring is read, and so does everything after an unpaired backtick.
+_SPLIT_ROLE = re.compile(r":(class|meth|attr|func|mod|data|exc):`[^`\n]*\n")
+
+
+def _docstrings(module_name: str) -> list[tuple[str, str]]:
+    """The (where, docstring) of a module and every definition inside it."""
+    module = importlib.import_module(module_name)
+    source_path = module.__file__
+    assert source_path is not None, f"{module_name} has no source file to read"
+    tree = ast.parse(Path(source_path).read_text())
+    found = [("<module>", ast.get_docstring(tree) or "")]
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            found.append((node.name, ast.get_docstring(node) or ""))
+    return found
+
+
+@pytest.mark.parametrize("module_name", _PUBLIC_MODULES)
+def test_docstrings_have_no_broken_markup(module_name: str) -> None:
+    # Neither defect shows up anywhere except in the rendered text: portal.py
+    # read ":meth:`enable` and :meth:`" and broke the line before
+    # "wait_for_activation`", so the second name never became a link, and a
+    # docstring with an unpaired backtick silently swallows the rest of it.
+    for where, doc in _docstrings(module_name):
+        if _SPLIT_ROLE.search(doc) is not None:
+            pytest.fail(f"{module_name}:{where} breaks a role across a line break")
+        assert doc.count("`") % 2 == 0, (
+            f"{module_name}:{where} has an unpaired backtick"
+        )

{python_libei-0.5.2 → python_libei-0.6.0}/tests/test_documented_examples.py

@@ -90,30 +90,3 @@ def test_ei_module_docstring_example_runs() -> None:
         ei.Context.dispatch = original_dispatch  # type: ignore[method-assign]
 
     assert namespace["device"] is not None
-
-
-@pytest.mark.parametrize("module", [ei, eis, "oeffis"])
-def test_public_api_is_documented(module: object) -> None:
-    # The package ships py.typed and is meant to be consumed as a
-    # dependency, so every public callable needs at least a one-line
-    # docstring. This started at 3/64 and 6/74.
-    import ast
-    import importlib
-
-    if isinstance(module, str):
-        module = importlib.import_module(f"libei.{module}")
-
-    source = Path(module.__file__).read_text()  # type: ignore[attr-defined]
-    tree = ast.parse(source)
-
-    undocumented = [
-        node.name
-        for node in ast.walk(tree)
-        if isinstance(node, ast.FunctionDef)
-        and not node.name.startswith("_")
-        and not ast.get_docstring(node)
-    ]
-    assert not undocumented, (
-        f"{module.__name__} has undocumented public callables: "  # type: ignore[attr-defined]
-        f"{sorted(set(undocumented))}"
-    )

{python_libei-0.5.2 → python_libei-0.6.0}/tests/test_portal.py

@@ -489,6 +489,20 @@ def test_explicit_all_devices_is_translated_too() -> None:
     assert select[1][-1]["types"].value != 0
 
 
+def test_create_session_carries_a_session_handle_token() -> None:
+    # Omitting it crashes xdg-desktop-portal 1.22.1 outright -- SIGABRT,
+    # "assertion failed: (session->token != NULL)" -- and it is a *different*
+    # token from the handle_token _request() injects on its own, so a
+    # CreateSession that carries one and not the other still looks right.
+    connection = FakeConnection()
+    with install_fake_gi(connection):
+        portal.RemoteDesktopSession.negotiate(connection=connection)
+    create = next(c for c in connection.calls if c[0] == "CreateSession")
+    options = create[1][-1]
+    assert options["session_handle_token"].value
+    assert options["handle_token"].value
+
+
 def test_restore_token_without_persist_mode_is_refused() -> None:
     # The portal consumes a restore token on use and only mints a new one
     # when persistence was asked for, so this combination would spend the