How the package is put together. Reading order matters here — each layer only makes sense once the one below it does.
| Layer | What it does |
|---|---|
_capi/loader.py |
LazyLibrary: dlopens a .so on first call, not at import, so this package imports fine with no native libraries installed |
_capi/libei.py, libeis.py, liboeffis.py |
One line per C function, with hand-written ctypes signatures. Nothing else — no logic |
_cobject.py |
CObject: pointer ownership, refcounting, and the identity cache that every wrapper class inherits |
ei.py, eis.py, oeffis.py |
The public API: Python classes, enums and dataclasses over the raw calls |
portal.py sits outside this stack entirely —
there is no C library behind it, so no _capi binding and no CObject. It
talks D-Bus directly through PyGObject (Gio/GLib, imported lazily the same
way the C libraries are loaded lazily) and only ever produces a plain fd,
which is where it hands off to ei.Sender.create_for_fd().
It is the smallest file with the most consequence: get wrap() vs adopt(),
the staticmethod() wrapping of _ref_func/_unref_func, or the
_wrappable flag wrong and the failure is a use-after-free or a segfault
rather than a traceback. Every non-obvious line there carries a comment
explaining what breaks without it.
_capinames drop the C prefix.ei_unref()is_capi.libei.unref(),eis_device_configure_name()is_capi.libeis.device_configure_name(). The module says which library it is, so repeating it in every name would only add noise.- Wrapper instances are passed straight to C calls.
CObjectdefines_as_parameter_, which ctypes consults automatically, so_capi.libei.device_frame(self, timestamp)works without unwrapping a pointer out ofselfby hand.
The ctypes layer binds 250 of the 302 functions the three libraries export as of 1.6.0 (libei 109/132, libeis 131/158, liboeffis 10/12). What is left out is deliberate:
*_get_user_data()/*_set_user_data()— the Python wrapper object is where you keep state.- The
*_ref()/*_unref()pairs —CObjecthandles those for you. - The logging-context accessors and
*_event_type_to_string(). - The NUL-terminated
*_device_text_utf8()— the_with_lengthform is bound instead, so text containing a NUL is not truncated. ei_new()— superseded byei_new_sender()/ei_new_receiver().*_clock_set_now_func().
One accessor pair sits on the line between bound and not. Of the
*_get_context() accessors the headers export, the two device variants —
ei_device_get_context and eis_device_get_context — are bound and are
used internally: when the caller gives frame() no timestamp, it reads
the device's own context to get one (ei_now() needs a context). A caller
who passes a timestamp never reaches the accessor. The seat, keymap and
client variants stay unbound, and what the
package never does with the two it binds is wrap the returned pointer into
a Context object: a context only ever reaches Python through its own
create_for_*(), never from a raw pointer, so there is no public
Device.context accessor to hand one back.
The gesture and stylus functions that libei's main branch adds -- 46 in
libei and 51 in libeis against 1.6.0's headers, counted 2026-09-30: the
swipe, pinch and hold senders and event getters, and the whole stylus
protocol -- are also unbound. Nothing that ships today exports them, so nothing here could be
verified against a real library — which is the bar every other binding in this
package was held to.
Written from scratch, taking its overall shape from
snegg (the reference bindings by
libei's own author), with different priorities suited to being embedded as a
dependency rather than used for prototyping. ../vs-snegg.md
covers the specifics, including two signature issues found by cross-checking
against the real libei source.