#69 - Add Python bindings API reference

[dleshchev]

Summary

• Adds docs/api-reference/python.md documenting the pybind11 bindings: RX/TX workflows mirroring cpp.md's step-by-step structure, reordered RX, file writes, socket/RDMA helpers, GIL behavior, and a full function / enum / class reference derived from python/daqiri_common_pybind.cpp.
• Wires the new page through mkdocs.yml nav, README.md docs table, docs/index.html footer, AGENTS.md doc structure list, and the docs-sync agent rule.
• Updates docs/api-reference/index.md so the six-step lifecycle and the "See also" section link the Python page alongside the C++ page.
• Extends scripts/check_doc_refs.py's binary-name regex to also exclude .py so the link to examples/daqiri_bench_raw_tx_rx.py is not mistaken for a missing binary.

Context

This builds on #94 (already merged), which restructured the API reference under docs/api-reference/ and split it into index.md, cpp.md, and configuration.md. With this PR landed, the reference covers the three surfaces a user actually touches — C++, Python, and the YAML schema — completing the Python-bindings docs work tracked in #69 and the broader API documentation effort tracked in #9.

The Python page deliberately mirrors cpp.md's section flow (Initialization → Receiving Packets w/ RX 1/2/3 → Reordered RX → Transmitting Packets w/ TX 1/2/3 → Writing Bursts to Storage → Socket and RDMA → Utility Functions → Function Reference) so a reader switching between the two surfaces sees the same shape, with Python-specific additions for GIL behavior and pointer/buffer semantics.

Closes #9.
Closes #69.

Test plan

• python3 scripts/check_doc_refs.py passes
• mkdocs build --strict passes (no broken links, missing anchors, or unrecognized nav entries)
• Browse to api-reference/python/ and visually confirm: TOC renders, code blocks highlight, internal links to cpp.md, configuration.md, ../concepts.md (incl. #zero-copy-ownership and #rx-packet-aggregation-and-reorder anchors) all resolve
• Spot-check the function-reference tables against python/daqiri_common_pybind.cpp — every m.def/m.attr/py::enum_/py::class_ is represented; GIL section lists every py::gil_scoped_release site

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

Adds docs/api-reference/python.md, a comprehensive Python bindings reference mirroring cpp.md's structure, and wires it into mkdocs.yml, README.md, docs/index.html, AGENTS.md, and the docs-sync agent rule. The check_doc_refs.py binary-name regex is also extended to exclude .py filenames.

• New Python API page — covers initialization, RX/TX workflows, reordered bursts, file writes, socket/RDMA helpers, GIL behavior, and a full function/enum/class reference derived from python/daqiri_common_pybind.cpp.
• RDMA snippet leaks burst metadata — the RDMA example calls create_tx_burst_params() but ends without a send_tx_burst or free_tx_metadata call; the head commit claims to fix both socket and RDMA burst leaks but only addressed the socket side.
• HEAD commit missing DCO sign-off — commit 18b702d has no Signed-off-by: trailer; the two earlier commits in this PR are correctly signed.

Confidence Score: 3/5

Two issues need fixing before merge: the RDMA documentation example leaks burst metadata, and the HEAD commit is missing its DCO sign-off trailer.

The RDMA code snippet in the new Python reference page calls create_tx_burst_params() but never reaches a send_tx_burst or free_tx_metadata call. Users following this example will drain the TX metadata pool in the same silent way the custom rules warn about. Additionally, the HEAD commit (18b702d) has no Signed-off-by: trailer, which blocks merge under the project's DCO policy.

docs/api-reference/python.md — RDMA snippet at line 406 needs a matching free or a complete send/free path to close the burst lifecycle.

Important Files Changed

Filename	Overview
docs/api-reference/python.md	New Python API reference page — well-structured and mirrors cpp.md, but the RDMA snippet at line 406 calls create_tx_burst_params() without a matching free or send, leaking burst metadata.
scripts/check_doc_refs.py	Correctly extends BIN_RE negative lookahead to also exclude .py extensions, preventing daqiri_bench_raw_tx_rx.py from being flagged as a missing binary.
mkdocs.yml	Adds Python API Usage nav entry alongside C++ API Usage — correct placement and path.
.claude/rules/docs-sync.md	Correctly adds python.md to the doc-sync trigger table for common.h, types.h, and the new python/daqiri_common_pybind.cpp and examples/*.py rows.
AGENTS.md	Adds python.md to the doc structure list and extends the Public API include drift hotspot — consistent with the rest of the PR.
README.md	Adds Python API Usage entry to the Documentation table — correct URL and description.
docs/api-reference/index.md	Updates lifecycle description and See Also section to link Python page alongside C++ page — clean wording.
docs/index.html	Adds Python API Usage footer link matching the mkdocs nav addition — consistent.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[create_tx_burst_params] --> B[set_header]
    B --> C{is_tx_burst_available?}
    C -- No --> D[free_tx_metadata]
    C -- Yes --> E[get_tx_packet_burst]
    E -- FAIL --> F[free_tx_metadata]
    E -- SUCCESS --> G[fill packets]
    G --> H[send_tx_burst]
    H -- FAIL --> I[free_all_packets_and_burst_tx]
    H -- SUCCESS --> J[worker thread owns burst]

    K[RDMA example gap] -.->|create_tx_burst_params + rdma_set_header only - no send or free shown| A

Loading

_{Reviews (2): Last reviewed commit: "#69 - fixing the TX burst leak in python..." | Re-trigger Greptile}

[greptile-apps]

TX burst leak on send_tx_burst failure in socket example

send_tx_burst is called without capturing its return value. When get_tx_packet_burst succeeds, packet buffers are allocated from the TX pool. If send_tx_burst subsequently fails, the tx_burst (with those buffers) is never freed — silently draining the TX packet pool until the NIC starts dropping traffic. Per the project's BurstParams zero-copy invariant, every exit path through create_tx_burst_params → get_tx_packet_burst must have a matching free. The corresponding pattern in TX Step 3 (earlier in this same doc) correctly checks the return value; this example should too.

[chloecrozier]

Ran the three CI scripts locally, all passed:

• mkdocs build --strict
• scripts/check_html_links.py site
• scripts/check_doc_refs.py

Also checked:

• The .py lookahead in check_doc_refs.py is actually needed. python.md links examples/daqiri_bench_raw_tx_rx.py.
• python.md function tables match every m.def, m.attr, py::enum_, and py::class_ in python/daqiri_common_pybind.cpp. GIL section lists every gil_scoped_release site.
• Wiring is in place: mkdocs.yml nav, docs/index.html footer, README.md, AGENTS.md, and .claude/rules/docs-sync.md all point at python.md.
• index.md links python.md from the six-step lifecycle and See Also.

One thing to fix as per greptile:

• python.md line 394 (Socket and RDMA TX snippet): the example calls send_tx_burst without checking the return value, so on a send failure the buffers from get_tx_packet_burst never get freed and eventually drain the TX pool (forcing the need for a manual free). The TX Step 3 example at line 333 already shows the right pattern, copy that check-and-free into this snippet too.