apache / apache/datafusion-python

Give the two FFI example crates a runnable entry point

未關閉
#1,727 0 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視
enhancement python
主要語言
Python
星號
604
分支
174
平均合併
1 天 7 小時
30 天內合併 PR
4

描述

Neither `datafusion-ffi-example` nor `datafusion-ffi-query-planner-example` has a script you can run. They are 51 and 47 pytest assertions respectively. Meanwhile `user-guide/data-sources.md:219` calls the first one a **"user example"** and sends Python users there from the user guide, and `io/table_provider.md:30` calls it "a complete example". We promise a runnable example and deliver a test suite.

**Precedent:** `examples/tpch/` — the script is the artifact and a pytest keeps it honest. CI already runs `pytest python/tests/_test*.py` in each crate directory (`test.yml:136-150`), so a driver test needs **zero workflow changes**.

Layout per crate: `run_demo.py` at the tree root, parallel to the existing `examples/distributed/run_tpch.py`, and a driver at `python/tests/_test_run_demo.py` that runs it via `subprocess.run([sys.executable, script])` and asserts on anchor lines. Subprocess rather than `import_module` or `runpy`, because it proves the thing being asked for: that it runs standalone with no pytest around it.

Each script should open with an import guard that turns the one real failure mode into an instruction rather than a traceback:

```python
try:
from datafusion_ffi_example import MyTableProvider
except ImportError:
sys.exit("build the extension first:\n uv run maturin develop\nSee README.md.")
```

- [ ] **`datafusion-ffi-example/run_demo.py`** — walk the conformance matrix in numbered sections: table provider, functions, catalog provider, config extension, codec round-trip, then *the same bytes decoded a second time*. That last section is only truthful after the logical-codec sub-issue lands, and it is the one place in the repository where the guide's central rule is demonstrated rather than asserted.
- [ ] **`datafusion-ffi-query-planner-example/run_demo.py`** — print plans, not rows. Planner nesting is understood by seeing the indented tree, and the existing tests assert on plan strings they never show. Cover the logical plan handed to the planner, the physical plan returned, the effect of `SET ffi_query_planner.max_rows`, and two planners nesting. Use `.display_indent()`.
- [ ] **`Role:` header on each tree's README**, so the label survives the click from `examples/README.md`, which already distinguishes the trees but loses the distinction as soon as you follow the link. Three lines: what this tree is, where to go if you are learning the protocol, and how to run it.

**Scope note:** make them runnable, but do not promise `datafusion-ffi-example` reads as a tutorial. It is a coverage matrix — `.ai/skills/check-upstream/SKILL.md:455` instructs adding every new FFI type to it — so it grows under protocol pressure rather than narrative need. The planner crate is single-topic and can carry the stronger claim.

貢獻指南

這個儲存庫沒有索引到貢獻指南

研究方向

從 examples/tpch/run_tpch.py、兩個 FFI crates 中 python/tests 下現有的 pytest 檔案以及 test.yml:136-150 開始,以確認測試命令。新增每個 root run_demo.py、帶有 anchor assertions 的 subprocess driver 以及 README Role 標題;完成的標準是兩個腳本都能 standalone 執行,且其 driver 測試通過,同時第二個 decode 區段遵循 logical-codec sub-issue。

由索引模型根據 Issue 內容生成。

評估

技術堆疊
python, rust
領域
developer-experience, documentation, testing
Issue 類型
功能
難度
4/5
預估耗時
3-5 天
活躍度
活躍
描述清晰度
描述清楚
新手友好度
68/100

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。