query-cascade 0.3.5__tar.gz → 0.3.7__tar.gz

{query_cascade-0.3.5 → query_cascade-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: query-cascade
-Version: 0.3.5
+Version: 0.3.7
 Summary: Minimal demand-driven query framework for incremental computation.
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -207,6 +207,17 @@ def parse(source: str):
 ```
 If a query throws an exception, it gets cached just like a regular return value. Subsequent calls instantly re-raise the exception, preserving incremental evaluation speed during error states. Cached exceptions can also be hydrated from the persistent disk cache.
 
+### Input Debouncing & Transactions
+When updating multiple inputs, intermediate read states ("flapping") can cause inconsistent evaluations. Use `engine.transaction()` to batch updates so they are committed atomically.
+
+```python
+with engine.transaction():
+    theme.set("dark")
+    layout.set("grid")
+    
+# Queries will only re-evaluate once observing both changes simultaneously.
+```
+
 ### Code-Aware Caching (Automatic Invalidation)
 Cascade automatically inspects the Python bytecode of your `@engine.query` and `@engine.input` functions. If you edit a function's logic and the module is hot-reloaded (or you restart your script), Cascade compares the new function's bytecode hash against the previously cached logic. If the logic has changed, Cascade immediately invalidates that function's memory and persistent disk caches, avoiding stale results without requiring manual cache wipes. Code formatting and comments do not affect the bytecode hash.
 

{query_cascade-0.3.5 → query_cascade-0.3.7}/README.md

@@ -188,6 +188,17 @@ def parse(source: str):
 ```
 If a query throws an exception, it gets cached just like a regular return value. Subsequent calls instantly re-raise the exception, preserving incremental evaluation speed during error states. Cached exceptions can also be hydrated from the persistent disk cache.
 
+### Input Debouncing & Transactions
+When updating multiple inputs, intermediate read states ("flapping") can cause inconsistent evaluations. Use `engine.transaction()` to batch updates so they are committed atomically.
+
+```python
+with engine.transaction():
+    theme.set("dark")
+    layout.set("grid")
+    
+# Queries will only re-evaluate once observing both changes simultaneously.
+```
+
 ### Code-Aware Caching (Automatic Invalidation)
 Cascade automatically inspects the Python bytecode of your `@engine.query` and `@engine.input` functions. If you edit a function's logic and the module is hot-reloaded (or you restart your script), Cascade compares the new function's bytecode hash against the previously cached logic. If the logic has changed, Cascade immediately invalidates that function's memory and persistent disk caches, avoiding stale results without requiring manual cache wipes. Code formatting and comments do not affect the bytecode hash.
 

{query_cascade-0.3.5 → query_cascade-0.3.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "query-cascade"
-version = "0.3.5"
+version = "0.3.7"
 description = "Minimal demand-driven query framework for incremental computation."
 requires-python = ">=3.12"
 readme = "README.md"

{query_cascade-0.3.5 → query_cascade-0.3.7}/src/cascade/_store.py

@@ -319,6 +319,39 @@ class GraphStore:
             self.trace_event("input_set", trace_key, detail=f"changed_at={changed_at}")
             return self.revision
 
+    def set_inputs(
+        self,
+        updates: list[tuple[str, tuple[Any, ...], Any]],
+        *,
+        bump_cancel_epoch: bool = True,
+    ) -> int:
+        with self.lock:
+            if not updates:
+                return self.revision
+            self.revision += 1
+            if bump_cancel_epoch:
+                self.cancel_epoch += 1
+            for input_id, args, value in updates:
+                key = (input_id, args)
+                versions = self.inputs.setdefault(key, [])
+                current = versions[-1] if versions else None
+                value_hash = self.stable_hash(value)
+                if current is not None and current.value_hash == value_hash:
+                    changed_at = current.changed_at
+                else:
+                    changed_at = self.revision
+                versions.append(
+                    InputVersion(
+                        revision=self.revision,
+                        changed_at=changed_at,
+                        value_hash=value_hash,
+                        value=value,
+                    )
+                )
+                trace_key = ("input", input_id, args)
+                self.trace_event("input_set", trace_key, detail=f"changed_at={changed_at}")
+            return self.revision
+
     def inspect_graph(self) -> dict[str, Any]:
         with self.lock:
             nodes = [self.key_to_str(k) for k in self.memos.keys()]

{query_cascade-0.3.5 → query_cascade-0.3.7}/src/cascade/engine.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import contextvars
 import inspect
 import concurrent.futures
 import os
@@ -38,6 +39,30 @@ __all__ = [
 ]
 
 
+class EngineTransaction:
+    def __init__(self, engine: Engine) -> None:
+        self.engine = engine
+        self.updates: list[tuple[str, tuple[Any, ...], Any]] = []
+        self._token: contextvars.Token | None = None
+
+    def __enter__(self) -> EngineTransaction:
+        if _active_transaction.get() is not None:
+            raise RuntimeError("Nested transactions are not supported")
+        self._token = _active_transaction.set(self)
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        if self._token is not None:
+            _active_transaction.reset(self._token)
+        if exc_type is None and self.updates:
+            self.engine._set_inputs(self.updates)
+
+
+_active_transaction: contextvars.ContextVar[EngineTransaction | None] = contextvars.ContextVar(
+    "active_transaction", default=None
+)
+
+
 class _InputHandle:
     def __init__(self, engine: Engine, fn: Callable[..., Any]) -> None:
         self._engine = engine
@@ -61,13 +86,19 @@ class _InputHandle:
                 
         return self._engine._read_input(self._id, self._fn, args, snapshot=snapshot)
 
-    def set(self, *args: Any, value: Any = _UNSET) -> int:
+    def set(self, *args: Any, value: Any = _UNSET) -> int | None:
         if value is _UNSET:
             if not args:
                 raise TypeError("set() requires input value")
             *input_args, resolved_value = args
             args = tuple(input_args)
             value = resolved_value
+            
+        tx = _active_transaction.get()
+        if tx is not None and tx.engine is self._engine:
+            tx.updates.append((self._id, tuple(args), value))
+            return None
+            
         return self._engine._set_input(self._id, tuple(args), value)
 
     @property
@@ -245,6 +276,9 @@ class Engine:
             raise PersistentCacheError("engine has no persistent cache; pass cache_dir= to Engine")
         self._disk.clear()
 
+    def transaction(self) -> EngineTransaction:
+        return EngineTransaction(self)
+
     def input(self, fn: Callable[..., Any]) -> _InputHandle:
         handle = _InputHandle(self, fn)
         self._store.register_input(handle.id, fn)
@@ -502,6 +536,14 @@ class Engine:
     ) -> int:
         return self._store.set_input(input_id, args, value, bump_cancel_epoch=bump_cancel_epoch)
 
+    def _set_inputs(
+        self,
+        updates: list[tuple[str, tuple[Any, ...], Any]],
+        *,
+        bump_cancel_epoch: bool = True,
+    ) -> int:
+        return self._store.set_inputs(updates, bump_cancel_epoch=bump_cancel_epoch)
+
     def _read_input(
         self,
         input_id: str,

{query_cascade-0.3.5 → query_cascade-0.3.7}/src/query_cascade.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: query-cascade
-Version: 0.3.5
+Version: 0.3.7
 Summary: Minimal demand-driven query framework for incremental computation.
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -207,6 +207,17 @@ def parse(source: str):
 ```
 If a query throws an exception, it gets cached just like a regular return value. Subsequent calls instantly re-raise the exception, preserving incremental evaluation speed during error states. Cached exceptions can also be hydrated from the persistent disk cache.
 
+### Input Debouncing & Transactions
+When updating multiple inputs, intermediate read states ("flapping") can cause inconsistent evaluations. Use `engine.transaction()` to batch updates so they are committed atomically.
+
+```python
+with engine.transaction():
+    theme.set("dark")
+    layout.set("grid")
+    
+# Queries will only re-evaluate once observing both changes simultaneously.
+```
+
 ### Code-Aware Caching (Automatic Invalidation)
 Cascade automatically inspects the Python bytecode of your `@engine.query` and `@engine.input` functions. If you edit a function's logic and the module is hot-reloaded (or you restart your script), Cascade compares the new function's bytecode hash against the previously cached logic. If the logic has changed, Cascade immediately invalidates that function's memory and persistent disk caches, avoiding stale results without requiring manual cache wipes. Code formatting and comments do not affect the bytecode hash.
 

{query_cascade-0.3.5 → query_cascade-0.3.7}/tests/test_engine.py

@@ -773,3 +773,49 @@ def test_inspect_graph_full_summary_oracle_across_varied_graphs() -> None:
         expected_memo_count=1,
         expected_input_count=3,
     )
+
+
+def test_engine_transaction() -> None:
+    engine = Engine()
+
+    @engine.input
+    def input_a() -> int:
+        return 0
+
+    @engine.input
+    def input_b() -> int:
+        return 0
+
+    @engine.query
+    def q() -> tuple[int, int]:
+        return (input_a(), input_b())
+
+    assert q() == (0, 0)
+    rev_before = engine.revision
+
+    with engine.transaction():
+        input_a.set(1)
+        input_b.set(2)
+        # uncommitted changes should not be visible
+        assert q() == (0, 0)
+
+    assert q() == (1, 2)
+    assert engine.revision == rev_before + 1
+
+    # Exception in transaction should abort updates
+    try:
+        with engine.transaction():
+            input_a.set(10)
+            input_b.set(20)
+            raise ValueError("abort")
+    except ValueError:
+        pass
+
+    assert q() == (1, 2)
+    assert engine.revision == rev_before + 1
+
+    # Nested transactions raise error
+    with engine.transaction():
+        with pytest.raises(RuntimeError, match="Nested transactions"):
+            with engine.transaction():
+                pass