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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-libei
-Version: 0.5.1
+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.1`), 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
@@ -187,11 +197,11 @@ Exactly what was run, when, and against which versions:
   portal paths are the part likeliest to come up short off Linux, since
   they need an xdg-desktop-portal RemoteDesktop backend to talk to.
 - CPython 3.10 or newer (tested on 3.13)
-- The native libraries: on Fedora, `sudo dnf install libei libeis liboeffis`;
-  on FreeBSD, `pkg install libei` (the `x11/libei` port), which supplies all
-  three sonames including `liboeffis`
-- `libei.portal` only: PyGObject (`pip install 'python-libei[portal]'`), plus
-  whatever GObject-introspection libraries your distro needs for `Gio` --
+- The native `libei`, `libeis` and `liboeffis` libraries, which `pip` cannot
+  supply. Which package provides them on your distribution — and what to do
+  when the name does not match — is in [docs/install.md](docs/install.md).
+- `libei.portal` only: PyGObject, via the `portal` extra, plus whatever
+  GObject-introspection libraries your distribution needs for `Gio`, since
   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
@@ -224,22 +234,11 @@ Exactly what was run, when, and against which versions:
 
 ## Install
 
-From [PyPI](https://pypi.org/project/python-libei/):
-
 ```sh
 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:
+From a checkout instead, to track `main` or to work on the package:
 
 ```sh
 git clone https://github.com/ctrondlp/python-libei.git
@@ -247,15 +246,11 @@ 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:
-
-```python
-from libei import ei
-
-if not ei.is_available():
-    ...  # fall back to another input backend
-```
+That is the half `pip` can do. The native `libei`/`libeis`/`liboeffis`
+libraries it cannot supply, the `portal` extra, and how to check what actually
+loaded are all in [docs/install.md](docs/install.md) — see
+[Requirements](#requirements) above for the version floors. Importing is safe
+without any of it: those libraries are loaded on first *use*, not at import.
 
 ## Concepts
 
@@ -409,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.1 → 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.1`), 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
@@ -150,11 +160,11 @@ Exactly what was run, when, and against which versions:
   portal paths are the part likeliest to come up short off Linux, since
   they need an xdg-desktop-portal RemoteDesktop backend to talk to.
 - CPython 3.10 or newer (tested on 3.13)
-- The native libraries: on Fedora, `sudo dnf install libei libeis liboeffis`;
-  on FreeBSD, `pkg install libei` (the `x11/libei` port), which supplies all
-  three sonames including `liboeffis`
-- `libei.portal` only: PyGObject (`pip install 'python-libei[portal]'`), plus
-  whatever GObject-introspection libraries your distro needs for `Gio` --
+- The native `libei`, `libeis` and `liboeffis` libraries, which `pip` cannot
+  supply. Which package provides them on your distribution — and what to do
+  when the name does not match — is in [docs/install.md](docs/install.md).
+- `libei.portal` only: PyGObject, via the `portal` extra, plus whatever
+  GObject-introspection libraries your distribution needs for `Gio`, since
   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
@@ -187,22 +197,11 @@ Exactly what was run, when, and against which versions:
 
 ## Install
 
-From [PyPI](https://pypi.org/project/python-libei/):
-
 ```sh
 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:
+From a checkout instead, to track `main` or to work on the package:
 
 ```sh
 git clone https://github.com/ctrondlp/python-libei.git
@@ -210,15 +209,11 @@ 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:
-
-```python
-from libei import ei
-
-if not ei.is_available():
-    ...  # fall back to another input backend
-```
+That is the half `pip` can do. The native `libei`/`libeis`/`liboeffis`
+libraries it cannot supply, the `portal` extra, and how to check what actually
+loaded are all in [docs/install.md](docs/install.md) — see
+[Requirements](#requirements) above for the version floors. Importing is safe
+without any of it: those libraries are loaded on first *use*, not at import.
 
 ## Concepts
 
@@ -372,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.1 → python_libei-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-libei"
-version = "0.5.1"
+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",
 ]
@@ -87,8 +95,39 @@ select = [
     "E", "W",   # pycodestyle
     "F",        # pyflakes
     "I",        # isort
-    "UP",       # pyupgrade
+    "D",        # pydocstyle
     "B",        # bugbear
+    "UP",       # pyupgrade
+    "C4",       # comprehensions
+    "SIM",      # simplification
+    "RET",      # return consistency
+    "ARG",      # unused arguments
+    "C901",     # cyclomatic complexity
+]
+ignore = [
+    "D203",    # incompatible with D211; keep no blank line before class docstring
+    "D213",    # incompatible with D212; keep the summary on the first line
+    "D401",    # properties read better as noun phrases than imperatives
+    "D105",    # __enter__/__exit__ and friends document themselves
+]
+
+[tool.ruff.lint.mccabe]
+# pyguitest's ceiling; python-libei's own worst case (InputCaptureSession.
+# negotiate(), forking on portal version) sits at 14, just under it. A
+# ceiling on what gets added, not a claim everything else is close to it.
+max-complexity = 15
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[tool.ruff.lint.per-file-ignores]
+# Tests use fakes with deliberately unused arguments and multi-with blocks
+# that read better nested; matching pyguitest's/pyguitest-recorder's own
+# per-file-ignores for the same reasons.
+"tests/*" = [
+    "ARG001", "ARG002", "ARG003", "ARG005",  # fakes accept arguments they ignore
+    "SIM117",                      # nested with-blocks read better in tests
+    "D100", "D101", "D102", "D103", "D104", "D107",
 ]
 
 [tool.mypy]

{python_libei-0.5.1 → 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.1"
+__version__ = "0.6.0"
 
 __all__ = ["__version__"]

python_libei-0.6.0/src/libei/_capi/__init__.py

@@ -0,0 +1,9 @@
+"""Low-level ctypes bindings.
+
+Not part of the public API -- use ``libei.ei``, ``libei.eis`` and
+``libei.oeffis`` instead.
+"""
+
+from . import libei, libeis, liboeffis
+
+__all__ = ["libei", "libeis", "liboeffis"]

{python_libei-0.5.1 → 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.1 → 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