aioxlib

Human-friendly asyncio interface to the X11 protocol

aioxlib is a pure-Python library that speaks the X11 wire protocol over asyncio. It aims to make displays, windows, drawing, events, and extensions feel natural in async Python—without blocking the event loop and without linking to libX11.

Inspired by linuxpy (same author): a clean high-level API with protocol details still available when you need them.

Features

• Fully asynchronous connection to the X server (Unix socket or TCP)
• High-level objects: Display, Screen, Window, GC, resources
• Event stream via async for event in display.events()
• Windows: create/map/configure/reparent, WM name & delete handling
• Core drawing: rectangles, arcs, segments, points, text, images
• RENDER: pictures, solid fills, gradients, triangles/trapezoids/strips, glyphs
• MIT-SHM for high-throughput image transfer
• DOUBLE-BUFFER, BIG-REQUESTS, plus GLX / DRI3 / Present helpers
• Atoms, properties (with type encode/decode), fonts, colormaps
• Python ≥ 3.12, GPLv3, no third-party runtime dependencies
• Implementation in a single module

Installation

pip install aioxlib

From source:

git clone https://codeberg.org/tiagocoutinho/aioxlib.git
cd aioxlib
pip install -e .

Quick start

import asyncio
import aioxlib


async def main():
    wnd = await aioxlib.create_window(
        width=640,
        height=480,
        title="Hello from aioxlib",
    )
    await wnd.show()

    async for event in aioxlib.events():
        if wnd.is_delete_window(event):
            break


asyncio.run(main())

create_window(..., delete_on_close=True) (the default) registers WM_DELETE_WINDOW. Use Window.is_delete_window(event) in the event loop.

Documentation

User guide and full API reference (Material for MkDocs + mkdocstrings):

pip install mkdocs mkdocs-material 'mkdocstrings[python]'
mkdocs serve

Then open http://127.0.0.1:8000/.

Examples

python examples/basic.py

API overview

display = await aioxlib.get_display()  # or get_display(":0")
async with display:
    screen = display.default_screen()

    wnd = await screen.create_window(
        width=800,
        height=600,
        title="Demo",
        event_mask=aioxlib.EventMask.Exposure,
    )
    await wnd.show()

    gc = await wnd.create_gc(foreground=0x00FFFF, background=0)
    await wnd.poly_fill_rectangles(gc, [(10, 10, 100, 50)])
    await wnd.poly_fill_arcs(gc, [(50, 50, 80, 80, 0, 360 * 64)])

    # Optional: RENDER
    render = await display.query_extension("RENDER")
    if render:
        formats = await render.query_picture_formats()
        ...

    async for event in display.events():
        if wnd.is_delete_window(event):
            break
        if event["code"] == aioxlib.EventType.Expose:
            ...

Events are dicts; core codes are in aioxlib.EventType.

Properties

await wnd.change_property(aioxlib.Atom.WM_NAME, aioxlib.Atom.STRING, data="Title")
reply = await wnd.get_property(aioxlib.Atom.WM_NAME)
print(reply["value"])  # decoded str / list[int] / …

Requirements

• Python ≥ 3.12
• An X11 server (Xorg, Xwayland, Xephyr, …)
• $DISPLAY set, or pass the display URI explicitly

Development

pip install -e .
pip install pytest pytest-asyncio pytest-cov
pytest

License

GPLv3 or later — see LICENSE.

Author

José Tiago Macara Coutinho
https://codeberg.org/tiagocoutinho

aioxlib 0.1.0 — feedback and contributions welcome.