Skip to content

Commit 379ccc0

Browse files
authored
Merge pull request #7 from ctrondlp/P2-docs-tests-link-and-anchor-checks
docs: add an install page for the native libraries and check doc link…
2 parents 50a1682 + 7184350 commit 379ccc0

17 files changed

Lines changed: 573 additions & 69 deletions

‎.github/workflows/ci.yml‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,10 @@ jobs:
5252
PY
5353
5454
- run: ruff check src tests
55+
# Checked, not applied. pyguitest and pyguitest-recorder both gate on
56+
# formatting; this repo's config had never asked for it, so an
57+
# unformatted file could land here and in neither of the others.
58+
- run: ruff format --check src tests
5559
- run: python -m mypy
5660
# -rs so the log names every skip: on an older libei the version-gated
5761
# tests skip, and which ones did is the interesting part of the run.
@@ -88,7 +92,35 @@ jobs:
8892
python-version: "3.13"
8993
- run: pip install build twine
9094
- run: python -m build
91-
- run: python -m twine check dist/*
95+
96+
# A PyPI version number can never be reused, so a tag disagreeing with
97+
# the packaged version has to fail here rather than ship. Read back out
98+
# of the built artifact, not out of the source, so it checks what would
99+
# actually be uploaded. Skipped on branch pushes, where there is no tag.
100+
#
101+
# This repo needed it more than either sibling, which both had it
102+
# already: 0.5.2 came about because eleven commits had accumulated past
103+
# v0.5.1 -- including the InputCapture signal fix -- with nothing
104+
# anywhere able to notice the released number had stopped describing
105+
# the tree. Porting their step is what closes that.
106+
- name: Check the tag matches the packaged version
107+
if: startsWith(github.ref, 'refs/tags/v')
108+
run: |
109+
set -eu
110+
tag="${GITHUB_REF_NAME#v}"
111+
built=$(ls dist/*.tar.gz | sed -E 's|.*/python_libei-(.+)\.tar\.gz|\1|')
112+
echo "tag=$tag packaged=$built"
113+
if [ "$tag" != "$built" ]; then
114+
echo "::error::tag $GITHUB_REF_NAME does not match the packaged"
115+
echo "::error::version $built -- fix the version in"
116+
echo "::error::pyproject.toml or retag."
117+
exit 1
118+
fi
119+
120+
# Strict, like its two siblings: catches a README that renders on GitHub
121+
# but not on PyPI, which is otherwise only discovered once the upload is
122+
# already permanent. Measured green on 0.5.2's artifacts before enabling.
123+
- run: python -m twine check --strict dist/*
92124

93125
# Handed to the publish job below rather than rebuilt there, so what
94126
# reaches PyPI is byte-for-byte what twine just checked.

‎CHANGELOG.md‎

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,19 @@ All notable changes to python-libei are recorded here. The format follows
55
[semantic versioning](https://semver.org/spec/v2.0.0.html) — with the usual
66
0.x caveat that the API may still change between minor versions.
77

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

1022
### Changed
1123

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

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

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

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

‎CONTRIBUTING.md‎

Lines changed: 25 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -14,15 +14,33 @@ pip install -e '.[dev]'
1414
## Lint, types, tests
1515

1616
```sh
17-
ruff check src tests
18-
python -m mypy
19-
20-
pytest # everything; the integration tests below
21-
# skip themselves if libei/libeis is absent
22-
pytest -m integration # only the tests that drive the real libraries
23-
pytest -rs # ...and report which tests skipped, and why
17+
./scripts/pre-commit-test.sh
2418
```
2519

20+
That is the gate — `scripts/pre-commit-test.sh` — and the only list of
21+
commands worth keeping in your head: the four commands of CI's `test` job, in
22+
CI's order and over CI's paths, with a pass/fail summary and a non-zero exit
23+
when anything failed.
24+
25+
`--full` adds CI's `build` job so far as it is checkable here: the sdist and
26+
wheel built into a temporary directory, `twine check --strict` over them, and
27+
the tag-matches-the-packaged-version check when HEAD is a `v*` tag. An
28+
interpreter without the build and twine packages reports SKIP, not a pass.
29+
`-k NAME` narrows to the checks matching a name, `-v` streams output, `-q`
30+
prints the summary only, `-x` stops at the first failure, and `--help` lists
31+
them. It checks the working tree, not the index.
32+
33+
Run it with the dev extra installed in the interpreter it points at
34+
(`PYTHON=...` to point it elsewhere). The two CI steps it deliberately leaves
35+
out describe the runner rather than the tree: `pip install -e '.[dev]'` and
36+
the apt packages.
37+
38+
It also reports which of libei/libeis/liboeffis that interpreter can load,
39+
and the summary names every skip — the interesting part of a run against an
40+
older libei, since a suite that ran with a third of its tests skipped is not
41+
the same green as one that ran them all. `pytest -m integration` is still the
42+
way to drive only the tests that negotiate with the real libraries.
43+
2644
Tests for a feature the installed libei is too old to provide skip themselves
2745
by checking for the symbol before they negotiate anything —
2846
`tests/conftest.py`'s `requires_symbol()`. Checking up front rather than

‎README.md‎

Lines changed: 12 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ and why, is in
119119

120120
## Status
121121

122-
Beta (`0.5.1`), published on [PyPI](https://pypi.org/project/python-libei/)
122+
Beta (`0.5.2`), published on [PyPI](https://pypi.org/project/python-libei/)
123123
since `0.1.0`, and **the API is not frozen** — expect renames before 1.0.
124124

125125
The injection path is exercised end to end against the real libraries by the
@@ -150,11 +150,11 @@ Exactly what was run, when, and against which versions:
150150
portal paths are the part likeliest to come up short off Linux, since
151151
they need an xdg-desktop-portal RemoteDesktop backend to talk to.
152152
- CPython 3.10 or newer (tested on 3.13)
153-
- The native libraries: on Fedora, `sudo dnf install libei libeis liboeffis`;
154-
on FreeBSD, `pkg install libei` (the `x11/libei` port), which supplies all
155-
three sonames including `liboeffis`
156-
- `libei.portal` only: PyGObject (`pip install 'python-libei[portal]'`), plus
157-
whatever GObject-introspection libraries your distro needs for `Gio` --
153+
- The native `libei`, `libeis` and `liboeffis` libraries, which `pip` cannot
154+
supply. Which package provides them on your distribution — and what to do
155+
when the name does not match — is in [docs/install.md](docs/install.md).
156+
- `libei.portal` only: PyGObject, via the `portal` extra, plus whatever
157+
GObject-introspection libraries your distribution needs for `Gio`, since
158158
PyPI's PyGObject wheel supplies the Python side only. Not needed for
159159
`libei.ei`, `libei.eis` or `libei.oeffis`.
160160
- libei 1.0.0 or newer for the core: connecting, binding a seat, and
@@ -187,38 +187,23 @@ Exactly what was run, when, and against which versions:
187187

188188
## Install
189189

190-
From [PyPI](https://pypi.org/project/python-libei/):
191-
192190
```sh
193191
pip install python-libei
194192
```
195193

196-
The distribution is named `python-libei`, the import is `libei` -- so
197-
`pip show python-libei`, but `from libei import ei`.
198-
199-
Pure Python, no build step: the wheel is `py3-none-any` and ctypes talks to
200-
the native libraries directly, so there is no compiler, no headers and no
201-
`libei-devel` involved at install time. What `pip` does *not* bring is the
202-
native libraries themselves -- see [Requirements](#requirements) above; on
203-
Fedora, `sudo dnf install libei libeis liboeffis`.
204-
205-
To track `main` instead, or to hack on it, install from a checkout:
194+
From a checkout instead, to track `main` or to work on the package:
206195

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

213-
Importing is always safe, even where the native libraries are missing — they
214-
are loaded on first use, not at import. Check before you rely on them:
215-
216-
```python
217-
from libei import ei
218-
219-
if not ei.is_available():
220-
... # fall back to another input backend
221-
```
202+
That is the half `pip` can do. The native `libei`/`libeis`/`liboeffis`
203+
libraries it cannot supply, the `portal` extra, and how to check what actually
204+
loaded are all in [docs/install.md](docs/install.md) — see
205+
[Requirements](#requirements) above for the version floors. Importing is safe
206+
without any of it: those libraries are loaded on first *use*, not at import.
222207

223208
## Concepts
224209

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ the [project README](../README.md).
88

99
| File | What's in it |
1010
|------|---------------|
11+
| [install.md](install.md) | The Python package, the native libraries per distribution, the optional `portal` extra, and how to check what actually loaded |
1112
| [getting-started.md](getting-started.md) | Install through a first pointer motion on a real desktop, and the one concept (`frame()`) everything depends on |
1213
| [recipes.md](recipes.md) | Keyboards, touch, absolute positioning, consent persistence, receiver mode, running your own EIS server |
1314
| [troubleshooting.md](troubleshooting.md) | The "when nothing happens" checklist — nearly every failure in libei is silent |

‎docs/developers/verification.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -46,11 +46,12 @@ By hand:
4646

4747
**The capture half remains unverified**, and unlike the rest of
4848
`libei.portal` its consent dialog is not the whole reason why. Approving a
49-
capture exclusively diverts the approving human's own pointer, keyboard or
50-
touch input away from their desktop for as long as it stays active, so
51-
verifying `set_pointer_barriers()` / `enable()` / `wait_for_activation()`
52-
needs someone to deliberately accept that, not merely click through a
53-
permission prompt. Those were designed against the shipped D-Bus spec
49+
capture exclusively diverts the approving developer's own pointer,
50+
keyboard or touch input away from their desktop for as long as it stays
51+
active, so verifying `set_pointer_barriers()` / `enable()` /
52+
`wait_for_activation()` needs someone to deliberately accept that, not
53+
merely click through a permission prompt.
54+
Those were designed against the shipped D-Bus spec
5455
(`/usr/share/dbus-1/interfaces/org.freedesktop.portal.InputCapture.xml`)
5556
and unit-tested against a fake connection reproducing its documented shapes
5657
(`tests/test_inputcapture.py`) instead.

‎docs/getting-started.md‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,9 @@ pip install python-libei
1010

1111
Pure Python, no build step — ctypes talks to the native libraries directly, so
1212
there is no compiler and no `libei-devel` involved. What `pip` does *not*
13-
bring is the native libraries themselves:
14-
15-
```sh
16-
sudo dnf install libei libeis liboeffis # Fedora
17-
```
13+
bring is the native libraries themselves; on Fedora that is `sudo dnf install
14+
libei libeis liboeffis`, and the name for every other distribution is in
15+
[install.md](install.md).
1816

1917
The distribution is named `python-libei`, the import is `libei` — so
2018
`pip show python-libei`, but `from libei import ei`.

‎docs/install.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Installing
2+
3+
Two halves, and `pip` only does the first.
4+
5+
## 1. The Python package
6+
7+
```sh
8+
pip install python-libei
9+
```
10+
11+
The distribution is named `python-libei`; the import is `libei`. So `pip show
12+
python-libei`, but `from libei import ei`.
13+
14+
Pure Python, no build step: the wheel is `py3-none-any`, and ctypes talks to
15+
the native libraries directly, so there is no compiler, no headers and no
16+
`libei-devel` involved at install time.
17+
18+
The `portal` extra adds PyGObject, which `libei.portal` needs and the other
19+
three modules do not:
20+
21+
```sh
22+
pip install 'python-libei[portal]'
23+
```
24+
25+
To track `main` instead, or to work on the package itself, install from a
26+
checkout:
27+
28+
```sh
29+
git clone https://github.com/ctrondlp/python-libei.git
30+
cd python-libei
31+
pip install . # or: pip install -e '.[dev]' to develop
32+
```
33+
34+
## 2. The native libraries
35+
36+
Nothing on PyPI provides these and `pip` cannot install them. The package
37+
still imports without them — they are loaded on first *use*, not at import
38+
(see `src/libei/_capi/loader.py`) — but every call then raises
39+
`LibraryNotFoundError` naming the symbol it wanted.
40+
41+
| Distribution | Install |
42+
| --- | --- |
43+
| Fedora | `sudo dnf install libei libeis liboeffis` |
44+
| Debian, Ubuntu | `sudo apt install libei1 libeis1 liboeffis1` |
45+
| FreeBSD | `sudo pkg install libei` — the `x11/libei` port, which supplies all three sonames including `liboeffis` |
46+
47+
Those three are the families whose names have actually been checked: Fedora
48+
and FreeBSD from a real install, and Debian from what this repository's own CI
49+
installs. CI deliberately runs against Ubuntu's libei 1.2.1 rather than a
50+
current build, so the 1.0.0 floor is exercised on a genuinely old library.
51+
52+
**On any other distribution the name varies** — the three sonames may be split
53+
across separate packages, or bundled under one. Search rather than assume; on
54+
Arch that is `pacman -Ss libei`.
55+
56+
## 3. Checking what you have
57+
58+
```python
59+
from libei import ei, eis, oeffis
60+
61+
print(ei.is_available(), eis.is_available(), oeffis.is_available())
62+
```
63+
64+
`is_available()` reports whether the *library* loaded, which is not the same
65+
question as whether the import worked — so an application can import this
66+
package, discover the libraries are missing, and fall back to another input
67+
backend without ever handling `ImportError`.
68+
69+
## 4. Which libei version
70+
71+
1.0.0 is the floor, and newer buys specific features rather than a different
72+
API: the full table is in the README's
73+
[Requirements](../README.md#requirements). Because nothing is resolved until
74+
it is called, a library too old for one call costs you that call — it raises
75+
`LibraryNotFoundError` naming the symbol — and not the rest of the package.
76+
77+
## Where to go next
78+
79+
| If you want… | Read |
80+
|---|---|
81+
| A first pointer motion on a real desktop | [getting-started.md](getting-started.md) |
82+
| Something silently does nothing | [troubleshooting.md](troubleshooting.md) |
83+
| Which module to use for what | the README's [Which API do I need?](../README.md#which-api-do-i-need) |

‎docs/recipes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ Three differences from `Oeffis` worth knowing:
6464
`GLib.MainLoop` per D-Bus round trip and returns only once connected, or
6565
raises `PortalVersionError` / `PortalDeniedError` / `PortalTimeoutError`.
6666
- **Bounded.** Each round trip gets `timeout` seconds (60 by default —
67-
generous, since `Start` waits on a human answering a dialog). Without it a
67+
generous, since `Start` waits on a user answering a dialog). Without it a
6868
portal that dies after accepting the call would wedge the calling thread
6969
forever, which is the one thing `Oeffis`'s pollable fd protects against.
7070
- **Close it.** The portal session lives in xdg-desktop-portal and outlives

‎docs/troubleshooting.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,8 +71,9 @@ Work down it in order. The first three account for most cases.
7171
## `LibraryNotFoundError`
7272

7373
The native library is not installed, or is too old to export a function this
74-
package binds. Check with `ei.is_available()`; install with
75-
`sudo dnf install libei libeis liboeffis` on Fedora.
74+
package binds. Check with `ei.is_available()`; the package name for your
75+
distribution, and what to do when it does not match, is in
76+
[install.md](install.md).
7677

7778
Because loading is lazy, this is raised at the first *call*, not at import —
7879
so an application can import this package, discover the libraries are absent,

0 commit comments

Comments
 (0)