# cuframes — Python bindings

Status: **WIP** (Phase 0 skeleton — issue [gx/cuframes#6](http://server:3000/gx/cuframes/issues/6))

Это пакет Python-обёрток над `libcuframes` (C ABI). Цель — позволить
downstream ML/CV пайплайнам (yolo-world-detector, zone-motion, custom
скриптам) подписываться на cuframes без CPU round-trip: получать NV12
frames прямо как CUDA pointer / `torch.Tensor` (DLPack export, zero-copy).

## Текущий статус (что уже работает в этом skeleton)

- Module import: `import cuframes` загружает `_native.so`
- Версия: `cuframes.version_string()`, `cuframes.protocol_version()`
- Enums: `PixelFormat`, `SubscriberMode`
- Иерархия исключений: `CuframesError` + 8 subclasses (publisher gone,
  frame timeout, device lost, и т. д.)

## Что в работе (см. tasks #198-#202)

- [ ] `CuframesSubscriber` + `CuframesFrame` lifecycle
- [ ] DLPack export → `torch.from_dlpack`, `cupy.from_dlpack`
- [ ] Context manager (`with cuframes.subscribe(key) as sub:`)
- [ ] Per-subscriber CUDA stream
- [ ] Health/stats properties (`ring_occupancy`, `drop_count`)
- [ ] Thread-safety contract документация

## Build (dev)

Standalone wheel:

```bash
cd python/
pip install -e . --no-build-isolation
```

Через корневой CMake-проект (вместе с libcuframes):

```bash
cmake -B build -DBUILD_PYTHON_BINDINGS=ON
cmake --build build -j
```

## Зависимости

- `libcuframes` ≥ 0.4 (линкуется из соседнего CMake target)
- CUDA Toolkit 12+
- `pybind11` 2.13+ (берётся через FetchContent при CMake-сборке)
- Python 3.10+
- Опционально: `torch>=2.4` или `cupy-cuda12x>=13` для DLPack-потребителей

## Лицензия

LGPL-2.1+ (как у libcuframes).