lora-python 0.6.0__tar.gz → 0.8.0__tar.gz

{lora_python-0.6.0 → lora_python-0.8.0}/Cargo.lock

@@ -54,6 +54,15 @@ version = "1.0.102"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
 
+[[package]]
+name = "arc-swap"
+version = "1.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a3a1fd6f75306b68087b831f025c712524bcb19aad54e557b1129cfa0a2b207"
+dependencies = [
+ "rustversion",
+]
+
 [[package]]
 name = "argon2"
 version = "0.5.3"
@@ -788,7 +797,7 @@ checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
 [[package]]
 name = "lora-analyzer"
-version = "0.6.0"
+version = "0.8.0"
 dependencies = [
  "lora-ast",
  "lora-parser",
@@ -798,14 +807,22 @@ dependencies = [
 
 [[package]]
 name = "lora-ast"
-version = "0.6.0"
+version = "0.8.0"
 dependencies = [
  "smallvec 2.0.0-alpha.12",
 ]
 
+[[package]]
+name = "lora-binding-buffer"
+version = "0.8.0"
+dependencies = [
+ "lora-database",
+ "lora-store",
+]
+
 [[package]]
 name = "lora-compiler"
-version = "0.6.0"
+version = "0.8.0"
 dependencies = [
  "lora-analyzer",
  "lora-ast",
@@ -813,9 +830,10 @@ dependencies = [
 
 [[package]]
 name = "lora-database"
-version = "0.6.0"
+version = "0.8.0"
 dependencies = [
  "anyhow",
+ "arc-swap",
  "criterion",
  "lora-analyzer",
  "lora-ast",
@@ -826,13 +844,15 @@ dependencies = [
  "lora-store",
  "lora-wal",
  "serde_json",
+ "thiserror",
  "tower",
+ "tracing",
  "zip",
 ]
 
 [[package]]
 name = "lora-executor"
-version = "0.6.0"
+version = "0.8.0"
 dependencies = [
  "lora-analyzer",
  "lora-ast",
@@ -840,15 +860,17 @@ dependencies = [
  "lora-store",
  "regex",
  "serde",
+ "smallvec 2.0.0-alpha.12",
  "thiserror",
  "tracing",
 ]
 
 [[package]]
 name = "lora-ffi"
-version = "0.6.0"
+version = "0.8.0"
 dependencies = [
  "anyhow",
+ "lora-binding-buffer",
  "lora-database",
  "lora-store",
  "serde",
@@ -857,9 +879,10 @@ dependencies = [
 
 [[package]]
 name = "lora-node"
-version = "0.6.0"
+version = "0.8.0"
 dependencies = [
  "anyhow",
+ "lora-binding-buffer",
  "lora-database",
  "lora-store",
  "napi",
@@ -871,7 +894,7 @@ dependencies = [
 
 [[package]]
 name = "lora-parser"
-version = "0.6.0"
+version = "0.8.0"
 dependencies = [
  "lora-ast",
  "pest",
@@ -882,7 +905,7 @@ dependencies = [
 
 [[package]]
 name = "lora-python"
-version = "0.6.0"
+version = "0.8.0"
 dependencies = [
  "anyhow",
  "lora-database",
@@ -894,7 +917,7 @@ dependencies = [
 
 [[package]]
 name = "lora-server"
-version = "0.6.0"
+version = "0.8.0"
 dependencies = [
  "anyhow",
  "axum",
@@ -908,7 +931,7 @@ dependencies = [
 
 [[package]]
 name = "lora-snapshot"
-version = "0.6.0"
+version = "0.8.0"
 dependencies = [
  "argon2",
  "bincode",
@@ -923,7 +946,7 @@ dependencies = [
 
 [[package]]
 name = "lora-store"
-version = "0.6.0"
+version = "0.8.0"
 dependencies = [
  "bincode",
  "crc32fast",
@@ -935,7 +958,7 @@ dependencies = [
 
 [[package]]
 name = "lora-wal"
-version = "0.6.0"
+version = "0.8.0"
 dependencies = [
  "crc32fast",
  "lora-store",
@@ -945,11 +968,12 @@ dependencies = [
 
 [[package]]
 name = "lora-wasm"
-version = "0.6.0"
+version = "0.8.0"
 dependencies = [
  "anyhow",
  "console_error_panic_hook",
  "js-sys",
+ "lora-binding-buffer",
  "lora-database",
  "lora-store",
  "serde",
@@ -960,7 +984,7 @@ dependencies = [
 
 [[package]]
 name = "lora_ruby"
-version = "0.6.0"
+version = "0.8.0"
 dependencies = [
  "anyhow",
  "lora-database",

{lora_python-0.6.0 → lora_python-0.8.0}/Cargo.toml

@@ -1,10 +1,10 @@
 [workspace]
-members = ["crates/lora-ast", "crates/lora-parser", "crates/lora-analyzer", "crates/lora-compiler", "crates/lora-store", "crates/lora-snapshot", "crates/lora-wal", "crates/lora-executor", "crates/lora-database", "crates/lora-python"]
+members = ["crates/lora-ast", "crates/lora-parser", "crates/lora-analyzer", "crates/lora-compiler", "crates/lora-store", "crates/lora-snapshot", "crates/lora-wal", "crates/lora-executor", "crates/lora-database", "crates/bindings/lora-python"]
 resolver = "2"
 
 [workspace.package]
 edition = "2021"
-version = "0.6.0"
+version = "0.8.0"
 license = "BUSL-1.1"
 authors = ["LoraDB, Inc."]
 repository = "https://github.com/lora-db/lora"
@@ -15,18 +15,20 @@ rust-version = "1.87"
 # Internal crates — versions are kept in lockstep with [workspace.package].version
 # by `scripts/sync-versions.mjs`. Both `path` and `version` are set so that
 # `cargo publish` works (crates.io cannot resolve path-only deps).
-lora-ast = { path = "crates/lora-ast", version = "=0.6.0" }
-lora-parser = { path = "crates/lora-parser", version = "=0.6.0" }
-lora-analyzer = { path = "crates/lora-analyzer", version = "=0.6.0" }
-lora-compiler = { path = "crates/lora-compiler", version = "=0.6.0" }
-lora-store = { path = "crates/lora-store", version = "=0.6.0" }
-lora-snapshot = { path = "crates/lora-snapshot", version = "=0.6.0", default-features = false }
-lora-wal = { path = "crates/lora-wal", version = "=0.6.0" }
-lora-executor = { path = "crates/lora-executor", version = "=0.6.0" }
-lora-database = { path = "crates/lora-database", version = "=0.6.0" }
+lora-ast = { path = "crates/lora-ast", version = "=0.8.0" }
+lora-parser = { path = "crates/lora-parser", version = "=0.8.0" }
+lora-analyzer = { path = "crates/lora-analyzer", version = "=0.8.0" }
+lora-compiler = { path = "crates/lora-compiler", version = "=0.8.0" }
+lora-store = { path = "crates/lora-store", version = "=0.8.0" }
+lora-snapshot = { path = "crates/lora-snapshot", version = "=0.8.0", default-features = false }
+lora-wal = { path = "crates/lora-wal", version = "=0.8.0" }
+lora-executor = { path = "crates/lora-executor", version = "=0.8.0" }
+lora-database = { path = "crates/lora-database", version = "=0.8.0" }
+lora-binding-buffer = { path = "crates/bindings/lora-binding-buffer", version = "=0.8.0" }
 
 # External crates.
 anyhow = "1"
+arc-swap = "1"
 thiserror = "2"
 tracing = "0"
 axum = "0"

{lora_python-0.6.0 → lora_python-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lora-python
-Version: 0.6.0
+Version: 0.8.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8
@@ -30,16 +30,16 @@ Project-URL: Repository, https://github.com/lora-db/lora
 
 # lora-python
 
-Python bindings for the [Lora](../../README.md) graph
+Python bindings for the [Lora](../../../README.md) graph
 engine. Ships both a synchronous PyO3 `Database` class and an
 asyncio-compatible `AsyncDatabase` wrapper that never blocks the event loop.
 
-> **Status:** prototype / feasibility check. Not published to PyPI.
+> **Package:** `lora-python`.
 
 ## Install (local dev)
 
 ```bash
-cd crates/lora-python
+cd crates/bindings/lora-python
 python3 -m venv .venv && source .venv/bin/activate
 pip install -U pip maturin pytest pytest-asyncio
 maturin develop         # builds the Rust extension into the venv
@@ -76,6 +76,37 @@ persistent = Database.create("app", {"database_dir": "./data"})  # persistent: .
 If you want persistence, pass a database name and `database_dir` to
 `Database.create(...)` or `Database(...)`.
 
+## Explain & Profile
+
+`db.explain()` and `db.profile()` are first-class methods alongside
+`db.execute()`. They are intentionally separate calls — neither
+routes through `execute()` — so plan inspection and runtime metrics
+must be requested explicitly.
+
+```python
+plan = db.explain(
+    "MATCH (p:Person) WHERE p.name = $name RETURN p",
+    {"name": "Alice"},
+)
+print(plan["shape"])             # "readOnly"
+print(plan["tree"]["operator"])  # top-most operator label
+
+profile = db.profile(
+    "MATCH (p:Person) WHERE p.name = $name RETURN p",
+    {"name": "Alice"},
+)
+print(profile["metrics"]["total_elapsed_ns"])
+print(profile["metrics"]["per_operator"])  # per-step inclusive timing
+```
+
+`explain()` never invokes the executor — calling it on a mutating
+query (`CREATE`, `MERGE`, `SET`, `DELETE`, `REMOVE`) leaves the graph
+untouched.
+
+> **`profile()` executes the query for real.** Mutating queries
+> produce the same side effects as `execute()`. Use `explain()` to
+> inspect a mutating plan without running it.
+
 ## Async usage (non-blocking)
 
 ```python
@@ -133,7 +164,7 @@ Constructors and guards are exported from `lora_python.types`:
 `is_relationship`, `is_path`, `is_point`, `is_temporal`.
 
 > `distance()` on WGS-84-3D points ignores `height` — see
-> [functions reference](../../apps/loradb.com/docs/functions/overview.md) for the full spatial
+> [functions reference](../../../apps/loradb.com/docs/functions/overview.md) for the full spatial
 > reference and known limitations.
 
 ## Errors

{lora_python-0.6.0 → lora_python-0.8.0}/README.md

@@ -1,15 +1,15 @@
 # lora-python
 
-Python bindings for the [Lora](../../README.md) graph
+Python bindings for the [Lora](../../../README.md) graph
 engine. Ships both a synchronous PyO3 `Database` class and an
 asyncio-compatible `AsyncDatabase` wrapper that never blocks the event loop.
 
-> **Status:** prototype / feasibility check. Not published to PyPI.
+> **Package:** `lora-python`.
 
 ## Install (local dev)
 
 ```bash
-cd crates/lora-python
+cd crates/bindings/lora-python
 python3 -m venv .venv && source .venv/bin/activate
 pip install -U pip maturin pytest pytest-asyncio
 maturin develop         # builds the Rust extension into the venv
@@ -46,6 +46,37 @@ persistent = Database.create("app", {"database_dir": "./data"})  # persistent: .
 If you want persistence, pass a database name and `database_dir` to
 `Database.create(...)` or `Database(...)`.
 
+## Explain & Profile
+
+`db.explain()` and `db.profile()` are first-class methods alongside
+`db.execute()`. They are intentionally separate calls — neither
+routes through `execute()` — so plan inspection and runtime metrics
+must be requested explicitly.
+
+```python
+plan = db.explain(
+    "MATCH (p:Person) WHERE p.name = $name RETURN p",
+    {"name": "Alice"},
+)
+print(plan["shape"])             # "readOnly"
+print(plan["tree"]["operator"])  # top-most operator label
+
+profile = db.profile(
+    "MATCH (p:Person) WHERE p.name = $name RETURN p",
+    {"name": "Alice"},
+)
+print(profile["metrics"]["total_elapsed_ns"])
+print(profile["metrics"]["per_operator"])  # per-step inclusive timing
+```
+
+`explain()` never invokes the executor — calling it on a mutating
+query (`CREATE`, `MERGE`, `SET`, `DELETE`, `REMOVE`) leaves the graph
+untouched.
+
+> **`profile()` executes the query for real.** Mutating queries
+> produce the same side effects as `execute()`. Use `explain()` to
+> inspect a mutating plan without running it.
+
 ## Async usage (non-blocking)
 
 ```python
@@ -103,7 +134,7 @@ Constructors and guards are exported from `lora_python.types`:
 `is_relationship`, `is_path`, `is_point`, `is_temporal`.
 
 > `distance()` on WGS-84-3D points ignores `height` — see
-> [functions reference](../../apps/loradb.com/docs/functions/overview.md) for the full spatial
+> [functions reference](../../../apps/loradb.com/docs/functions/overview.md) for the full spatial
 > reference and known limitations.
 
 ## Errors

{lora_python-0.6.0/crates → lora_python-0.8.0/crates/bindings}/lora-python/README.md

@@ -1,15 +1,15 @@
 # lora-python
 
-Python bindings for the [Lora](../../README.md) graph
+Python bindings for the [Lora](../../../README.md) graph
 engine. Ships both a synchronous PyO3 `Database` class and an
 asyncio-compatible `AsyncDatabase` wrapper that never blocks the event loop.
 
-> **Status:** prototype / feasibility check. Not published to PyPI.
+> **Package:** `lora-python`.
 
 ## Install (local dev)
 
 ```bash
-cd crates/lora-python
+cd crates/bindings/lora-python
 python3 -m venv .venv && source .venv/bin/activate
 pip install -U pip maturin pytest pytest-asyncio
 maturin develop         # builds the Rust extension into the venv
@@ -46,6 +46,37 @@ persistent = Database.create("app", {"database_dir": "./data"})  # persistent: .
 If you want persistence, pass a database name and `database_dir` to
 `Database.create(...)` or `Database(...)`.
 
+## Explain & Profile
+
+`db.explain()` and `db.profile()` are first-class methods alongside
+`db.execute()`. They are intentionally separate calls — neither
+routes through `execute()` — so plan inspection and runtime metrics
+must be requested explicitly.
+
+```python
+plan = db.explain(
+    "MATCH (p:Person) WHERE p.name = $name RETURN p",
+    {"name": "Alice"},
+)
+print(plan["shape"])             # "readOnly"
+print(plan["tree"]["operator"])  # top-most operator label
+
+profile = db.profile(
+    "MATCH (p:Person) WHERE p.name = $name RETURN p",
+    {"name": "Alice"},
+)
+print(profile["metrics"]["total_elapsed_ns"])
+print(profile["metrics"]["per_operator"])  # per-step inclusive timing
+```
+
+`explain()` never invokes the executor — calling it on a mutating
+query (`CREATE`, `MERGE`, `SET`, `DELETE`, `REMOVE`) leaves the graph
+untouched.
+
+> **`profile()` executes the query for real.** Mutating queries
+> produce the same side effects as `execute()`. Use `explain()` to
+> inspect a mutating plan without running it.
+
 ## Async usage (non-blocking)
 
 ```python
@@ -103,7 +134,7 @@ Constructors and guards are exported from `lora_python.types`:
 `is_relationship`, `is_path`, `is_point`, `is_temporal`.
 
 > `distance()` on WGS-84-3D points ignores `height` — see
-> [functions reference](../../apps/loradb.com/docs/functions/overview.md) for the full spatial
+> [functions reference](../../../apps/loradb.com/docs/functions/overview.md) for the full spatial
 > reference and known limitations.
 
 ## Errors

lora_python-0.8.0/crates/bindings/lora-python/src/errors.rs

@@ -0,0 +1,73 @@
+//! Exception type registrations for the Python bindings.
+//!
+//! `pyo3::create_exception!` generates the per-class machinery
+//! (`new_err`, `type_object`, `From<Self> for PyErr`, etc.). The types
+//! are registered with the module by `lib.rs::_native` at import time so
+//! Python callers see `lora_python.LoraError` and friends.
+//!
+//! Engine errors are surfaced with the message body prefixed by the
+//! precise wire code from [`lora_database::LoraErrorCode`] (e.g.
+//! `"LORA_PARSE: parse error at 0..5: ..."`). Callers who care about
+//! routing past the exception class can split on the first colon to
+//! recover the code.
+
+use pyo3::create_exception;
+use pyo3::exceptions::PyException;
+use pyo3::PyErr;
+
+use lora_database::{LoraError as EngineLoraError, LoraErrorCode};
+
+create_exception!(
+    lora_python,
+    LoraError,
+    PyException,
+    "Base class for Lora engine errors. Exception messages start with a stable `LORA_*` code."
+);
+create_exception!(
+    lora_python,
+    LoraQueryError,
+    LoraError,
+    "Parse / analyze / execute / IO failure. Exception message starts with a precise `LORA_*` code."
+);
+create_exception!(
+    lora_python,
+    InvalidParamsError,
+    LoraError,
+    "A parameter value could not be mapped to a Lora value. Message starts with `LORA_INVALID_PARAMS:`."
+);
+
+/// Build a [`LoraQueryError`], prefixing the message with the precise
+/// wire code so the Python caller can route past the exception class.
+/// Accepts anything convertible into [`EngineLoraError`] — typed
+/// engine errors and binding-internal `anyhow::Error` both flow through
+/// the same path.
+pub(crate) fn lora_query_err_from_anyhow(err: impl Into<EngineLoraError>) -> PyErr {
+    let lora = err.into();
+    LoraQueryError::new_err(format!("{}: {}", lora.code().as_str(), lora.message()))
+}
+
+/// Borrowed-by-reference variant for call sites that don't have an
+/// owned error (e.g. closures that need to keep the original).
+#[allow(dead_code)]
+pub(crate) fn lora_query_err_from_anyhow_ref(err: &anyhow::Error) -> PyErr {
+    let lora = EngineLoraError::from_anyhow_ref(err);
+    LoraQueryError::new_err(format!("{}: {}", lora.code().as_str(), lora.message()))
+}
+
+/// Build a [`LoraQueryError`] for a binding-side message that doesn't
+/// carry a downcastable error chain (e.g. `database is closed`,
+/// `database lock poisoned`). Tagged with [`LoraErrorCode::Internal`].
+#[allow(dead_code)]
+pub(crate) fn lora_query_err_internal(message: &str) -> PyErr {
+    LoraQueryError::new_err(format!("{}: {message}", LoraErrorCode::Internal.as_str()))
+}
+
+/// Build an [`InvalidParamsError`] tagged with `LORA_INVALID_PARAMS`.
+#[allow(dead_code)]
+pub(crate) fn invalid_params_err(message: impl AsRef<str>) -> PyErr {
+    InvalidParamsError::new_err(format!(
+        "{}: {}",
+        LoraErrorCode::InvalidParams.as_str(),
+        message.as_ref()
+    ))
+}