#69 - Add Python bindings API reference

.claude/rules/docs-sync.md

@@ -12,10 +12,12 @@ When the user is committing, pushing, or otherwise wrapping up a change that tou
 - `include/daqiri/common.h` / `include/daqiri/daqiri.h` — public free-function API (`get_rx_burst`, `get_packet_ptr`, `set_udp_header`, etc.). Any signature change, new function, removed function, or changed parameter semantics may need updating in:
   - `docs/api-reference/index.md` (API guide: 6-step application lifecycle)
   - `docs/api-reference/cpp.md` (C++ API usage guide and function reference)
+  - `docs/api-reference/python.md` (Python bindings reference — when the binding surface changes alongside the C++ API)
   - `docs/concepts.md` (when the change introduces or renames a user-facing concept — burst, segment, flow, queue, memory region, etc.)
   - `AGENTS.md` (Architecture section's API summary)
-- `include/daqiri/types.h` — public types (`BurstParams`, `Status`, `NetworkConfig`, enums like `MemoryKind`, `Direction`, `SocketProtocol`). Struct field changes, new enum values, or renamed types may need updating in the API docs, `docs/concepts.md` (terminology), and `AGENTS.md` (Architecture / BurstParams discussion).
+- `include/daqiri/types.h` — public types (`BurstParams`, `Status`, `NetworkConfig`, enums like `MemoryKind`, `Direction`, `SocketProtocol`). Struct field changes, new enum values, or renamed types may need updating in the API docs (`docs/api-reference/cpp.md`, `docs/api-reference/python.md`), `docs/concepts.md` (terminology), and `AGENTS.md` (Architecture / BurstParams discussion).
 - `src/manager.h` — `Manager` virtual interface and `ManagerFactory`. Changes here affect the backend abstraction docs in `docs/api-reference/cpp.md`, the backends section of `docs/concepts.md`, and the Manager-abstraction subsection in `AGENTS.md`.
+- `python/daqiri_common_pybind.cpp` — pybind11 binding surface. Any added/removed/renamed `m.def(...)`, changed pybind signature, new enum/class binding, or changed GIL-release behavior may need updating in `docs/api-reference/python.md` (function reference tables, enums/classes tables, GIL Behavior section).
 
 ### Backend and build changes (medium impact)
 - `src/managers/*/` — adding a new backend or changing backend behavior may need updating in:
@@ -70,13 +72,15 @@ When the user is committing, pushing, or otherwise wrapping up a change that tou
 
 | Source file | Docs to check |
 |---|---|
-| `include/daqiri/common.h` / `include/daqiri/daqiri.h` | `docs/api-reference/index.md`, `docs/api-reference/cpp.md`, `docs/concepts.md`, `AGENTS.md` |
-| `include/daqiri/types.h` | `docs/api-reference/index.md`, `docs/api-reference/cpp.md`, `docs/concepts.md`, `AGENTS.md` |
+| `include/daqiri/common.h` / `include/daqiri/daqiri.h` | `docs/api-reference/index.md`, `docs/api-reference/cpp.md`, `docs/api-reference/python.md`, `docs/concepts.md`, `AGENTS.md` |
+| `include/daqiri/types.h` | `docs/api-reference/index.md`, `docs/api-reference/cpp.md`, `docs/api-reference/python.md`, `docs/concepts.md`, `AGENTS.md` |
 | `src/manager.h` | `docs/api-reference/cpp.md`, `docs/concepts.md`, `AGENTS.md` |
 | `src/managers/*/` | `docs/getting-started.md`, `docs/concepts.md` (backend list + maturity), `docs/api-reference/configuration.md`, `docs/tutorials/configuration-walkthrough.md`, `README.md`, `AGENTS.md` |
 | `src/CMakeLists.txt` | `docs/getting-started.md`, `AGENTS.md`, `README.md` |
 | `src/kernels.cu` | `docs/tutorials/benchmarking_examples.md`, `AGENTS.md` |
+| `python/daqiri_common_pybind.cpp` | `docs/api-reference/python.md`, `AGENTS.md` |
 | `examples/*.cpp` | `docs/tutorials/benchmarking_examples.md`, `docs/tutorials/configuration-walkthrough.md`, `AGENTS.md` |
 | `examples/*.yaml` | `docs/tutorials/benchmarking_examples.md`, `docs/tutorials/configuration-walkthrough.md`, `AGENTS.md` |
+| `examples/*.py` | `docs/api-reference/python.md`, `AGENTS.md` |
 | `mkdocs.yml` | `docs/index.html` (nav links) |
 | Any `docs/*` rename/move | `README.md` (Documentation table), `AGENTS.md` (Documentation section), `mkdocs.yml`, `docs/index.html` |

AGENTS.md

@@ -94,15 +94,16 @@ The web docs live in `docs/` and are built with [MkDocs Material](https://squidf
 - `docs/getting-started.md` — system requirements, build instructions, CMake options
 - `docs/concepts.md` — terminology glossary (kernel bypass, GPUDirect, packet/burst/segment, flow/queue, memory region, zero-copy ownership, RX reorder). Meant to be opened in parallel with the rest of the docs.
 - `docs/api-reference/index.md` — API guide (6-step application lifecycle, configuration-first model)
-- `docs/api-reference/configuration.md`, `docs/api-reference/cpp.md` — YAML schema and C++ API docs
+- `docs/api-reference/configuration.md`, `docs/api-reference/cpp.md`, `docs/api-reference/python.md` — YAML schema, C++ API, and Python bindings docs
 - `docs/tutorials/` — tutorial walkthroughs (system config, benchmarking, config files)
 - `docs/stylesheets/extra.css` — custom theme overrides
 
 **Keeping docs in sync with code:** before committing changes, scan for the recurring drift hotspots:
 - **Backend list** (`src/managers/*/`) — README Backends table, `docs/getting-started.md`, `docs/concepts.md` (Kernel Bypass section + Backend Maturity admonition), `docs/api-reference/configuration.md`
 - **CMake options / `DAQIRI_MGR` default** (`src/CMakeLists.txt:137`) — README Quick Start, `docs/getting-started.md`, this file's Build & run section
 - **Benchmark binary or YAML names** (`examples/`) — the benchmark table above, `docs/tutorials/benchmarking_examples.md`, and the "Choosing an example config" decision tree in `docs/tutorials/configuration-walkthrough.md` (every YAML must have a leaf; CI's `scripts/check_doc_refs.py` enforces coverage)
-- **Public API include** (`#include <daqiri/daqiri.h>`; source files under `include/daqiri/`) — `docs/api-reference/index.md`, `docs/api-reference/cpp.md`; if the change adds or renames a user-facing concept, also `docs/concepts.md`
+- **Public API include** (`#include <daqiri/daqiri.h>`; source files under `include/daqiri/`) — `docs/api-reference/index.md`, `docs/api-reference/cpp.md`, `docs/api-reference/python.md`; if the change adds or renames a user-facing concept, also `docs/concepts.md`
+- **Python bindings** (`python/daqiri_common_pybind.cpp`) — `docs/api-reference/python.md` (function reference tables, enums/classes tables, GIL Behavior section)
 - **Doc reorganization** (any rename in `docs/`) — `docs/index.html` landing page, `mkdocs.yml` nav, README Documentation table
 
 The full mapping with rationale lives in the docs-sync agent rule. Internal-link, anchor, and nav drift is enforced by CI (`.github/workflows/docs.yml`); content drift (stale binary names, defaults) is still a manual check at commit time.

README.md

@@ -83,6 +83,7 @@ Reference material for the DAQIRI codebase:
 - [API Guide](https://nvidia.github.io/daqiri/api-reference/) — Six-step DAQIRI application lifecycle and configuration-first model
 - [Configuration YAML Reference](https://nvidia.github.io/daqiri/api-reference/configuration/) — Full YAML config reference for all backends
 - [C++ API Usage](https://nvidia.github.io/daqiri/api-reference/cpp/) — C++ RX/TX workflows, buffer lifecycle, file writing, utilities, and status codes
+- [Python API Usage](https://nvidia.github.io/daqiri/api-reference/python/) — Python bindings, workflow examples, enums, config classes, and helper functions
 - [Contributing](CONTRIBUTING.md) — Contribution guidelines, coding standards, DCO sign-off
 
 ## Tutorials

docs/api-reference/index.md

@@ -46,8 +46,8 @@ The typical DAQIRI application lifecycle has six steps:
 6. **Shut down DAQIRI** before process exit (`shutdown`).
 
 Each step maps directly to a section of the
-[C++ API Usage](cpp.md) page. The buffer-release step in particular is
-load-bearing — see
+[C++ API Usage](cpp.md) and [Python API Usage](python.md) pages. The
+buffer-release step in particular is load-bearing — see
 [Zero-Copy Ownership](../concepts.md#zero-copy-ownership) on the
 Concepts page for why missed frees cause queue drops.
 
@@ -59,5 +59,8 @@ Concepts page for why missed frees cause queue drops.
   type, and its valid values.
 - [C++ API Usage](cpp.md) — initialization, RX/TX workflows, buffer
   lifecycle, file writing, utilities, and the full C++ function reference.
+- [Python API Usage](python.md) — the same workflow through the pybind11
+  bindings, including GIL behavior, tuple return shapes, and the full
+  Python function reference.
 - [Configuration walkthrough tutorial](../tutorials/configuration-walkthrough.md)
   — annotated YAML walkthrough with a use-case decision tree.