Metadata-Version: 2.4
Name: aioxlib
Version: 0.5.0
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

# 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)

`aioxlib` is a pure-Python library that speaks the X11 wire protocol over
asyncio—without blocking the event loop and without linking to libX11.

## Documentation

- Online: [aioxlib.readthedocs.io](https://aioxlib.readthedocs.io)
- Local: `pip install --group docs && mkdocs serve`

## Installation

From within your favorite python environment:

```bash
pip install aioxlib
```

## Quick start

The **root package** exposes the functional API and `get_display` only:

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

## Package layout

| Module | Contents |
|--------|----------|
| **`aioxlib`** (root) | Constants/enums + functional API + `get_display` |
| `aioxlib.constants` | X11 constants and enumerations |
| `aioxlib.protocol` | Constants, enums, pack/unpack |
| `aioxlib.connection` | Socket connection, Xauthority |
| `aioxlib.resource` | Resource, Drawable, ResourceManager |
| `aioxlib.display` (Window, Screen, GC, …) | Window, Screen, GC |
| `aioxlib.display` | Display, Pipeline |
| `aioxlib.render` / `shm` / `dbe` / … | Extensions |

### 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 |

Classes such as `Display`, `Window`, and `EventType` are **not** re-exported
from the root; import them from their modules.

## Documentation

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

## Examples

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

## Requirements

- Python ≥ 3.12
- An X11 server and `$DISPLAY` (or an explicit URI)

## License

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

## Author

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