feat: Python bindings for embedded mode (clickgraph-py) (#180)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: genezhang

Cargo.lock

@@ -2,6 +2,7 @@
 members = [
     "clickgraph-client",
     "clickgraph-embedded",
+    "clickgraph-py",
 ]
 
 [package]

Cargo.toml

@@ -10,7 +10,7 @@ use clickgraph::graph_catalog::graph_schema::GraphSchema;
 
 use super::database::Database;
 use super::error::EmbeddedError;
-use super::query_result::{QueryResult, Row};
+use super::query_result::QueryResult;
 use super::value::Value;
 
 /// A connection to an embedded ClickGraph database.

clickgraph-embedded/src/connection.rs

@@ -0,0 +1,14 @@
+# Compiled extensions
+*.so
+*.pyd
+*.dll
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+
+# maturin
+target/

clickgraph-py/.gitignore

@@ -0,0 +1,16 @@
+[package]
+name = "clickgraph-py"
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.85"
+description = "Python bindings for ClickGraph embedded graph query engine"
+repository = "https://github.com/genezhang/clickgraph"
+license = "Apache-2.0"
+
+[lib]
+name = "_clickgraph"
+crate-type = ["cdylib"]
+
+[dependencies]
+clickgraph-embedded = { path = "../clickgraph-embedded" }
+pyo3 = { version = "0.24", features = ["extension-module"] }

clickgraph-py/Cargo.toml

@@ -0,0 +1,138 @@
+# clickgraph — Python bindings
+
+Embedded graph query engine — run Cypher queries over Parquet, Iceberg, Delta Lake and S3 data without a ClickHouse server.
+
+## Quick Start
+
+```python
+import clickgraph
+
+db = clickgraph.Database("schema.yaml")
+conn = db.connect()
+
+for row in conn.query("MATCH (u:User) RETURN u.name LIMIT 5"):
+    print(row["u.name"])
+```
+
+## API Compatibility
+
+ClickGraph's Python API is designed to be familiar to users of other graph databases:
+
+| Operation | ClickGraph | Kuzu | Neo4j |
+|-----------|-----------|------|-------|
+| Open database | `Database("schema.yaml")` | `Database("path")` | `GraphDatabase.driver(uri)` |
+| Get connection | `db.connect()` or `Connection(db)` | `Connection(db)` | `driver.session()` |
+| Run query | `conn.query(cypher)` | `conn.execute(cypher)` | `session.run(cypher)` |
+| Iterate rows | `for row in result:` | `while result.has_next():` | `for record in result:` |
+| Access by name | `row["col"]` (dict) | `row[0]` (tuple) | `record["col"]` (dict-like) |
+
+All three calling styles work — use whichever feels natural:
+
+```python
+# ClickGraph style
+conn = db.connect()
+result = conn.query("MATCH (u:User) RETURN u.name")
+
+# Kuzu style
+conn = clickgraph.Connection(db)
+result = conn.execute("MATCH (u:User) RETURN u.name")
+while result.has_next():
+    row = result.get_next()
+    print(row[0])
+
+# Neo4j style
+conn = db.connect()
+result = conn.run("MATCH (u:User) RETURN u.name")
+for row in result:
+    print(row["u.name"])
+```
+
+## API
+
+### `Database(schema_path, **kwargs)`
+
+Open an embedded database from a YAML schema file.
+
+**Keyword arguments** (all optional):
+- `session_dir` — directory for chdb session data (default: temp dir)
+- `data_dir` — base directory for relative `source:` paths
+- `max_threads` — maximum threads for chdb
+- `s3_access_key_id`, `s3_secret_access_key`, `s3_region`, `s3_endpoint_url`, `s3_session_token` — S3 credentials
+- `gcs_access_key_id`, `gcs_secret_access_key` — GCS HMAC credentials
+- `azure_storage_account_name`, `azure_storage_account_key`, `azure_storage_connection_string` — Azure credentials
+
+### `Database.connect() → Connection`
+
+Create a connection for executing queries.
+
+### `Connection(db)` *(Kuzu-compatible constructor)*
+
+Alternative to `db.connect()` — creates a connection from a Database instance.
+
+### `Database.execute(cypher) → QueryResult`
+
+Shorthand — execute a query without creating a separate connection.
+
+### `Connection.query(cypher) → QueryResult`
+
+Execute a Cypher query. Returns an iterable of row dicts.
+
+### `Connection.execute(cypher) → QueryResult` *(Kuzu-compatible alias)*
+
+Alias for `query()`.
+
+### `Connection.run(cypher) → QueryResult` *(Neo4j-compatible alias)*
+
+Alias for `query()`.
+
+### `Connection.query_to_sql(cypher) → str`
+
+Translate Cypher to ClickHouse SQL without executing.
+
+### `QueryResult`
+
+**Dict-style access** (ClickGraph/Neo4j pattern):
+- Iterable: `for row in result:` — each row is a `dict`
+- `result[i]` — access row by index (supports negative indexing)
+- `result.column_names` — list of column names
+- `result.num_rows` — number of rows
+- `result.as_dicts()` — all rows as a list of dicts
+- `result.get_row(i)` — single row by index as dict
+- `len(result)` — number of rows
+
+**Tuple-style access** (Kuzu pattern):
+- `result.has_next()` — True if more rows remain
+- `result.get_next()` — next row as a list of values (column order)
+- `result.reset_iterator()` — restart the cursor
+
+## Installation
+
+```bash
+# From source (requires Rust toolchain + chdb)
+cd clickgraph-py
+pip install maturin
+maturin develop
+```
+
+## Example with S3 data
+
+```python
+import clickgraph
+
+db = clickgraph.Database(
+    "schema.yaml",
+    s3_access_key_id="AKIA...",
+    s3_secret_access_key="...",
+    s3_region="us-east-1",
+)
+
+conn = db.connect()
+result = conn.query("""
+    MATCH (u:User)-[:FOLLOWS]->(f:User)
+    WHERE u.name = 'Alice'
+    RETURN f.name, f.email
+""")
+
+for row in result:
+    print(f"{row['f.name']}: {row['f.email']}")
+```

clickgraph-py/README.md

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["maturin>=1.0,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "clickgraph"
+version = "0.1.0"
+description = "Embedded graph query engine — run Cypher over Parquet, Iceberg, S3 and ClickHouse"
+requires-python = ">=3.8"
+license = "Apache-2.0"
+readme = "README.md"
+keywords = ["graph", "cypher", "clickhouse", "embedded", "analytics"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Rust",
+    "Topic :: Database",
+]
+
+[tool.maturin]
+features = []
+python-source = "python"
+module-name = "clickgraph._clickgraph"

clickgraph-py/pyproject.toml

@@ -0,0 +1,39 @@
+"""ClickGraph — embedded graph query engine for Python.
+
+Run Cypher queries over Parquet, Iceberg, Delta Lake and S3 data
+without a ClickHouse server.
+
+Quick start::
+
+    import clickgraph
+
+    db = clickgraph.Database("schema.yaml")
+    conn = db.connect()
+    for row in conn.query("MATCH (u:User) RETURN u.name LIMIT 5"):
+        print(row["u.name"])
+
+Kuzu-compatible style::
+
+    from clickgraph import Database, Connection
+
+    db = Database("schema.yaml")
+    conn = Connection(db)
+    result = conn.execute("MATCH (u:User) RETURN u.name")
+    while result.has_next():
+        row = result.get_next()
+        print(row[0])
+
+With S3 credentials::
+
+    db = clickgraph.Database(
+        "schema.yaml",
+        s3_access_key_id="AKIA...",
+        s3_secret_access_key="...",
+        s3_region="us-east-1",
+    )
+"""
+
+from clickgraph._clickgraph import Database, Connection, QueryResult
+
+__all__ = ["Database", "Connection", "QueryResult"]
+__version__ = "0.1.0"