Metadata-Version: 2.4
Name: aioxlib
Version: 0.7.2
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://aioxlib.readthedocs.io/en/latest/
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
License-File: LICENSE
Dynamic: license-file

# aioxlib

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

[![PyPI](https://img.shields.io/pypi/v/aioxlib.svg)](https://pypi.org/project/aioxlib/)
[![Python Versions](https://img.shields.io/pypi/pyversions/aioxlib.svg)](https://pypi.org/project/aioxlib/)
[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Docs](https://img.shields.io/badge/docs-readthedocs-blue.svg)](https://aioxlib.readthedocs.io)

`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.

<p align="center">
  <img src="docs/images/game_of_life.gif" style="height: 300px;" alt="Conway's Game of Life on X11 via aioxlib"/>
  &nbsp;
  <img src="docs/images/3d_cube.gif" style="height: 300px;" alt="Rotating 3D wireframe via aioxlib"/>
</p>

<p align="center"><em>Examples shipped with the library: Game of Life · 3D wireframe</em></p>

## 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](https://github.com/tiagocoutinho/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
  (`$DISPLAY` or an explicit URI)

No third-party Python packages are required at runtime.

## Installation

```bash
pip install aioxlib
```

## Quick start

### Functional API (simplest)

```python
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)

```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(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

```bash
# 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](https://aioxlib.readthedocs.io)
- Local:

```bash
pip install --group docs   # or: pip install mkdocs mkdocs-material 'mkdocstrings[python]'
mkdocs serve
```

## License

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

## Author

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