Metadata-Version: 2.4
Name: aioxlib
Version: 0.0.3
Summary: Human friendly interface to XLib subsystems using asyncio python
Author-email: Jose Tiago Macara Coutinho <coutinhotiago@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Documentation, https://codeberg.org/tiagocoutinho/aioxlib/
Project-URL: Homepage, https://codeberg.org/tiagocoutinho/aioxlib/
Project-URL: Repository, https://codeberg.org/tiagocoutinho/aioxlib/
Keywords: x11,asyncio
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Multimedia :: Video :: Capture
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# aioxlib

**Human-friendly asyncio interface to the X11 protocol**

`aioxlib` is a pure-Python library that talks the X11 wire protocol over asyncio.  
It aims to make working with X displays, windows, graphics contexts, events, and images feel natural in modern async Python code—without blocking the event loop.

Inspired by the style of [linuxpy](https://github.com/tiagocoutinho/linuxpy) (also by the same author), it provides a clean, high-level API while still exposing the underlying protocol details 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()`
- Window creation, mapping, attributes, WM properties (`WM_NAME`, `WM_PROTOCOLS`, …)
- Graphics Context (GC) drawing: rectangles, text (`put_text`), images
- MIT-SHM support for high-performance image transfer
- Atom interning, extensions querying, fonts listing
- Python ≥ 3.12, GPLv3
- No external dependencies
- Code in a single file

## Installation

From within your favorite python environment:

```bash
pip install aioxlib
```

## Quick start

```python
import asyncio
import aioxlib

async def main():
    display = await aioxlib.get_display()
    async with display:
        screen = display.default_screen()
        wnd = await screen.create_window(width=640, height=480)
        await wnd.map()
        await wnd.set_name("Hello from aioxlib")

        # Handle window close
        protocols = await display.get_atom("WM_PROTOCOLS")
        delete = await display.get_atom("WM_DELETE_WINDOW")
        await wnd.set_wm_protocols([delete])

        async for event in display.events():
            if (event["code"] == aioxlib.Event.ClientMessage
                    and event["type"] == protocols
                    and event["data"][0] == delete):
                break

asyncio.run(main())
```

## Examples

The `examples/` directory contains several demos:

| File            | Description                              |
|-----------------|------------------------------------------|
| `basic.py`      | Minimal window + close handling          |
| `text.py`       | Draw text on expose                      |
| `grid.py`       | Fill a grid of rectangles                |
| `point.py`      | Points API                               |
| `segments.py`   | Line segments                            |
| `3d.py`         | Simulate 3d rendering                    |
| `shm.py`        | MIT-SHM image transfer                   |
| `video.py`      | Live video from a V4L2 camera            |
| `video_shm.py`  | Video + shared-memory path               |

Run any of them with:

```bash
python examples/basic.py
```

## API overview

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

    wnd = await screen.create_window(...)      # or display.create_window(...)
    await wnd.map()
    await wnd.set_name("…")
    await wnd.set_wm_protocols([...])

    gc = await wnd.create_gc(foreground=…, background=…)
    await gc.poly_fill_rectangles([...])
    await gc.put_text(x, y, "text")
    await wnd.draw_image(gc, x, y, w, h, depth, data)

    async for event in display.events():
        ...
```

Events are plain dicts with a `"code"` field matching `aioxlib.Event.*`.

## Requirements

- Python ≥ 3.12
- An X11 server (Xorg, Xwayland, …)
- `$DISPLAY` set (or pass the display string explicitly)

## License

GPLv3 or later — see [LICENSE](LICENSE).

## Author

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

---

*Early beta (v0.0.2). Feedback and contributions welcome!*
