feat: add PyO3 Python API

Author: KKould

.github/workflows/ci.yml

@@ -147,3 +147,23 @@ jobs:
 
       - name: Run native examples
         run: make native-examples
+  # 7
+  python-tests:
+    name: Python bindings tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Install stable toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Run python binding tests
+        run: make test-python

Cargo.lock

@@ -28,6 +28,7 @@ default = ["macros"]
 macros  = []
 net     = ["dep:pgwire", "dep:async-trait", "dep:clap", "dep:env_logger", "dep:futures", "dep:log", "dep:tokio"]
 pprof   = ["pprof/criterion", "pprof/flamegraph"]
+python  = ["dep:pyo3"]
 
 [[bench]]
 name    = "query_bench"
@@ -48,6 +49,7 @@ itertools             = { version = "0.12" }
 ordered-float         = { version = "4", features = ["serde"] }
 paste                 = { version = "1" }
 parking_lot           = { version = "0.12", features = ["arc_lock"] }
+pyo3                  = { version = "0.23", features = ["auto-initialize"], optional = true }
 recursive             = { version = "0.1" }
 regex                 = { version = "1" }
 rust_decimal          = { version = "1" }

Cargo.toml

@@ -3,12 +3,16 @@ CARGO ?= cargo
 WASM_PACK ?= wasm-pack
 SQLLOGIC_PATH ?= tests/slt/**/*.slt
 
-.PHONY: test test-wasm test-slt test-all wasm-build check tpcc tpcc-dual cargo-check build wasm-examples native-examples fmt clippy
+.PHONY: test test-python test-wasm test-slt test-all wasm-build check tpcc tpcc-dual cargo-check build wasm-examples native-examples fmt clippy
 
 ## Run default Rust tests in the current environment (non-WASM).
 test:
 	$(CARGO) test --all
 
+## Run Python binding API tests implemented with pyo3.
+test-python:
+	$(CARGO) test --features python test_python_
+
 ## Perform a `cargo check` across the workspace.
 cargo-check:
 	$(CARGO) check
@@ -30,7 +34,7 @@ test-slt:
 	$(CARGO) run -p sqllogictest-test -- --path '$(SQLLOGIC_PATH)'
 
 ## Convenience target to run every suite in sequence.
-test-all: test test-wasm test-slt
+test-all: test test-wasm test-slt test-python
 
 ## Run formatting (check mode) across the workspace.
 fmt:

Makefile

@@ -52,6 +52,20 @@ console.log(rows.map((r) => r.values.map((v) => v.Int32 ?? v)));
 ```
 - In Node.js, provide a small `localStorage` shim if you enable statistics-related features (see `examples/wasm_index_usage.test.mjs`).
 
+## Python (PyO3)
+- Enable bindings with Cargo feature `python`.
+- Constructor is explicit: `Database(path)`; in-memory usage is `Database.in_memory()`.
+- Minimal usage:
+```python
+import kite_sql
+
+db = kite_sql.Database.in_memory()
+db.execute("create table demo(id int primary key, v int)")
+db.execute("insert into demo values (1, 2), (2, 4)")
+rows = db.run("select * from demo").rows()
+print([row["values"] for row in rows])
+```
+
 ## Examples
 
 ```rust

README.md

@@ -115,6 +115,8 @@ mod optimizer;
 pub mod parser;
 pub mod paths;
 pub mod planner;
+#[cfg(all(not(target_arch = "wasm32"), feature = "python"))]
+pub mod python;
 pub mod serdes;
 pub mod storage;
 pub mod types;