All notable changes to python-libei are recorded here. The format follows Keep a Changelog, and versions follow semantic versioning — with the usual 0.x caveat that the API may still change between minor versions.
- Round-trip coverage for the socket backend,
SEAT_BINDandscroll_stop/scroll_cancel. Three more groups of public names that no test reached, found the same way as 0.8.1's sweep.create_for_socket()on both sides is a whole transport the fd-backend tests never take, and the only one that can answereis.Client.pid—eis_backend_socket_get_client_pidreads a liveSO_PEERCREDcredential, so with client and server in one process the reported pid has to be exactlyos.getpid(). That symbol is libei 1.5+ while the transport itself is on the 1.0.0 floor, so the round trip runs everywhere and only the pid read is version-gated.SEAT_BINDexerciseseis_event_seat_has_capabilityat the value level, with the offer and the bind each passing their capabilities in a different order so the asserted result can match neither by accident.scroll_stop/scroll_cancelset their two axes asymmetrically, so a getter wired to the wrong axis symbol disagrees with what was sent.
-
*_get_context()is not quite as unbound as the docs said. The "deliberately unbound" list indocs/developers/architecture.mdand the matching bullet indocs/vs-snegg.mdboth claimed the whole*_get_context()family has nothing to hand back and is therefore not bound. The two device variants are in fact bound and used internally: when the caller givesframe()notimestamp, it reads the device's own context to get one, becauseei_now()needs a context. What is true of all of them is that none is ever surfaced — a context only ever reaches Python through its owncreate_for_*(), never wrapped from a raw pointer — which is the claim the docs now make. The seat, keymap and client variants stay genuinely unbound. -
There is no C-level logging for liboeffis.
docs/recipes.md's Logging section listedlibei.oeffisalongsidelibei.eiandlibei.eisas a logger carrying routed C diagnostics. liboeffis exposes no log-handler entry point to hook, so nothing of the sort reaches it; that logger carries only this package's own messages. Named explicitly rather than quietly dropped from the list, since "no output on that logger" is otherwise indistinguishable from a library that has gone quiet.
-
The
versionproperty reply is checked before it is believed. Both portals' version reads unpacked aProperties.Getreply on faith. As everywhere in this module,_call_syncis given noreply_type, so GDBus validates nothing about the shape that comes back — which is why every other reply-consuming site here checks the unpacked value first. These two did not: a reply that did not unpack to a single value raisedValueErrorout of the tuple assignment, and a non-numericversionraisedTypeErrorfromint(), both bare built-ins escaping theexcept PortalErrorthatdocs/troubleshooting.mdpromises covers the negotiation. They now raisePortalProtocolErrorwith the reply as the payload, like theResponseand fd-index faults beside them. ATrueis refused too rather than read as version 1 —boolis anint, so it would otherwise have been reported as a portal too old forConnectToEIS, blaming the version for a reply that was nonsense. Verified against a live portal rather than a stub: on Ubuntu 26.10 (GNOME/Wayland) the realorg.freedesktop.portal.Desktopanswered RemoteDesktop version 2 through this path, and six malformed shapes — two values, none, a non-tuple, a string, aTrueand aNone— each arrived as aPortalProtocolErrorcatchable asPortalError. With the check removed, the same six produced a bareValueError/TypeErroror silently returned the nonsense as a version. Reading a property needs no session and so no consent dialog, which is what makes this path reachable over a plain login. -
A failed second signal subscription no longer leaks the first.
_wait_for_signaltook its twosignal_subscribe()handles into locals before thetry/finallythat unsubscribes them, so a failure in the second left the first registered for the life of the connection with nothing holding its handle. Collected into a list as they are made and unsubscribed from that list, which is what_requestalready does. -
ConnectToEIS's fd reply was trusted in three ways it should not have been, one of which handed out-1as the EIS fd. The reply is(h)— an index into an fd list carried out-of-band — and_call_for_fd()passed the index straight tog_unix_fd_list_get(). Measured against GLib 2.90.1 and the Gio-2.0.gir contract, that is wrong three times over:- The out fd list is nullable. A well-formed reply that attached no
fds arrives as
None, and dereferencing it raisedAttributeError('NoneType' object has no attribute 'get') — a name noexcept PortalErrorcatches. - A bad index is a programmer error, not a runtime failure.
g_unix_fd_list_get()assertsindex >= 0 && index < nfd, logsGLib-GIO-CRITICAL, and returns-1without raising and without setting aGError. So the previous attempt at hardening this — anexcept GLib.Erroraround theget(), reporting "no matching fd" — could never fire for the case it was written for. The-1flowed out as the session'seis_fdinstead, into anei.Sender.create_for_fd()that has no guard against a negative one, withclose()'sos.close(-1)swallowing the resultingEBADFat debug level. The fix is the bounds check the GIR itself prescribes, againstget_length()—lookup()would do it in one call but is GLib 2.90+ only. - The one failure
get()does raise for is the dup it performs to hand back an owned fd, i.e. running out of file descriptors. That is still caught, and the message now says so rather than blaming the index.
All three now raise
PortalProtocolError, carrying the index as.payload, so a caller'sexcept PortalErrorcovers the fd leg of the negotiation as it already covered the signal payloads. The suite'sFakeUnixFDListgrew the real semantics to match — it holds a list of fds, returns-1for an out-of-range index and never raises — because the old one ignored its index entirely, which made every index valid and was why the gap went unnoticed. - The out fd list is nullable. A well-formed reply that attached no
fds arrives as
-
A socketpair round-trip covering the event accessors no test reached. Found by asking which public names never appear in any test file: the scroll, button, absolute-motion and emulating-sequence accessors on
eis.Event,ei.Event.keyboard_xkb_modifiers, andeis.Device.device_type/heightwere all unexercised. Each is a ctypes binding to a separate C symbol, so an unexercised one is where a wrong symbol name or a wrongrestypehides -- a mistake reading cannot catch, only letting the library answer. Every binding was in fact correct, and on libei 1.6 every value round-trips exactly (button 272, scroll 3.5/-2.0, discrete 120/-240, absolute 100/200, sequence 4242, modifiers 4/0/2/0). Driven in one negotiation rather than one test apiece, because the handshake is the expensive part and the values then have to agree within the same frame.The absolute leg needed a region to be configured on the device. libei 1.0.0's
ei_device_pointer_motion_absoluteends inif (!ei_device_in_region(device, x, y)) return;, and with no region the list it walks is empty, so the event was silently dropped -- no log, no error, just an event that never arrived. Local libei 1.6 delivered it anyway, which is why this only showed up on the CI runners' 1.0.x.
eis.Event.emulating_sequencereads 0 on every libei before 1.6, no matter what the client sent.eis_queue_device_start_emulating_event()built the event and never copied the sequence into it, so the getter returned a zeroed struct field; upstream added the one missing assignment in libei 1.6.0 (commit98cd152) and in no earlier tag. Measured 0 on 1.2.1, 1.3.901 and 1.5.0, and 4242 on 1.6.0 -- which covers Ubuntu 24.04 and Debian 13, so it is what most users of this package will see. The accessor and its binding are correct; there is simply nothing in the event to read, and because the symbol is exported from the 1.0.0 floor up there is nothing to raise either, leaving a 0 indistinguishable from a client that really sent 0. Now stated on the property and in the README besideEvent.touch_up_event, the other accessor that degrades rather than raising. The client-sideei.Event.emulating_sequenceis unaffected -- libei has always stored it -- so only the EIS leg of the new round-trip test is version-gated, and it asserts the 0 rather than skipping, which keeps the documented claim under test on an old library instead of merely unchallenged.tests/conftest.pygrewhas_symbol()for that branch: the existingrequires_symbolmark cannot see this class of difference, where the symbol is present on every version and only its answer changed.
ei_region_convert_pointwas marked as needing libei 1.1, and does not. It is declared in libei 1.0.0's own public header and implemented there; the marker put it alongside its genuine 1.1 neighboursei_region_get_mapping_idandei_device_region_at. The weekly declared-floor job is what caught it -- building libei 1.0.0 from source found the symbol present where the marker promised it would be absent -- which is the job working as intended rather than a flake. The README's version table no longer tells a reader on a 1.0.x build thatRegion.convert_point()is out of reach, and every remaining marker was swept against 1.0.0's real headers: 17ei_and 18eis_markers, none of them contradicted.- A malformed
Responsereply to a portal request now raises the typedPortalProtocolErrorinstead of a timeout or a crash. Every Request-returning portal call waits on aResponsespecified as(u response, a{sv} results), and_requestunpacked it on faith: a wrong-arity payload raised inside the GLib signal callback -- where PyGI prints the traceback to stderr and swallows it, so the step silently degraded to a full-timeoutPortalTimeoutError-- while a non-dictresultsslipped through to callers, whose.get()crashed with a rawAttributeErrorpastexcept PortalError. The shape is now checked in the callback and any mismatch ends the wait withPortalProtocolError(the same hardening the session signals received in 0.8.0), so what_requestreturns is structurally guaranteed: anintcode and adictof results.GetZones' andSetPointerBarriers' result values are converted under the same kind of guard as the Activated signal's (zone_setand each zone's four coordinates as the spec's integers,failed_barriersas a list of them) -- and adwhere the spec gives an integer is now rejected rather than silently truncated byint(), so a0.9coordinate or a1.9refused-barrier id cannot read back as a different, valid-looking value. And aResponselanding in the same main-context iteration as the request's deadline now resolves to whichever outcome was recorded first, rather than the delivered reply being dropped for a timeout -- the same simultaneous-dispatch fix_wait_for_signalalready had. - Every event pulled from the dispatch queue leaked one C reference.
ei_get_event()andeis_get_event()transfer ownership of the returned event to the caller, butei.Context.events()andeis.Eis.events()wrapped it withwrap(), which is for borrowed pointers and takes its own extra ref -- so the transferred reference was never released, leaking oneei_event/eis_eventfor every event the iterator yielded. They nowadopt()the transferred reference, which takes no extra ref and lets the wrapper's finalizer balance the one the C API handed over.
- A malformed portal signal payload now raises the new typed
PortalProtocolErrorinstead of hanging or crashing the caller. Every signalwait_for_activation()andwait_for_deactivation()wait on is specified as(o session_handle, a{sv} options), and that shape used to be unpacked on faith, failing differently depending on how it was wrong: an empty tuple raisedIndexErrorinside the GLib signal callback — where PyGI prints the traceback to stderr and swallows it, so the loop kept running and the wait hung (unboundedly, withtimeout=None), the worst case because it was invisible; a wrong-length tuple or a non-dict options value instead slipped through to the caller and crashed it withValueError/AttributeError. The shape is now checked in one place and any mismatch ends the wait withPortalProtocolError, naming the signal and the payload that arrived. The value level is covered too: every field the spec types —activation_id(u),cursor_position((dd), now checked for exactly two numeric components rather than any iterable),barrier_id(u) — is converted under one guard, so a non-conforming value in any of them raises the same typed error (including theOverflowErroran infiniteactivation_idwould otherwise throw past anexcept PortalError) rather than crashing the caller later doing arithmetic on a string. Oneexcept PortalProtocolErrortherefore covers every way a non-conforming portal can malform one of these signals. The error carries.step(the signal name, the attribute every sibling portal error uses),.payload, and.detail(Nonefor a shape fault, a phrase naming the field for a value fault). Signals and the wait's deadline or a session close that become ready in the same GLib main-context iteration now resolve to whichever outcome was recorded first, rather than a delivered activation being dropped for a timeout.
- A portal session closed from the compositor's side now ends a wait
instead of hanging it.
InputCaptureSession.wait_for_activation()andwait_for_deactivation()subscribe to the session object's ownorg.freedesktop.portal.Session::Closedsignal alongside the signal they wait for, and raise the new typedPortalSessionClosedErrorwhen it fires — naming what was being waited for. Before this, a wait withtimeout=Noneon a session the compositor or portal had ended (a compositor restart, the portal process dying, capture revoked from a settings panel) blocked forever, indistinguishable from a pointer barrier nobody had crossed yet. NoteClosedreally is emitted on the session's own object path — the opposite ofActivated/Deactivated, which fire on the portal object. - A weekly CI job builds libei 1.0.0 and 1.1.0 from source and runs the suite against them. The README's "libei 1.0.0 or newer" floor was a claim nothing executed — development tracks 1.6.x and CI's Ubuntu ships 1.2.1 — so the declared floor now runs for real, with the version-gated tests skipping loudly as designed.
- The ABI tests misread upstream's prerelease version numbers. Debian 13 ships libei 1.3.901 — a snapshot on the way to 1.4 that already exports the 1.4 symbols — and the "marked functions really are absent from a library that predates them" pin read 1.3.901 as predating every 1.4 marker, failing on a library whose only sin was being packaged mid-cycle. A micro of 900 or more is now normalized to the next minor, matching what such a library actually contains. Found by running the suite across eight live machines; the binding itself was never wrong, only the test's reading of the version.
- The package metadata and README now say
libei.portalcaptures input, and the README counts its modules right.InputCaptureSession-- receiving the user's real pointer and keyboard through the InputCapture portal -- was in the module docstring and nowhere a reader looks: not the PyPI description, not the keywords, and not the README's table of what to use for what. The description now names it,input-captureandeisjoin the keywords, and the table has a row that says, asdocs/developers/verification.mddoes, that only its negotiation half has been run against a real desktop. Also thePOSIXoperating-system classifier the other two packages carry, adocumentationURL and a link to pyguitest, its main consumer. The README said "Five modules" where there are four (ei,eis,oeffis,portal; the table has five rows).InputCaptureSession's docstring said "Never live-tested", which the verification log contradicts for its negotiation half; it now says half.
-
Using a released event raised
ctypes.ArgumentError, not the documentedRuntimeError. Each event is released as the loop moves on, and the README anddocs/recipes.mdpromise aRuntimeErrorif one is used afterwards. What a caller actually got, from a real call, wasArgumentError: argument 1: RuntimeError: Event has already been released-- ctypes wraps anything raised while converting an argument and keeps only its text, soexcept RuntimeErrormissed it. The unit test passed because it read_as_parameter_directly and never crossed ctypes; found by probing the real library for the README's claims.LazyLibrarynow re-raises the originalRuntimeErrorwhen an argument is a released object, and an ordinary bad argument is still ctypes' own error. -
Six bindings named no libei version, so an old library read as a mystery.
ei_touch_cancel,ei_event_touch_get_is_cancel,ei_event_pong_get_pingand their libeis counterparts arrived in libei 1.4, andeis_backend_socket_get_client_pidin 1.5; none carried the# libei X.Y+marker the other gated declarations do. Found by checking every declaration against the headers of 1.0.0, 1.2.1, 1.4.0, 1.5.0 and 1.6.0. Behaviour was already right -- the README's version table had them correctly -- so this is the source catching up with it. -
The docs said forgetting
frame()means nothing happens, silently. It is only true withoutstop_emulating(). Measured against libei 1.2.1 and 1.6.0: a motion queued and then followed bystop_emulating()is delivered, in aFRAMElibei adds itself, and logged as an error --Bug: ei_device_stop_emulating: missing call to ei_device_frame(). Only a queue that is never stopped is dropped with no log line at all. The README, getting-started and troubleshooting now say so. The same probing corrected two more claims: an event sent to a device lacking the capability is dropped with aBug: ... device is not a keyboarderror log rather than "silently", and the wrong-accessor read libei answers with zeros is likewise logged at error level rather than "a line the caller never sees". The README's list of versions the suite has been run against named 1.5.0, whichdocs/developers/verification.mdhas no record of, and contradicted its own Status section on CI's 1.2.1; both now agree. -
The test suite ran nothing at all off Linux and FreeBSD.
tests/test_loader.pyraised at module level whenctypes.util.find_library("c")found no C library, which pytest reports as a collection error -- so on Windowspytest -q -rsstopped before any of the other 200-odd tests, including every pure-Python one. The four loader tests that need a real library now skip there instead, and the three tests that build a keymap withos.memfd_createskip where it does not exist. On Windows the suite now reports 212 passed, 18 skipped; on Linux nothing changes -- 230 passed against libei 1.6.0. -
The count of unbound gesture/stylus functions was stale. The README and
docs/developers/architecture.mdsaid libei'smainadds 22; counted against 1.6.0's headers on 2026-09-30 it is 46 in libei and 51 in libeis, now that the stylus protocol has landed there too. Still none of it is in a release, so still none of it is bound.
- The bindings are checked against the real headers and libraries.
tests/test_abi.pycompares every declared function's argument count and argument and return classes (pointer, 4- or 8-byte int, double, bool, void) with the upstream prototype, every Python enum member with its C enumerator value, and every declaration with the installed library's exports, where a missing one must carry a version marker. There are noctypes.Structurebindings, so there is no layout to check. It needs the headers, viaLIBEI_SOURCE_DIR, and otherwise skips; see CONTRIBUTING.md. Clean against the public headers of 1.0.0, 1.2.1, 1.4.0, 1.5.0 and 1.6.0, and against the installed 1.6.0 (Fedora 45) and 1.2.1 (Ubuntu 24.04) libraries.LazyLibrarynow records what is declared on it (declared,soname) for this. - Every event accessor against every event type.
tests/test_event_accessors.pyreads the accessor list from the source, so a new one is covered automatically, and checks that each raisesTypeErrorbefore any C accessor is called for every wrong type, on both the client and server side, and that an accessor added without a guard fails. Previously one wrong type per library was pinned. - Forgetting
frame()and using a released event, against the real library.tests/test_integration_frame.pypins the four behaviours above andtests/test_integration_lifetime.pythe released-event error; the loader tests gain missing-symbol behaviour (named, repeatable, the rest still working) and one-open-under-concurrent-first-calls.
-
LibraryNotFoundErroris now part oflibei.ei's,libei.eis's andlibei.oeffis's public surface. It has always been raised from all three --_capi/loader.pyraises it the moment adlopenfails, or an installed library turns out too old to export a bound function -- anddocs/troubleshooting.mdhad been telling readers to writefrom libei.ei import Error, LibraryNotFoundErrorsince its exceptions table went in. It was in no module's__all__, alone among the eight classes that table names: catchingei.LibraryNotFoundErrorworked, butfrom libei.ei import *,pydoc, an IDE's completion, and anything else reading a module's declared surface did not see it, and the only obviously public place to import it from was the privatelibei._capi.loaderit is defined in. Two of the three modules come from the table;libei.oeffiswas found while fixing those,Oeffis.create()on a machine with no liboeffis being the same failure one module over. Nothing moved to the package root either way:libei/__init__.pystill carries only__version__, as that page says. -
docs/troubleshooting.mdnow names the exceptions, having been the page for everything that doesn't raise. Eight classes are raised from real paths and were named in no user-facing text:ei.Errorandeis.Error(22 raise sites between them, two classes sharing no ancestor, carrying.errnowhere libei reported one),portal.PortalError(18 sites, the "session is closed" path among them) with its three subclasses, andoeffis.DisconnectedError/SessionClosedErrorfrom a session that ends under the caller. Only the three portal subclasses appeared anywhere, and only inside one sentence ofrecipes.md; the twoErrorclasses and both oeffis ones appeared on no page at all — so the names a caller writes in anexceptclause were exactly the names the docs did not carry. The new section gives what each is raised for and what nests under what:except PortalErrorcovers its three,except DisconnectedErrorcoversSessionClosedError, andei.Error/eis.Errorcover nothing but themselves. -
docs/recipes.mdpairs every event type with the getter that reads it. The page listed twelve getters in a sentence and never said which event each one belongs to — the pairing theTypeErrorbeside them exists to enforce, and the reasonkeyboard_xkb_modifiersreads oddly, being the only getter not named after the class it unwraps. Two more were missing from the sentence entirely:pong, which is used two paragraphs below it, andemulating_sequence. All fourteen are now a table with the fields each returns and the libei version where one is needed, followed by the connection and lifecycle events, which have no getter and are read throughevent_type. -
CI, PyPI and license badges on the README. The three things a reader checks before installing anything -- whether the suite is green on
main, what the current release is, and under what license -- each took a click through to somewhere else. The PyPI badge is also the one version statement in the repository that reads what is actually published: the prose lines thattests/test_documentation_shape.pyguards are held to this checkout'slibei.__version__, which says nothing about whatpip installwould fetch. -
.coderabbit.yaml, turning the Docstring Coverage pre-merge check off and telling the reviewer not to ask for docstrings undertests/. That check scores a whole diff against a single percentage threshold and its schema offers no per-path option, so it cannot see that[tool.ruff.lint.per-file-ignores]ignoresD100-D104andD107undertests/*deliberately -- matching both sibling repos, on the grounds that each test is named for the behaviour it pins -- and so it objected on every PR that adds tests, which is most of them. Coverage ofsrc/is untouched: ruff's pydocstyle rules enforce it inscripts/pre-commit-test.sh, and those are path-aware. The same exclusion is repeated as apath_instructionsentry, which is where it can be path-scoped, so it holds whether or not the check is ever switched back on.
-
The docstring-completeness check now runs everywhere, and covers
libei.portal. It lived intests/test_documented_examples.py, whose module-levelintegrationmark skips the file where the native libraries are absent -- so a check that reads source withastand needs nothing installed was skipping on exactly the machines where it was cheapest to run. It now sits intests/test_documentation_shape.py, beside the other checks that need no native library, takes in classes as well as functions, and includeslibei.portal, which was never checked. Nothing had to be written to make it pass: every public definition in all four modules already carries a docstring, so this is a guard rather than a cleanup. -
A new check ties the exceptions table to the modules it names.
tests/test_documentation_shape.pynow reads the table indocs/troubleshooting.mdand asserts that every class it pairs with a module is both reachable from that module and listed in its__all__-- and that a class shared between modules is one class in all of them, which is what makes oneexceptclause cover every module that raises it. This is the check that would have caughtLibraryNotFoundErrorwhen the table itself was written. -
The documentation guards reach the files that were drifting.
tests/test_documentation_shape.pycompared the README's version line againstlibei.__version__but not the developers page's, which is how 0.5.1 sat there through a release; both pages are compared now. The module-docstring example check covered the two modules that used::and read nothing at all from the two that did not -- both are covered now, all four public modules. A new check reads every docstring in those modules for the two defects below, neither of which is visible anywhere but in the rendered text: a role split across a line break, and an unpaired backtick. Andtests/test_portal.pynow asserts whatverification.mdclaimed it covered -- thatCreateSessioncarries asession_handle_token, whose absence crashes xdg-desktop-portal 1.22.1 outright. -
39 docstrings on the dunders and private helpers that had none. No check asked for them: ruff's pydocstyle rules treat an underscore-prefixed name as non-public, and this repo's config ignores
D105outright -- so__init__,__eq__,__hash__,__repr__,__del__,__enter__/__exit__,__init_subclass__,_cobject.CObject._get_or_create(),LazyLibrary._ensure_loaded()and both_log_callbacks went undocumented while being the definitions whose behaviour is least guessable from the signature: pointer adoption and the per-hierarchy identity cache, a faileddlopencached rather than retried, a C function resolved on first call rather than at bind time.help()and an IDE's hover show all of them, and neither cares that a name starts with an underscore.
-
The README's link to the developer pages landed on a file listing.
docs/developers/holdsarchitecture.mdandverification.mdand has no README of its own, so the last entry of the documentation index sent a reader to a directory listing rather than to anything written -- the same defect the sibling recorder repo fixed in its own README, found by holding this one to that fix. The entry now names both pages, andtests/test_documentation_shape.pyrequires a linked directory to have a README rather than merely to exist, which is the distinctionexists()cannot draw. -
Three public names were documented nowhere.
eis.Flag,eis.ConfigureRegionandportal.Activationare in their modules'__all__-- the declared surface, the thingfrom libei.eis import *,pydocand an IDE's completion read -- and appeared on no page of the README ordocs/: the only way to learn they existed was to open the source that defines them. Each is now named where its subject is described:FlagandConfigureRegionbesideEis.set_flag()andDevice.configure()in the README's tour of the modules, with the region argument written out in the own-EIS-server recipe, andActivationin the sentence saying whatportalis smaller thaneiby. The guard runs the direction the existing checks never did -- every one of them went from a page to the source, and none from the declared surface back to the pages -- so a public name that ships with prose nowhere is a failing test rather than a discovery. -
scripts/pre-commit-test.shfailed itstestscheck on any interpreter without the package installed. The script runspython -m pytest -q -rswith noPYTHONPATH, deliberately: CI's install step is one of the two things it leaves to the runner. But[tool.pytest.ini_options]here had onlytestpaths, so nothing putsrcon the path, andtests/conftest.py'sfrom libei import eidied at collection -- reporting an ImportError for the whole suite where pyguitest and pyguitest-recorder both setpythonpath = ["src"]and just run. The other four checks passed, which is what made it look like a test failure rather than a path one. Same setting added here; a bare checkout now runs the suite with nothing installed, which is also what makes a copied tree testable anywhere. -
Four documentation defects, each invisible from the page it is on.
docs/developers/verification.mdopened with "the package is beta (0.5.1)" a release after 0.5.2 shipped, and nothing compared that prose topyproject.tomlthe way the README's own version line is compared. The same page anddocs/vs-snegg.mdboth pointed a reader at "the README's Troubleshooting section", which has never existed -- the GNOME 44 explanation they mean is indocs/troubleshooting.md, and both links now go there. AndInputCaptureSession's own docstring broke a role across a line, so:meth:wait_for_activation`` rendered as the literal text ":meth:" and a name rather than as a link. The README's module table also promised that each module carries anErrorexception and an `EventType`/`DeviceCapability` enum, which holds for `ei` and `eis` only: `oeffis` and `portal` raise their own classes and carry `DeviceType` instead, so a reader writing `except oeffis.Error` was chasing a class that does not exist. All four are corrected. -
The two module docstrings that carry a usage example now mark it as one.
oeffisandportalwrote their examples as plain indented blocks, whereeiandeisuse the::a reST literal block needs -- which is also why the example check had never read either of them, since the extractor looks for that marker. The blocks themselves were already valid Python and unaffected.
docs/install.md, a page for the halfpipcannot do: the nativelibei/libeis/liboeffislibraries, which distribution provides them under which name, and the optional[portal]extra. The same information was spread across two README sections, andtroubleshooting.mdcarried a Fedora-onlydnfline 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 standardhints.pyin pyguitest holds itself to as well.
-
Ruff now enforces pydocstyle plus the same complexity/simplification/ argument rules pyguitest and pyguitest-recorder already gate on (
D,C4,SIM,RET,ARG,C901, ceiling 15) -- this repo's config had never turned them on. Closing the gap surfaced two real things: eighttry/except OSError: passblocks (tests plus two__del__methods inportal.py) rewritten ascontextlib.suppress(OSError), and ~40 missing docstrings, mostly one-line additions to the per-event dataclasses inei.py/eis.pynaming the numbering scheme a field uses (e.g.KeyEvent.keyis a LinuxKEY_*code, matchingDevice.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.
-
InputCaptureSession.wait_for_activation()/wait_for_deactivation()now actually receive their signals. Both subscribed toActivated/Deactivatedwith the session handle as the D-Bus object path, but the portal emits these on its own object (/org/freedesktop/portal/desktop), identifying the session by the signal's first argument instead. The subscription therefore matched nothing and the wait always ran to its timeout -- indistinguishable, from the caller's side, from a compositor that never activates capture, which is exactly how it was misdiagnosed: as a Mutter bug, across two GNOME versions, a standalone C reproducer and an upstream bug report, until an xdg-desktop-portal developer pointed out the mistake. Now subscribes on the portal object and filters on the payload's session handle, so a second concurrent session's signals are ignored rather than answered. -
_wait_for_signal(used byInputCaptureSession.wait_for_activation/wait_for_deactivation) no longer double-removes its own GLib timeout source on timeout, which logged a real GLib warning ("Source ID N was not found when attempting to remove it") on every timed-out wait.GLib.timeout_add's callback returnsFalse, which already deregisters the source; the cleanupfinallyblock calledGLib.source_removeon it again unconditionally. Caught live on the GNOME 50 box (this session's first real timeout run against a genuine GLib main loop) -- the unit tests' fakeGLib.source_removedoesn't reproduce the warning, so it was invisible to the suite. -
_requesthad the identical double-remove bug as its sibling above, never fixed alongside it._requestbacks every Request-returning RemoteDesktop/InputCapture call (CreateSession,SelectDevices,Start,GetZones,SetPointerBarriers) -- far more heavily used than_wait_for_signal-- so this covers the single most realistic timeout scenario in the module: a consent dialog nobody answers. Found by a self-review sweep after the_wait_for_signalfix, not live; fixed the same way, with a test mirroringtest_inputcapture.py's existing one for_wait_for_signal.
-
InputCaptureSession.negotiate()now works against pre-v2 portals, via the deprecated v1CreateSession. OnlyCreateSession2andStartare version 2 additions to the interface --GetZones,SetPointerBarriers,Enable,Disable,ReleaseandConnectToEISare all v1 originals -- so just session creation forks and everything after negotiating is unchanged. On v1 a singleCreateSessioncarriescapabilitiesand raises the consent dialog itself; there is noStartto call.This turns out to matter on shipping systems, not just old ones: xdg-desktop-portal-gnome 50 reports InputCapture version 0 -- it registers the complete impl interface (including
ConnectToEIS, theActivated/Deactivatedsignals andSupportedCapabilities = 15) and simply never sets theversionproperty, and the frontend derives its own version from the impl's. Previously that raisedPortalVersionError: InputCapture version 0 is too old for CreateSession2and there was no way through. Live-validated on Fedora 44 / GNOME Shell 50.0 (xdg-desktop-portal 1.21.1): negotiation returns a real EIS fd andzones()answers(0, [(1920, 1080, 0, 0)]).Note that such a portal's introspection XML advertises
CreateSession2anyway -- that XML is static and says nothing about what the frontend will dispatch, which is why theversionproperty is read first and believed. CallingCreateSession2there fails withUnknownMethod.The one thing v1 cannot do is persist:
persist_modeandrestore_tokenwere added toStart, which does not exist. Passing either against a pre-v2 portal now raisesPortalVersionErrorexplaining that, rather than being silently ignored and handing back arestore_tokenofNone.
-
libei.portal.InputCaptureSession, the read direction: receiving real input from the user's own devices viaorg.freedesktop.portal.InputCapture, rather than injecting synthetic input the wayRemoteDesktopSessionand every other class in this package does. MirrorsRemoteDesktopSession's own architecture closely --negotiate()(CreateSession2->Start->ConnectToEIS), the samePersistMode/restore-token round trip, the same ownership rules foreis_fdandclose()-- and reuses its private Request/Response plumbing directly rather than duplicating it;_request()gained an optionaltrailing_argsparameter forSetPointerBarriers, the one Request-returning method in either portal whoseoptionsargument is not last.Adds
zones(),set_pointer_barriers(),enable()/disable()/release(), andwait_for_activation()/wait_for_deactivation()-- new plumbing this needed andRemoteDesktopSessiondid not: capturing is triggered by the compositor deciding a pointer barrier was crossed, not by a call this module makes, so waiting forActivated/Deactivatedis an ordinary signal subscription rather than the request-that-returns-a-handle pattern every other method here uses.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 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 -- seetests/ test_inputcapture.py, including its own note on the one bug this caught: an early draft of one test omitted the "force PyGObject import to fail" patch its sibling intest_portal.pyalready used, which on a system where PyGObject really is installed reached the real session bus instead of a fake one and raised a real consent dialog. No pointer barriers had been set andEnable()was never reached, so nothing was actually captured -- but the test now forces the import failure explicitly, the way its sibling always did.
-
The README no longer asks you to learn libei before you can use python-libei. An external review put it exactly that way, and the shape of the file agreed: 812 lines, with the four-layer architecture, the release process and a full verification log sitting between a new reader and the code they needed. It is now 375 lines and leads with what a caller does.
Added where they were missing: a
frame()callout in the opening lines, since events queueing until a frame commits them is the one concept every user must hold and the commonest reason a first attempt appears to do nothing; and a "Which API do I need?" table —ei.Sendervsei.Receivervsoeffisvsportalvseis— because the package exposes five modules and most callers need exactly two.The
What's implementedtable is now two tables.GESTURESandSTYLUSare in no released libei, and a skimming reader could take a single table as saying otherwise. They now sit under their own heading that says binding them against a shipping library silently does nothing. -
New
docs/:getting-started.md(install through a first real pointer motion),recipes.md(keyboards, touch, absolute positioning, consent persistence, receiver mode, EIS server, logging),troubleshooting.md, and an index. Troubleshooting is deliberately a 10-point "when nothing happens" checklist rather than a list of error messages, because nearly every failure mode here — a missingframe(), emulating beforeDEVICE_RESUMED, an event the device lacks the capability for — is silent by design. -
New
CONTRIBUTING.md, holding the setup, checks, old-libei reproduction and release process that were living in the README, matching the convention of the sibling projects. The architecture explanation moved todocs/developers/architecture.mdand the per-path verification log todocs/developers/verification.md, with a short trust summary left in the README's Status section.
-
The test suite's own portability:
tests/test_loader.pyusedlibc.so.6as its stand-in "always available" shared library -- correct on glibc, wrong everywhere else. Confirmed on FreeBSD, whose libc islibc.so.7, where it made four otherwise-unrelated tests fail for a reason that had nothing to do withLazyLibrary, which was behaving correctly the whole time -- it was accurately reporting that a soname which doesn't exist on that platform isn't available. Resolved withctypes.util.find_library("c")instead of a hardcoded soname. -
[tool.mypy]'s defaults broke on FreeBSD in two independent ways, only visible oncemypyactually ran there rather than just installed.sqlite_cache(mypy's own default is on) importssqlite3unconditionally, which crashes rather than falls back on a Python built without_sqlite3-- GhostBSD's python3.11 port is one such build. And once that was cleared,os.memfd_createfailed type-checking on FreeBSD even though it works correctly there at runtime (confirmed directly:hasattris true, and it round-trips real data) -- typeshed's stub for it is still gated tosys.platform == "linux", and mypy's--platformdefaults to whatever OS invokes it.sqlite_cache = falseandplatform = "linux"fix both; the second pins every run to check against Linux's stubs regardless of the contributor's own OS, so results stop depending on wheremypyhappens to execute.
- Development status is now Beta rather than Alpha. The API is still not
frozen — expect renames before 1.0 — but nothing in the public surface
has moved since 0.2.0, the injection path is exercised end to end against
the real libraries on every CI run, and the one module that cannot be
covered that way,
libei.portal, has now been both hand-verified against a real GNOME session and hardened against the failure paths hand verification never reaches (see below).
-
libei.portal: a negotiation that failed afterCreateSessionleft the portal session it had just created open. Nothing could close it: noRemoteDesktopSessionexists to own it until every step has succeeded, and the D-Bus connection it was created on is GLib's shared session-bus singleton, which outlives the failure rather than dropping 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 onKeyboardInterrupt:Startblocks 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. -
libei.portal: the caller'stimeoutnow bounds the D-Bus call that starts each round trip, not just the wait for theResponsesignal that answers it. Those calls were left on GDBus's-1, which is not "no timeout" (that isG_MAXINT) but GIO's own 25-second default — so the bound on a round trip was a number this module never chose and a caller could not see, andConnectToEIS, which returns noRequestat all, was bounded by nothing else. Both legs now draw on one deadline, so a slow first leg cannot double the wait a caller asked for, and GDBus's own reply timeout (G_IO_ERROR_TIMED_OUT, which is what it raises rather than anorg.freedesktop.DBus.Error.*code) raisesPortalTimeoutErrorlike any other round trip that runs out of time, instead of a genericPortalError. -
libei.portal:RemoteDesktopSession.close()sentSession.Close()to the default portal bus name even whennegotiate(busname=...)had used another one, so such a session was never actually closed. The session now remembers the name it was negotiated on, whichRemoteDesktopSession.__init__takes as a new optionalbusnameargument defaulting to the standard portal name — the one API addition in this release, and why it is a minor rather than a patch. -
libei.portal: aCreateSessionthat answered "approved" with nosession_handleraisedKeyErrorstraight past a caller'sexcept PortalError; it now raisesPortalErrorlike every other malformed reply.
-
libei.portal: negotiateorg.freedesktop.portal.RemoteDesktopdirectly over D-Bus (via PyGObject, the new optionalportalextra) instead of throughlibei.oeffis/liboeffis, exposingpersist_mode/restore_tokensupport that liboeffis's C API doesn't have —oeffis_create_session()takes only a device-type bitmask. Upstream's own docs say as much: liboeffis is "intentionally kept simple, any more complex needs should be handled by an application talking to DBus directly."RemoteDesktopSession.negotiate()is a synchronous port of a request/response sequence (including two hard-won fixes: a subscribe-before-call race, and asession_handle_tokencrash workaround for xdg-desktop-portal 1.22.1) that was already live-verified as the Wayland input backend of a separate GUI-automation project — this is that logic upstreamed into the library itself, so other consumers don't have to reimplement it. See the README's "Avoiding the consent dialog on every run".RemoteDesktopSessionis a context manager and has an explicitclose(), which ends the portal session (Session.Close()) and closes the EIS fd if it was never claimed. Both matter:Gio.bus_get_sync()returns GLib's shared connection, so dropping the object tears nothing down, and the fd arrives dup'd and owned by the receiver. Each portal round trip is bounded by atimeout(60s default,PortalTimeoutErroron expiry) so a portal that accepts a call and then dies cannot wedge the caller forever. GDBus failures — no session bus, no portal implementation — are wrapped inPortalErrorrather than escaping as rawGLib.Error. Passingrestore_tokenwithout apersist_moderaisesValueError, since the portal answers that combination with no token at all and a caller storing what came back would writeNoneover the one it just spent. AndDeviceType.ALL_DEVICES, which is liboeffis's sentinel and literally0, is translated to every device type the portal defines — sent raw it would mean no device types, yielding a session on which no device ever appears.Two further details the portal makes you get right: the
Responseis awaited on the handle the call actually returned as well as on the path derived from our ownhandle_token, because the spec says those match but a portal is free to hand back something else — watching only the derived path means such a reply is never seen. And the main loop only runs when no reply is already in hand:quit()on a loop that is not running yet does not stop a laterrun(), so a Response delivered synchronously during the call would otherwise block forever on a result already collected.
No changelog entry recorded before this file was created; see git history and PyPI release notes.
Initial release.