aioxlib
Human-friendly asyncio interface to the X11 protocol
aioxlib is a pure-Python, asyncio-native client for the X11 wire protocol.
Open displays, create windows, draw with GCs and the RENDER extension, and stream
events — without blocking the event loop and without linking to libX11 or xcb.
Examples shipped with the library: Game of Life · 3D wireframe
Why aioxlib?
| aioxlib | python-xlib | xcffib / xpyb | |
|---|---|---|---|
| Language | Pure Python | Pure Python | C (libxcb) + Python |
| Async | asyncio first | Blocking / threads | Blocking |
| Dependencies | None at runtime | None | libxcb |
| Protocol access | Pack/unpack helpers exposed | High-level only | Low-level |
| Extensions | RENDER, MIT-SHM, DBE, GLX, … | Many | Many |
Inspired by linuxpy (same author): a clean high-level API when you want it, full protocol detail when you need it.
Requirements
- Python ≥ 3.12
- An X server (local or remote) and network/socket access to it
(
$DISPLAYor an explicit URI)
No third-party Python packages are required at runtime.
Installation
pip install aioxlib
Quick start
Functional API (simplest)
import asyncio
import aioxlib
async def main():
wnd = await aioxlib.create_window(640, 480, title="Hello from aioxlib")
await wnd.show()
async for event in aioxlib.events():
if wnd.is_delete_window(event):
break
asyncio.run(main())
Explicit display (object API)
import asyncio
import aioxlib
async def main():
display = await aioxlib.get_display()
async with display:
screen = display.default_screen()
wnd = await screen.create_window(640, 480, title="Hello from aioxlib")
await wnd.show()
async for event in display.events():
if wnd.is_delete_window(event):
break
asyncio.run(main())
Features
- Windows & drawing — create/map/configure windows, GCs, polylines, rectangles, arcs, text, images
- Events — non-blocking
async for event in display.events()stream - Properties & atoms —
WM_NAME, protocols, custom properties - Extensions — BIG-REQUESTS, RENDER, MIT-SHM, DBE, GLX, RANDR, DRI3, Present
- Pipeline — batch requests with
async with display.pipeline(): … - Protocol transparent — opcodes, pack/unpack helpers stay accessible
Examples
# clone the repo, then:
python examples/basic.py
python examples/game_of_life.py # Conway's Life (numpy)
python examples/3d.py # rotating 3D mesh
python examples/video_shm_dbe.py # shared memory + double buffering
| Example | What it shows |
|---|---|
basic.py |
Window + delete protocol |
game_of_life.py |
Animated cellular automaton |
3d.py |
Perspective projection & wireframe |
render.py / tristrip.py |
RENDER extension |
shm.py / video_shm*.py |
MIT-SHM image transfer |
cube_dbe.py |
Double buffering (DBE) |
keyboard.py |
Key events |
Package layout
| Module | Contents |
|---|---|
aioxlib (root) |
Functional API + get_display + common constants |
aioxlib.constants |
X11 constants and enumerations |
aioxlib.protocol |
Pack/unpack helpers |
aioxlib.connection |
Socket connection, Xauthority |
aioxlib.display |
Display, Screen, Window, GC, Pipeline |
aioxlib.render / shm / dbe / … |
Extensions |
Classes such as Display, Window, and EventType are imported from their
modules (or from the root where re-exported).
Root functional API (selection)
| Function | Role |
|---|---|
get_display / get_default_display |
Open connection |
create_window, map_window, … |
Windows |
events(), pipeline() |
Event stream / batched writes |
flush, query_extension, get_atom, … |
Display operations |
close_default_display |
Tear down default connection |
Documentation
- Online: aioxlib.readthedocs.io
- Local:
pip install --group docs # or: pip install mkdocs mkdocs-material 'mkdocstrings[python]'
mkdocs serve
License
GPLv3 or later — see LICENSE.
Author
José Tiago Macara Coutinho https://codeberg.org/tiagocoutinho
Metadata
Release files for aioxlib 0.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aioxlib-0.10.0.tar.gz | 148.9 kB | Without provenance | Details for aioxlib-0.10.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aioxlib-0.10.0-py3-none-any.whl | Python 3 | none | any | Details for aioxlib-0.10.0-py3-none-any.whl |
Total release size: 250.7 kB
Release files / aioxlib-0.10.0.tar.gz
| Download URL | aioxlib-0.10.0.tar.gz |
|---|---|
| Size | 148.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1658ae24109c7d0e5a991eedd5dd5bed2715003e75127d0766618e0170b08f11
|
|
BLAKE2b-256 checksum How to use checksums |
92bda1cef213d3c795ff21895d529b2d73e6e93f0eff2413c2ab73cbe4e2b1e7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.9
|
Release files / aioxlib-0.10.0-py3-none-any.whl
| Download URL | aioxlib-0.10.0-py3-none-any.whl |
|---|---|
| Size | 101.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2c0fca4a0543bd5b3e1a341712d0eb0f0e7efd9ae3d4d3ab88c065dc83639f4e
|
|
BLAKE2b-256 checksum How to use checksums |
51ab1a040168d3b9dbe14eebe3f47d8132d6e21e5c21e0487a4a9710b3d6d8e9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.9
|
Security for aioxlib 0.10.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.