diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 120b008..a47ab51 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -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. @@ -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. diff --git a/CHANGELOG.md b/CHANGELOG.md index 8796273..1b3bb03 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 @@ -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()` @@ -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/ @@ -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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4f7e9dd..a9962c1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 diff --git a/README.md b/README.md index afd2f29..6b21764 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 @@ -187,22 +187,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 +199,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 diff --git a/docs/README.md b/docs/README.md index 02e6993..d133c91 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 | diff --git a/docs/developers/verification.md b/docs/developers/verification.md index 1d6ab36..8386acd 100644 --- a/docs/developers/verification.md +++ b/docs/developers/verification.md @@ -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. diff --git a/docs/getting-started.md b/docs/getting-started.md index 33b5c41..f7f5bf9 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -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`. diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..6a15a99 --- /dev/null +++ b/docs/install.md @@ -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) | diff --git a/docs/recipes.md b/docs/recipes.md index 709a332..981bc30 100644 --- a/docs/recipes.md +++ b/docs/recipes.md @@ -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 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index aec9ea2..726cd7c 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -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, diff --git a/pyproject.toml b/pyproject.toml index 6231bde..061e539 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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" diff --git a/scripts/pre-commit-test.sh b/scripts/pre-commit-test.sh new file mode 100755 index 0000000..2297b68 --- /dev/null +++ b/scripts/pre-commit-test.sh @@ -0,0 +1,312 @@ +#!/usr/bin/env bash +# Run python-libei's check suite -- tests, ruff lint, ruff format, mypy -- and +# report a pass/fail summary. Intended as the gate to clear before committing. +# +# The command list mirrors .github/workflows/ci.yml rather than inventing a +# house style, so a green run here means what CI means: the four commands of +# CI's `test` job, in CI's order, over CI's paths. What is deliberately not +# here are the parts of that job which describe the runner rather than the +# tree -- `pip install -e '.[dev]'` and the apt packages -- so run this with +# the dev extra installed in the interpreter it points at. +# +# It does report which of libei/libeis/liboeffis that interpreter can load. +# The integration tests skip themselves when the native libraries are absent, +# which is right on a machine without them; CI asserts at least libei and +# libeis are present, because on a runner a skipped test is a job that proved +# nothing. Here a skip is legitimate, so the libraries are printed rather than +# checked, and the skip count in the summary is worth reading for the same +# reason: a suite that ran with a third of its tests skipped is not the same +# green as one that ran them all. +# +# `--full` adds CI's `build` job, so far as it is checkable here: the sdist and +# wheel built into a temporary directory (CI's `python -m build` fills dist/; +# this writes nothing into the tree), `twine check --strict` over them, and -- +# when HEAD is exactly a v* tag -- the tag-matches-the-packaged-version check. +# An interpreter without the build and twine packages reports SKIP, not a pass. +# +# Not covered, deliberately: +# +# import-without-libei asserts importing works with *no* native libraries +# present -- the property the lazy loader exists to +# provide, and one that cannot be reproduced from a +# machine where they are installed. CI does it in an +# interpreter of its own, with nothing installed. +# publish runs on a v* tag and uploads to PyPI. Not a gate. +# +# Note it checks the working tree, not the index. If you have unstaged +# changes, that is not what `git commit` is about to record. +# +# Usage: +# ./scripts/pre-commit-test.sh run everything +# ./scripts/pre-commit-test.sh -k mypy only checks whose name matches (repeatable) +# ./scripts/pre-commit-test.sh -v stream each check's output as it runs +# ./scripts/pre-commit-test.sh -q summary only; do not dump failure logs +# ./scripts/pre-commit-test.sh -x stop at the first failure +# ./scripts/pre-commit-test.sh --full also build the sdist and wheel, +# twine-check them, and check the +# tag when HEAD is one +# +# Exit status: 0 all passed (a SKIP is not a pass, but is not a failure +# either), 1 one or more checks failed, 2 setup problem. + +set -uo pipefail + +# Repo root, not this script's own directory (scripts/): every check below runs +# `cd "$ROOT"`, and pyproject.toml/src/tests live one level up. +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +PYTHON="${PYTHON:-python3}" +RUFF="${RUFF:-ruff}" + +# name|command. Run from the repository root, via eval, so the quoting here is +# ordinary shell quoting. CI's `test` job, in CI's order. -rs so the summary +# names every skip, which is the interesting part of a run on an older libei. +CHECKS=( + "ruff|$RUFF check src tests" + "format|$RUFF format --check src tests" + "mypy|$PYTHON -m mypy" + "tests|$PYTHON -m pytest -q -rs" +) + +# name|command|guard|needs -- only with --full. The guard answers "are the +# tools here?" and is what turns a missing package into a SKIP instead of a +# failure; `needs` is what to name in the SKIP line. +FULL_CHECKS=( + "build|check_build|needs_build|the build and twine packages" +) + +# ---------------------------------------------------------------- arguments + +verbose=0 +quiet=0 +fail_fast=0 +full=0 +want_checks=() + +# The usage text is this script's own header: every comment line from line 2 +# down to the first line that is not one. Extracted by pattern rather than by +# line number, so adding a paragraph up there cannot silently truncate --help +# -- or leak the `set` line below into it. +usage() { + awk 'NR > 1 && !/^#/ { exit } NR > 1 { sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}" +} + +while (($#)); do + case "$1" in + -k|--check) [[ ${2:-} ]] || { echo "-k needs a value" >&2; exit 2; } + want_checks+=("$2"); shift 2 ;; + -v|--verbose) verbose=1; shift ;; + -q|--quiet) quiet=1; shift ;; + -x|--fail-fast) fail_fast=1; shift ;; + --full) full=1; shift ;; + -h|--help) usage; exit 0 ;; + *) echo "pre-commit-test.sh: unknown option '$1' (try --help)" >&2; exit 2 ;; + esac +done + +# ------------------------------------------------------------------ display + +if [[ -t 1 ]]; then + TTY=1 + BOLD=$'\033[1m'; DIM=$'\033[2m'; RED=$'\033[31m'; GREEN=$'\033[32m' + YELLOW=$'\033[33m'; RESET=$'\033[0m' +else + TTY=0 + BOLD=; DIM=; RED=; GREEN=; YELLOW=; RESET= +fi + +now() { date +%s.%N; } + +# ----------------------------------------------------------------- preflight + +matches() { # matches ; empty array matches all + local -n _pats="$1"; local val="$2" pat + ((${#_pats[@]} == 0)) && return 0 + for pat in "${_pats[@]}"; do [[ $val == *"$pat"* ]] && return 0; done + return 1 +} + +[[ -f "$ROOT/pyproject.toml" ]] || { + echo "pre-commit-test.sh: $ROOT does not look like the python-libei repo" >&2 + exit 2 +} + +missing=() +command -v "$PYTHON" >/dev/null || missing+=("$PYTHON") +command -v "$RUFF" >/dev/null || missing+=("$RUFF") +"$PYTHON" -c 'import pytest' 2>/dev/null || missing+=("pytest (for $PYTHON)") +"$PYTHON" -c 'import mypy' 2>/dev/null || missing+=("mypy (for $PYTHON)") +if ((${#missing[@]})); then + printf '%spre-commit-test.sh: not installed:%s %s\n' "$RED" "$RESET" "${missing[*]}" >&2 + echo "install with: pip install -e '.[dev]'" >&2 + exit 2 +fi + +LOGDIR="$(mktemp -d "${TMPDIR:-/tmp}/libei-checks.XXXXXX")" + +# Which native libraries the interpreter above can load, for the reason in the +# header. `src` on the path so this answers for the tree as it stands, whether +# or not the package is installed in editable mode -- the same reason CI sets +# PYTHONPATH there. One line per module, so a partial install is visible. +native="$(PYTHONPATH="src${PYTHONPATH:+:$PYTHONPATH}" "$PYTHON" -c ' +from libei import ei, eis, oeffis +print(", ".join(m.__name__ + (" yes" if m.is_available() else " no") + for m in (ei, eis, oeffis)))' 2>/dev/null)" || native= + +# --------------------------------------------------------------- full checks + +needs_build() { "$PYTHON" -c 'import build, twine' 2>/dev/null; } + +# CI's build job, minus the artifact upload. Everything happens in a temporary +# directory rather than in dist/, so a release artifact already sitting in the +# tree is neither clobbered nor mistaken for this run's output. +check_build() { + local dist status=0 + dist="$(mktemp -d "${TMPDIR:-/tmp}/libei-build.XXXXXX")" || return 1 + + # A subshell under `set -e`, so the first failing step is where it stops -- + # the shape CI has, where each step is its own `run:`. + ( + set -e + "$PYTHON" -m build --outdir "$dist" + "$PYTHON" -m twine check --strict "$dist"/* + + # CI's tag check, which only means anything when HEAD *is* a tag. A + # PyPI version number can never be reused, so a tag disagreeing with + # the packaged version has to fail rather than ship -- read back out of + # the built artifact, not out of the source. This is the repo that had + # most to gain from it: 0.5.2 exists because eleven commits accumulated + # past v0.5.1, including a signal fix, with nothing anywhere able to + # notice the released number had stopped describing the tree. + tagged="" + if command -v git >/dev/null && + tag="$(git -C "$ROOT" describe --exact-match --tags HEAD 2>/dev/null)"; then + [[ $tag == v* ]] && tagged="$tag" + fi + if [[ $tagged ]]; then + built="$(cd "$dist" && printf '%s' python_libei-*.tar.gz)" + built="${built#python_libei-}" + built="${built%.tar.gz}" + printf 'tag=%s packaged=%s\n' "$tagged" "$built" + if [[ ${tagged#v} != "$built" ]]; then + echo "tag $tagged does not match the packaged version $built" \ + "-- fix the version in pyproject.toml or retag." + exit 1 + fi + fi + ) + status=$? + + rm -rf "$dist" + return "$status" +} + +# --------------------------------------------------------------------- run + +results=() # "check|status|duration|logfile" +failed=0 +ran=0 +skipped=0 +run_start="$(now)" + +printf '%s%s%s %s %s\n' "$BOLD" "pre-commit-test" "$RESET" \ + "$("$PYTHON" -V 2>&1)" "${DIM}$(date '+%F %T')${RESET}" +printf '\n%s== python-libei ==%s\n' "$BOLD" "$RESET" +printf ' %snative%s %s\n' "$DIM" "$RESET" \ + "${native:-libei is not importable by $PYTHON -- pip install -e '.[dev]'}" + +active_checks=("${CHECKS[@]}") +((full)) && active_checks+=("${FULL_CHECKS[@]}") + +for entry in "${active_checks[@]}"; do + IFS='|' read -r name cmd guard needs <<<"$entry" + matches want_checks "$name" || continue + + # A guard that says no is a SKIP: printed, counted, and not a failure. + # --full on a machine without the build packages is a legitimate run, and + # the summary says which claims it did not check. + if [[ $guard ]] && ! "$guard"; then + printf ' %-8s %sSKIP%s %s(%s not available)%s\n' \ + "$name" "$YELLOW" "$RESET" "$DIM" "$needs" "$RESET" + results+=("$name|SKIP|-|") + ((skipped++)) + continue + fi + + log="$LOGDIR/$name.log" + if ((verbose)); then + printf ' %-8s %s$ %s%s\n' "$name" "$DIM" "$cmd" "$RESET" + elif ((TTY)); then + printf ' %-8s %s...%s' "$name" "$DIM" "$RESET" + fi + + start="$(now)" + if ((verbose)); then + ( cd "$ROOT" && eval "$cmd" ) 2>&1 | tee "$log" + status=${PIPESTATUS[0]} + else + ( cd "$ROOT" && eval "$cmd" ) >"$log" 2>&1 + status=$? + fi + dur="$(awk -v a="$start" -v b="$(now)" 'BEGIN { printf "%.1fs", b - a }')" + ((ran++)) + + cr=$'\r'; { ((verbose)) || ((!TTY)); } && cr='' + if ((status == 0)); then + printf '%s %-8s %sPASS%s %6s\n' "$cr" "$name" "$GREEN" "$RESET" "$dur" + results+=("$name|PASS|$dur|$log") + else + printf '%s %-8s %sFAIL%s %6s %s(exit %d)%s\n' "$cr" \ + "$name" "$RED" "$RESET" "$dur" "$DIM" "$status" "$RESET" + results+=("$name|FAIL|$dur|$log") + ((failed++)) + ((fail_fast)) && break + fi +done + +((ran + skipped)) || { echo "pre-commit-test.sh: no checks matched" >&2; rm -rf "$LOGDIR"; exit 2; } + +# ----------------------------------------------------------------- summary + +total_dur="$(awk -v a="$run_start" -v b="$(now)" 'BEGIN { printf "%.1fs", b - a }')" + +if ((failed && !quiet && !verbose)); then + for entry in "${results[@]}"; do + IFS='|' read -r name status dur log <<<"$entry" + [[ $status == FAIL ]] || continue + printf '\n%s---- %s ----%s\n' "$YELLOW" "$name" "$RESET" + # Long test failures are the norm; the tail is where the summary is. + tail -n 40 "$log" + printf '%sfull log: %s%s\n' "$DIM" "$log" "$RESET" + done +fi + +# Named rather than counted alone: a skip is --full telling you which claims +# this machine could not check, and a run without them is still a pass. +list_skipped() { + local entry name status + for entry in "${results[@]}"; do + IFS='|' read -r name status _ _ <<<"$entry" + [[ $status == SKIP ]] && printf ' %sSKIP%s %s\n' "$YELLOW" "$RESET" "$name" + done +} + +printf '\n%s%s%s ' "$BOLD" "summary" "$RESET" +if ((failed == 0)); then + printf '%s%d/%d passed%s' "$GREEN" "$ran" "$ran" "$RESET" + ((skipped)) && printf ', %s%d skipped%s' "$YELLOW" "$skipped" "$RESET" + printf ' in %s\n' "$total_dur" + list_skipped + rm -rf "$LOGDIR" + exit 0 +fi + +printf '%s%d of %d failed%s' "$RED" "$failed" "$ran" "$RESET" +((skipped)) && printf ', %s%d skipped%s' "$YELLOW" "$skipped" "$RESET" +printf ' in %s\n' "$total_dur" +list_skipped +for entry in "${results[@]}"; do + IFS='|' read -r name status dur log <<<"$entry" + [[ $status == FAIL ]] && printf ' %sFAIL%s %s\n' "$RED" "$RESET" "$name" +done +printf '%slogs kept in %s%s\n' "$DIM" "$LOGDIR" "$RESET" +exit 1 \ No newline at end of file diff --git a/src/libei/__init__.py b/src/libei/__init__.py index 97aecb9..16aca75 100644 --- a/src/libei/__init__.py +++ b/src/libei/__init__.py @@ -31,6 +31,6 @@ Beta: the API is not frozen. """ -__version__ = "0.5.1" +__version__ = "0.5.2" __all__ = ["__version__"] diff --git a/src/libei/portal.py b/src/libei/portal.py index 9a43a40..ade9780 100644 --- a/src/libei/portal.py +++ b/src/libei/portal.py @@ -107,7 +107,7 @@ _MIN_INPUT_CAPTURE_VERSION = 2 # CreateSession2 is a v2-only method _DEFAULT_TIMEOUT = 60.0 -"""Seconds to wait for one portal round trip. Generous, because a human has +"""Seconds to wait for one portal round trip. Generous, because a user has to see and answer the consent dialog `Start` raises -- but bounded, because the alternative is a caller wedged forever if the portal dies after accepting the call and before sending its `Response`.""" @@ -159,7 +159,7 @@ class PortalTimeoutError(PortalError): Distinct from a decline: the portal accepted the call and then never sent its ``Response`` signal. Most often the consent dialog is simply - still waiting for a human, so raise the timeout rather than treating + still waiting for a user, so raise the timeout rather than treating this as a failure if that is expected. """ @@ -834,7 +834,7 @@ def negotiate( timeout=timeout, ) except BaseException: - # BaseException, not Exception: `Start` blocks on a human + # BaseException, not Exception: `Start` blocks on a user # answering a consent dialog, so Ctrl-C during that wait is a # routine way out of this function -- and it strands an # approved session exactly as a decline does. @@ -1006,7 +1006,7 @@ def _wait_for_signal( before this is even called (a long-enabled session, subscribed to late) or not for a long time. ``timeout=None`` waits indefinitely -- the read a caller wants when there is nothing else useful to do but - wait for a human to move the pointer. + wait for a user to move the pointer. **These signals are emitted on the portal object, not on the session object.** Subscribing with the session handle as the D-Bus object path @@ -1165,10 +1165,10 @@ class InputCaptureSession: **Never live-tested.** Every other class in this module that talks to a real portal carries a hand-verification note in its own docstring; this - one does not, because verifying it means a human clicking through the - consent dialog *and* accepting that their pointer will be diverted away - from their own desktop for the length of the test -- not something to - trigger without asking first, unlike everything else here. Designed + one does not, because verifying it means a developer clicking through + the consent dialog *and* accepting that their pointer will be diverted + away from their own desktop for the length of the test -- not something + to trigger without asking first, unlike everything else here. Designed against ``/usr/share/dbus-1/interfaces/org.freedesktop.portal. InputCapture.xml`` (the shipped portal spec, not the header alone) and unit-tested against a fake connection reproducing that spec's documented @@ -1406,7 +1406,7 @@ def wait_for_activation(self, timeout: float | None = None) -> Activation: """Block until the compositor activates capture, or ``timeout``. Only returns once a real barrier crossing has been reported -- - which, on hardware, means a human moved a physical pointer across + which, on hardware, means a user moved a physical pointer across one. There is no way to trigger this synthetically (see the class docstring's third paragraph), so this call can legitimately hang until someone does that, and `timeout=None` -- the default -- waits @@ -1668,7 +1668,7 @@ def negotiate( timeout, ) except BaseException: - # BaseException, not Exception: Start blocks on a human + # BaseException, not Exception: Start blocks on a user # answering a consent dialog, so Ctrl-C during that wait is a # routine way out of this function -- and it strands an # approved session exactly as a decline does. diff --git a/tests/test_documentation_shape.py b/tests/test_documentation_shape.py index d893450..99fb973 100644 --- a/tests/test_documentation_shape.py +++ b/tests/test_documentation_shape.py @@ -259,6 +259,61 @@ def test_version_is_declared_identically_in_both_places() -> None: ) +_DOCS_ROOT = _PROJECT_ROOT / "docs" +_INLINE_LINK = re.compile(r"\]\(([^)\s]+)\)") +_CONTENTS_ENTRY = re.compile(r"^- \[[^\]]+\]\(#([^)]+)\)$", re.MULTILINE) +_HEADING = re.compile(r"^#{1,6} (.+)$", re.MULTILINE) + + +def _documentation_pages() -> list[Path]: + """The README plus every page under docs/, which is the user set.""" + return [_README, *sorted(_DOCS_ROOT.rglob("*.md"))] + + +def _slug(heading: str) -> str: + """The anchor a heading gets, insensitive to how a slugger trims. + + Runs of dashes are collapsed and both ends stripped, so a heading naming a + ``--flag`` matches a contents entry written with one leading dash as well as + the two a strict slugger would produce. What is asked is "is there a section + for this", not "is the anchor byte-exact". + """ + text = re.sub(r"[^a-z0-9 \-_]", "", heading.strip().lower()) + return re.sub(r"-+", "-", text.replace(" ", "-")).strip("-") + + +def test_relative_links_point_at_something_that_exists() -> None: + # A page linked from another page is the only way most readers find it, so + # a move that updates the file but not the links makes it unreachable + # without breaking anything a reader can see. + pages = _documentation_pages() + assert len(pages) > 5, "the docs set looks empty; check the glob" + for page in pages: + for target in _INLINE_LINK.findall(page.read_text()): + if target.startswith(("http://", "https://", "mailto:")): + continue + path = target.split("#", 1)[0] + if not path: + continue + assert (page.parent / path).exists(), ( + f"{page.name} links to {path}, which does not exist" + ) + + +def test_each_pages_own_contents_resolves() -> None: + # The recipes and troubleshooting pages open with a catalogue of their own + # sections. A section renamed without the catalogue moving leaves a link + # that silently goes nowhere -- the page still renders, which is why + # nothing catches it. + for page in _documentation_pages(): + text = page.read_text() + headings = {_slug(heading) for heading in _HEADING.findall(text)} + for anchor in _CONTENTS_ENTRY.findall(text): + assert _slug(anchor) in headings, ( + f"{page.name} lists #{anchor} in its contents with no such heading" + ) + + 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 diff --git a/tests/test_inputcapture.py b/tests/test_inputcapture.py index 81c9dea..cb21445 100644 --- a/tests/test_inputcapture.py +++ b/tests/test_inputcapture.py @@ -3,7 +3,7 @@ All D-Bus calls are faked, for the same reason test_portal.py's RemoteDesktopSession tests are: nothing here can click through a real consent dialog, and unlike RemoteDesktop, InputCapture additionally cannot -be triggered at all without a human physically crossing a pointer barrier +be triggered at all without a user physically crossing a pointer barrier -- there is no synthetic way to fire Activated for real, which is exactly why negotiate() and the barrier/activation methods are unit-tested here but have never been run against a live portal. See InputCaptureSession's own @@ -391,7 +391,7 @@ def test_negotiate_without_pygobject_raises_portal_error() -> None: def test_an_interrupted_consent_dialog_closes_the_portal_session() -> None: - # Start blocks on a human answering the dialog; Ctrl-C during that wait + # Start blocks on a user answering the dialog; Ctrl-C during that wait # is a routine way out, and it strands an approved session exactly like # a decline does unless this closes it on the way out too. class RaisingConnection(FakeInputCaptureConnection): diff --git a/tests/test_portal.py b/tests/test_portal.py index 49257f5..a2ec294 100644 --- a/tests/test_portal.py +++ b/tests/test_portal.py @@ -808,7 +808,7 @@ def call_with_unix_fd_list_sync( def test_an_interrupted_consent_dialog_closes_the_portal_session() -> None: - # Why the cleanup catches BaseException: Start blocks on a human, so + # Why the cleanup catches BaseException: Start blocks on a user, so # Ctrl-C during that wait is a routine way out of negotiate() -- and it # strands an approved session exactly as a decline does. class InterruptedConnection(FakeConnection):