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
34 changes: 33 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,10 @@ jobs:
PY

- run: ruff check src tests
# Checked, not applied. pyguitest and pyguitest-recorder both gate on
# formatting; this repo's config had never asked for it, so an
# unformatted file could land here and in neither of the others.
- run: ruff format --check src tests
- run: python -m mypy
# -rs so the log names every skip: on an older libei the version-gated
# tests skip, and which ones did is the interesting part of the run.
Expand Down Expand Up @@ -88,7 +92,35 @@ jobs:
python-version: "3.13"
- run: pip install build twine
- run: python -m build
- run: python -m twine check dist/*

# A PyPI version number can never be reused, so a tag disagreeing with
# the packaged version has to fail here rather than ship. Read back out
# of the built artifact, not out of the source, so it checks what would
# actually be uploaded. Skipped on branch pushes, where there is no tag.
#
# This repo needed it more than either sibling, which both had it
# already: 0.5.2 came about because eleven commits had accumulated past
# v0.5.1 -- including the InputCapture signal fix -- with nothing
# anywhere able to notice the released number had stopped describing
# the tree. Porting their step is what closes that.
- name: Check the tag matches the packaged version
if: startsWith(github.ref, 'refs/tags/v')
run: |
set -eu
tag="${GITHUB_REF_NAME#v}"
built=$(ls dist/*.tar.gz | sed -E 's|.*/python_libei-(.+)\.tar\.gz|\1|')
echo "tag=$tag packaged=$built"
if [ "$tag" != "$built" ]; then
echo "::error::tag $GITHUB_REF_NAME does not match the packaged"
echo "::error::version $built -- fix the version in"
echo "::error::pyproject.toml or retag."
exit 1
fi

# Strict, like its two siblings: catches a README that renders on GitHub
# but not on PyPI, which is otherwise only discovered once the upload is
# already permanent. Measured green on 0.5.2's artifacts before enabling.
- run: python -m twine check --strict dist/*

# Handed to the publish job below rather than rebuilt there, so what
# reaches PyPI is byte-for-byte what twine just checked.
Expand Down
30 changes: 24 additions & 6 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,19 @@ 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]
## [0.5.2] - 2026-09-12

### Added

- **`docs/install.md`**, a page for the half `pip` cannot do: the native
`libei`/`libeis`/`liboeffis` libraries, which distribution provides them
under which name, and the optional `[portal]` extra. The same information
was spread across two README sections, and `troubleshooting.md` carried a
Fedora-only `dnf` line with nothing to say for anyone else. Package names
are listed only for the families they have actually been checked against —
Fedora, Debian/Ubuntu (both exercised by this repo's own CI) and FreeBSD —
with the rest pointed at the name to search for rather than a guess, which
is the standard `hints.py` in pyguitest holds itself to as well.

### Changed

Expand All @@ -20,6 +32,12 @@ All notable changes to python-libei are recorded here. The format follows
`KeyEvent.key` is a Linux `KEY_*` code, matching `Device.keyboard_key()`)
since that wasn't stated on the class itself.

- **CI now runs `ruff format --check`**, which this repo had never asked for,
though pyguitest and pyguitest-recorder both gate on it. The tree was
already formatted, so this is a guard rather than a cleanup — and it is the
one repo of the three where formatting could previously have drifted in
unnoticed.

### Fixed

- **`InputCaptureSession.wait_for_activation()`/`wait_for_deactivation()`
Expand Down Expand Up @@ -116,10 +134,10 @@ All notable changes to python-libei are recorded here. The format follows

**Never run against a real portal**, unlike every other class in this
module -- see the class's own docstring for why: verifying it needs a
human to click through the consent dialog *and* accept that their pointer
will be exclusively diverted from their own desktop for the length of the
test, not something to trigger without asking first. Designed against the
shipped portal spec
developer to click through the consent dialog *and* accept that their
pointer will be exclusively diverted from their own desktop for the
length of the test, not something to trigger without asking first.
Designed against the shipped portal spec
(`/usr/share/dbus-1/interfaces/org.freedesktop.portal.InputCapture.xml`),
not just the header, and unit-tested against a fake connection
reproducing that spec's documented shapes -- see `tests/
Expand Down Expand Up @@ -217,7 +235,7 @@ All notable changes to python-libei are recorded here. The format follows
the session with it — so a process that retried after a declined,
timed-out or interrupted consent dialog accumulated live sessions inside
xdg-desktop-portal. `negotiate()` now closes the session on the way out,
including on `KeyboardInterrupt`: `Start` blocks on a human answering a
including on `KeyboardInterrupt`: `Start` blocks on a user answering a
dialog, so Ctrl-C during that wait is a routine exit and strands an
approved session exactly as a decline does.

Expand Down
32 changes: 25 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,15 +14,33 @@ pip install -e '.[dev]'
## Lint, types, tests

```sh
ruff check src tests
python -m mypy

pytest # everything; the integration tests below
# skip themselves if libei/libeis is absent
pytest -m integration # only the tests that drive the real libraries
pytest -rs # ...and report which tests skipped, and why
./scripts/pre-commit-test.sh
```

That is the gate — `scripts/pre-commit-test.sh` — and the only list of
commands worth keeping in your head: the four commands of CI's `test` job, in
CI's order and over CI's paths, with a pass/fail summary and a non-zero exit
when anything failed.

`--full` adds CI's `build` job so far as it is checkable here: the sdist and
wheel built into a temporary directory, `twine check --strict` over them, and
the tag-matches-the-packaged-version check when HEAD is a `v*` tag. An
interpreter without the build and twine packages reports SKIP, not a pass.
`-k NAME` narrows to the checks matching a name, `-v` streams output, `-q`
prints the summary only, `-x` stops at the first failure, and `--help` lists
them. It checks the working tree, not the index.

Run it with the dev extra installed in the interpreter it points at
(`PYTHON=...` to point it elsewhere). The two CI steps it deliberately leaves
out describe the runner rather than the tree: `pip install -e '.[dev]'` and
the apt packages.

It also reports which of libei/libeis/liboeffis that interpreter can load,
and the summary names every skip — the interesting part of a run against an
older libei, since a suite that ran with a third of its tests skipped is not
the same green as one that ran them all. `pytest -m integration` is still the
way to drive only the tests that negotiate with the real libraries.

Tests for a feature the installed libei is too old to provide skip themselves
by checking for the symbol before they negotiate anything —
`tests/conftest.py`'s `requires_symbol()`. Checking up front rather than
Expand Down
39 changes: 12 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ and why, is in

## Status

Beta (`0.5.1`), published on [PyPI](https://pypi.org/project/python-libei/)
Beta (`0.5.2`), 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
Expand Down Expand Up @@ -150,11 +150,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
Expand Down Expand Up @@ -187,38 +187,23 @@ 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
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

Expand Down
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ the [project README](../README.md).

| File | What's in it |
|------|---------------|
| [install.md](install.md) | The Python package, the native libraries per distribution, the optional `portal` extra, and how to check what actually loaded |
| [getting-started.md](getting-started.md) | Install through a first pointer motion on a real desktop, and the one concept (`frame()`) everything depends on |
| [recipes.md](recipes.md) | Keyboards, touch, absolute positioning, consent persistence, receiver mode, running your own EIS server |
| [troubleshooting.md](troubleshooting.md) | The "when nothing happens" checklist — nearly every failure in libei is silent |
Expand Down
11 changes: 6 additions & 5 deletions docs/developers/verification.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,11 +46,12 @@ By hand:

**The capture half remains unverified**, and unlike the rest of
`libei.portal` its consent dialog is not the whole reason why. Approving a
capture exclusively diverts the approving human's own pointer, keyboard or
touch input away from their desktop for as long as it stays active, so
verifying `set_pointer_barriers()` / `enable()` / `wait_for_activation()`
needs someone to deliberately accept that, not merely click through a
permission prompt. Those were designed against the shipped D-Bus spec
capture exclusively diverts the approving developer's own pointer,
keyboard or touch input away from their desktop for as long as it stays
active, so verifying `set_pointer_barriers()` / `enable()` /
`wait_for_activation()` needs someone to deliberately accept that, not
merely click through a permission prompt.
Those were designed against the shipped D-Bus spec
(`/usr/share/dbus-1/interfaces/org.freedesktop.portal.InputCapture.xml`)
and unit-tested against a fake connection reproducing its documented shapes
(`tests/test_inputcapture.py`) instead.
Expand Down
8 changes: 3 additions & 5 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,9 @@ pip install python-libei

Pure Python, no build step — ctypes talks to the native libraries directly, so
there is no compiler and no `libei-devel` involved. What `pip` does *not*
bring is the native libraries themselves:

```sh
sudo dnf install libei libeis liboeffis # Fedora
```
bring is the native libraries themselves; on Fedora that is `sudo dnf install
libei libeis liboeffis`, and the name for every other distribution is in
[install.md](install.md).

The distribution is named `python-libei`, the import is `libei` — so
`pip show python-libei`, but `from libei import ei`.
Expand Down
83 changes: 83 additions & 0 deletions docs/install.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
# Installing

Two halves, and `pip` only does the first.

## 1. The Python package

```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.

The `portal` extra adds PyGObject, which `libei.portal` needs and the other
three modules do not:

```sh
pip install 'python-libei[portal]'
```

To track `main` instead, or to work on the package itself, install from a
checkout:

```sh
git clone https://github.com/ctrondlp/python-libei.git
cd python-libei
pip install . # or: pip install -e '.[dev]' to develop
```

## 2. The native libraries

Nothing on PyPI provides these and `pip` cannot install them. The package
still imports without them — they are loaded on first *use*, not at import
(see `src/libei/_capi/loader.py`) — but every call then raises
`LibraryNotFoundError` naming the symbol it wanted.

| Distribution | Install |
| --- | --- |
| Fedora | `sudo dnf install libei libeis liboeffis` |
| Debian, Ubuntu | `sudo apt install libei1 libeis1 liboeffis1` |
| FreeBSD | `sudo pkg install libei` — the `x11/libei` port, which supplies all three sonames including `liboeffis` |

Those three are the families whose names have actually been checked: Fedora
and FreeBSD from a real install, and Debian from what this repository's own CI
installs. CI deliberately runs against Ubuntu's libei 1.2.1 rather than a
current build, so the 1.0.0 floor is exercised on a genuinely old library.

**On any other distribution the name varies** — the three sonames may be split
across separate packages, or bundled under one. Search rather than assume; on
Arch that is `pacman -Ss libei`.

## 3. Checking what you have

```python
from libei import ei, eis, oeffis

print(ei.is_available(), eis.is_available(), oeffis.is_available())
```

`is_available()` reports whether the *library* loaded, which is not the same
question as whether the import worked — so an application can import this
package, discover the libraries are missing, and fall back to another input
backend without ever handling `ImportError`.

## 4. Which libei version

1.0.0 is the floor, and newer buys specific features rather than a different
API: the full table is in the README's
[Requirements](../README.md#requirements). Because nothing is resolved until
it is called, a library too old for one call costs you that call — it raises
`LibraryNotFoundError` naming the symbol — and not the rest of the package.

## Where to go next

| If you want… | Read |
|---|---|
| A first pointer motion on a real desktop | [getting-started.md](getting-started.md) |
| Something silently does nothing | [troubleshooting.md](troubleshooting.md) |
| Which module to use for what | the README's [Which API do I need?](../README.md#which-api-do-i-need) |
2 changes: 1 addition & 1 deletion docs/recipes.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ Three differences from `Oeffis` worth knowing:
`GLib.MainLoop` per D-Bus round trip and returns only once connected, or
raises `PortalVersionError` / `PortalDeniedError` / `PortalTimeoutError`.
- **Bounded.** Each round trip gets `timeout` seconds (60 by default —
generous, since `Start` waits on a human answering a dialog). Without it a
generous, since `Start` waits on a user answering a dialog). Without it a
portal that dies after accepting the call would wedge the calling thread
forever, which is the one thing `Oeffis`'s pollable fd protects against.
- **Close it.** The portal session lives in xdg-desktop-portal and outlives
Expand Down
5 changes: 3 additions & 2 deletions docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,8 +71,9 @@ Work down it in order. The first three account for most cases.
## `LibraryNotFoundError`

The native library is not installed, or is too old to export a function this
package binds. Check with `ei.is_available()`; install with
`sudo dnf install libei libeis liboeffis` on Fedora.
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).

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
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

[project]
name = "python-libei"
version = "0.5.1"
version = "0.5.2"
description = "Inject and receive input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis"
readme = "README.md"
license = "MIT"
Expand Down
Loading
Loading