python: skeleton pybind11 bindings (issue #6 task #197)

Каркас Python-пакета `cuframes`:
- python/pyproject.toml — scikit-build-core конфиг
- python/CMakeLists.txt — pybind11 module через FetchContent
- python/src/_native.cpp — module entry, error таксономия,
  enum mirrors (PixelFormat, SubscriberMode), version
- python/cuframes/__init__.py — re-export публичного API
- python/tests/test_smoke.py — smoke tests без real subscribe
- python/README.md — статус + build instructions
- CMakeLists.txt — подключение python/ при BUILD_PYTHON_BINDINGS=ON

Реальный subscriber/frame wrapper в следующих коммитах
(tasks #198-#202).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
2026-06-13 12:59:04 +01:00
parent 655649f4d8
commit a7da4ea728
8 changed files with 406 additions and 0 deletions
+53
View File
@@ -0,0 +1,53 @@
# 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).