query-cascade 0.3.4__tar.gz → 0.3.6__tar.gz

{query_cascade-0.3.4 → query_cascade-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: query-cascade
-Version: 0.3.4
+Version: 0.3.6
 Summary: Minimal demand-driven query framework for incremental computation.
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -13,6 +13,7 @@ Requires-Dist: lmdb; extra == "dev"
 Requires-Dist: msgpack; extra == "dev"
 Requires-Dist: mutmut; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
 
@@ -138,6 +139,43 @@ A few things to know:
 
 ## Advanced Features
 
+### Asynchronous Execution
+Cascade natively supports asynchronous queries via `async def`. This is extremely useful for I/O-bound workflows (such as making database or network calls). When an asynchronous query evaluates, it runs cooperatively on the active `asyncio` event loop.
+
+```python
+import asyncio
+from cascade import Engine
+
+engine = Engine()
+
+@engine.query
+async def fetch_user(uid: str):
+    await asyncio.sleep(0.5) # Network I/O
+    return {"id": uid, "name": "Alice"}
+    
+@engine.query
+async def process_user(uid: str):
+    # Await downstream async queries seamlessly
+    user = await fetch_user(uid)
+    return user["name"].upper()
+
+async def main():
+    print(await process_user("123"))
+
+asyncio.run(main())
+```
+Synchronous queries can also be called directly from inside asynchronous nodes (and vice versa). Cascade maintains type stability and performance segregation, ensuring pure-Python CPU-bound tasks suffer no context-switching overhead while I/O-bound tasks evaluate concurrently.
+
+### Pass-Through Queries (`memoize=False`)
+For intermediate queries that generate large outputs, you can set `memoize=False` to prevent their results from being stored in the LRU cache. This saves significant memory while still allowing the query to fully participate in the dependency graph. Downstream nodes will still accurately detect when the query's inputs change, and the unmemoized query will simply recompute its output on-demand when an active caller needs it.
+
+```python
+@engine.query(memoize=False)
+def mapped_data() -> list[int]:
+    data = raw_data()
+    return [x * 2 for x in data]
+```
+
 ### Side-Effect Accumulators
 Queries must be pure functions. Use `Accumulator` to record side-effects (like logs or warnings) that must be replayed when a result is served from the cache.
 
@@ -169,6 +207,20 @@ 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.
+
 ### Performance Metrics
 Set `stats=True` in the `Engine` constructor to track execution timing.
 *   **`engine.stats_summary()`**: Returns wall-clock time spent in function bodies and cache eviction counts.
@@ -211,8 +263,11 @@ pip install query-cascade
 | Script | What it shows |
 |--------|----------------|
 | `compiler_pipeline.py` | `source → parse → symbols → typecheck`, warnings accumulator, cache-hit narration |
+| `async_execution.py` | Asynchronous query evaluation and asyncio event loop integration for IO-bound work |
 | `error_caching.py` | Basic exception caching to prevent repeated re-evaluation on failure |
 | `error_caching_persistence.py` | Disk cache hydration of exceptions across process runs |
+| `code_versioning.py` | Automatic cache invalidation when a function's bytecode logic changes |
+| `pass_through_queries.py` | `memoize=False` tracking inputs without keeping large outputs in the LRU cache |
 | `dynamic_macro_expansion.py` | Query that **changes downstream dependencies** at runtime |
 | `snapshot_isolation.py` | Snapshot reads while live inputs change |
 | `concurrent_background_work.py` | Dedup under concurrency + cancellation after input changes |

{query_cascade-0.3.4 → query_cascade-0.3.6}/README.md

@@ -120,6 +120,43 @@ A few things to know:
 
 ## Advanced Features
 
+### Asynchronous Execution
+Cascade natively supports asynchronous queries via `async def`. This is extremely useful for I/O-bound workflows (such as making database or network calls). When an asynchronous query evaluates, it runs cooperatively on the active `asyncio` event loop.
+
+```python
+import asyncio
+from cascade import Engine
+
+engine = Engine()
+
+@engine.query
+async def fetch_user(uid: str):
+    await asyncio.sleep(0.5) # Network I/O
+    return {"id": uid, "name": "Alice"}
+    
+@engine.query
+async def process_user(uid: str):
+    # Await downstream async queries seamlessly
+    user = await fetch_user(uid)
+    return user["name"].upper()
+
+async def main():
+    print(await process_user("123"))
+
+asyncio.run(main())
+```
+Synchronous queries can also be called directly from inside asynchronous nodes (and vice versa). Cascade maintains type stability and performance segregation, ensuring pure-Python CPU-bound tasks suffer no context-switching overhead while I/O-bound tasks evaluate concurrently.
+
+### Pass-Through Queries (`memoize=False`)
+For intermediate queries that generate large outputs, you can set `memoize=False` to prevent their results from being stored in the LRU cache. This saves significant memory while still allowing the query to fully participate in the dependency graph. Downstream nodes will still accurately detect when the query's inputs change, and the unmemoized query will simply recompute its output on-demand when an active caller needs it.
+
+```python
+@engine.query(memoize=False)
+def mapped_data() -> list[int]:
+    data = raw_data()
+    return [x * 2 for x in data]
+```
+
 ### Side-Effect Accumulators
 Queries must be pure functions. Use `Accumulator` to record side-effects (like logs or warnings) that must be replayed when a result is served from the cache.
 
@@ -151,6 +188,20 @@ 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.
+
 ### Performance Metrics
 Set `stats=True` in the `Engine` constructor to track execution timing.
 *   **`engine.stats_summary()`**: Returns wall-clock time spent in function bodies and cache eviction counts.
@@ -193,8 +244,11 @@ pip install query-cascade
 | Script | What it shows |
 |--------|----------------|
 | `compiler_pipeline.py` | `source → parse → symbols → typecheck`, warnings accumulator, cache-hit narration |
+| `async_execution.py` | Asynchronous query evaluation and asyncio event loop integration for IO-bound work |
 | `error_caching.py` | Basic exception caching to prevent repeated re-evaluation on failure |
 | `error_caching_persistence.py` | Disk cache hydration of exceptions across process runs |
+| `code_versioning.py` | Automatic cache invalidation when a function's bytecode logic changes |
+| `pass_through_queries.py` | `memoize=False` tracking inputs without keeping large outputs in the LRU cache |
 | `dynamic_macro_expansion.py` | Query that **changes downstream dependencies** at runtime |
 | `snapshot_isolation.py` | Snapshot reads while live inputs change |
 | `concurrent_background_work.py` | Dedup under concurrency + cancellation after input changes |

{query_cascade-0.3.4 → query_cascade-0.3.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "query-cascade"
-version = "0.3.4"
+version = "0.3.6"
 description = "Minimal demand-driven query framework for incremental computation."
 requires-python = ">=3.12"
 readme = "README.md"
@@ -20,6 +20,7 @@ dev = [
     "msgpack",
     "mutmut",
     "pytest",
+    "pytest-asyncio",
     "pytest-cov",
     "ruff",
 ]

{query_cascade-0.3.4 → query_cascade-0.3.6}/src/cascade/_disk_cache.py

@@ -1,186 +1,186 @@
-"""LMDB-backed persistent store for query metadata and value blobs.
-
-Layout: one LMDB environment per ``cache_dir`` with three named databases.
-``meta`` maps a deterministic entry key to a packed record describing a query
-result (value fingerprint, dependency fingerprints, accumulator effects).
-``blobs`` is content-addressed: value fingerprint -> canonical value bytes.
-``sys`` holds the on-disk format stamp; a mismatched stamp wipes the cache,
-which is always safe because everything here can be recomputed.
-"""
-
-from __future__ import annotations
-
-import hashlib
-import os
-import threading
-from typing import Any
-
-from . import _canonical
-from ._errors import PersistentCacheError
-
-try:
-    import lmdb
-except ImportError:  # pragma: no cover - exercised via monkeypatch in tests
-    lmdb = None  # type: ignore[assignment]
-
-LMDB_INSTALL_HINT = (
-    "cascade persistent caching requires the 'lmdb' package for the on-disk store; "
-    "there is no fallback. Install it with: pip install lmdb"
-)
-
-DISK_FORMAT = 1
-_FORMAT_KEY = b"format"
-
-
-class _SharedEnv:
-    def __init__(self, env: Any) -> None:
-        self.env = env
-        self.refs = 1
-
-
-# LMDB permits exactly one environment handle per path per process; concurrent
-# access from other processes is handled by LMDB's own file locks. Multiple
-# DiskCache instances in one process therefore share a refcounted environment,
-# and the first opener's map_size wins for the life of the process.
-_ENV_REGISTRY: dict[str, _SharedEnv] = {}
-_ENV_LOCK = threading.Lock()
-
-
-def _acquire_env(path: str, map_size: int) -> tuple[str, Any]:
-    registry_key = os.path.realpath(path)
-    with _ENV_LOCK:
-        shared = _ENV_REGISTRY.get(registry_key)
-        if shared is not None:
-            shared.refs += 1
-            return registry_key, shared.env
-        try:
-            # sync=False trades durability of the last few writes for speed.
-            # A crash can lose recent entries, never corrupt the store, and a
-            # lost entry only costs one recompute.
-            env = lmdb.open(
-                path,
-                map_size=map_size,
-                max_dbs=3,
-                subdir=True,
-                sync=False,
-                metasync=False,
-            )
-        except lmdb.Error as exc:
-            raise PersistentCacheError(f"failed to open persistent cache at {path!r}: {exc}") from exc
-        _ENV_REGISTRY[registry_key] = _SharedEnv(env)
-        return registry_key, env
-
-
-def _release_env(registry_key: str) -> None:
-    with _ENV_LOCK:
-        shared = _ENV_REGISTRY.get(registry_key)
-        if shared is None:
-            return
-        shared.refs -= 1
-        if shared.refs <= 0:
-            del _ENV_REGISTRY[registry_key]
-            shared.env.sync(True)
-            shared.env.close()
-
-
-def entry_key(kind: str, function_id: str, args_blob: bytes) -> bytes:
-    """Deterministic cache address: Hash(kind + name + Hash(args))."""
-    args_hash = hashlib.blake2b(args_blob, digest_size=20).digest()
-    h = hashlib.blake2b(digest_size=20)
-    h.update(kind.encode("utf-8"))
-    h.update(b"\x00")
-    h.update(function_id.encode("utf-8"))
-    h.update(b"\x00")
-    h.update(args_hash)
-    return h.digest()
-
-
-class DiskCache:
-    def __init__(self, cache_dir: str | os.PathLike[str], *, map_size: int) -> None:
-        if lmdb is None:
-            raise PersistentCacheError(LMDB_INSTALL_HINT)
-        _canonical.require_msgpack()
-        path = os.fspath(cache_dir)
-        os.makedirs(path, exist_ok=True)
-        self._registry_key, self._env = _acquire_env(path, map_size)
-        self._meta = self._env.open_db(b"meta")
-        self._blobs = self._env.open_db(b"blobs")
-        self._sys = self._env.open_db(b"sys")
-        self._closed = False
-        self._ensure_format()
-
-    @property
-    def path(self) -> str:
-        return self._env.path()
-
-    def _ensure_format(self) -> None:
-        stamp = DISK_FORMAT.to_bytes(4, "big")
-        with self._env.begin(write=True) as txn:
-            current = txn.get(_FORMAT_KEY, db=self._sys)
-            if current == stamp:
-                return
-            if current is not None:
-                txn.drop(self._meta, delete=False)
-                txn.drop(self._blobs, delete=False)
-            txn.put(_FORMAT_KEY, stamp, db=self._sys)
-
-    def load_entry(self, key: bytes) -> dict[str, Any] | None:
-        with self._env.begin() as txn:
-            raw = txn.get(key, db=self._meta)
-        if raw is None:
-            return None
-        try:
-            record = _canonical.decode(bytes(raw))
-        except Exception:
-            return None
-        if not isinstance(record, dict):
-            return None
-        return record
-
-    def load_blob(self, value_hash: str) -> bytes | None:
-        with self._env.begin() as txn:
-            raw = txn.get(value_hash.encode("ascii"), db=self._blobs)
-        return None if raw is None else bytes(raw)
-
-    def store_entry(self, key: bytes, record: dict[str, Any], value_hash: str, value_blob: bytes) -> None:
-        record_blob = _canonical.encode(record)
-        try:
-            with self._env.begin(write=True) as txn:
-                txn.put(value_hash.encode("ascii"), value_blob, db=self._blobs)
-                txn.put(key, record_blob, db=self._meta)
-        except lmdb.MapFullError as exc:
-            raise PersistentCacheError(
-                f"persistent cache at {self.path!r} is full; pass a larger cache_map_size "
-                "to Engine, or clear the cache with engine.clear_disk_cache()."
-            ) from exc
-
-    def clear(self) -> None:
-        with self._env.begin(write=True) as txn:
-            txn.drop(self._meta, delete=False)
-            txn.drop(self._blobs, delete=False)
-
-    def retain(self, wanted_entries: set[bytes], wanted_blobs: set[str]) -> None:
-        """Drop all meta entries and blobs not in the provided sets."""
-        with self._env.begin(write=True) as txn:
-            drop_meta = []
-            with txn.cursor(db=self._meta) as curs:
-                if curs.first():
-                    for key in curs.iternext(keys=True, values=False):
-                        if key not in wanted_entries:
-                            drop_meta.append(key)
-            for k in drop_meta:
-                txn.delete(k, db=self._meta)
-
-            drop_blobs = []
-            with txn.cursor(db=self._blobs) as curs:
-                if curs.first():
-                    for key in curs.iternext(keys=True, values=False):
-                        if key.decode("ascii") not in wanted_blobs:
-                            drop_blobs.append(key)
-            for k in drop_blobs:
-                txn.delete(k, db=self._blobs)
-
-    def close(self) -> None:
-        if not self._closed:
-            self._closed = True
-            _release_env(self._registry_key)
+"""LMDB-backed persistent store for query metadata and value blobs.
+
+Layout: one LMDB environment per ``cache_dir`` with three named databases.
+``meta`` maps a deterministic entry key to a packed record describing a query
+result (value fingerprint, dependency fingerprints, accumulator effects).
+``blobs`` is content-addressed: value fingerprint -> canonical value bytes.
+``sys`` holds the on-disk format stamp; a mismatched stamp wipes the cache,
+which is always safe because everything here can be recomputed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import threading
+from typing import Any
+
+from . import _canonical
+from ._errors import PersistentCacheError
+
+try:
+    import lmdb
+except ImportError:  # pragma: no cover - exercised via monkeypatch in tests
+    lmdb = None  # type: ignore[assignment]
+
+LMDB_INSTALL_HINT = (
+    "cascade persistent caching requires the 'lmdb' package for the on-disk store; "
+    "there is no fallback. Install it with: pip install lmdb"
+)
+
+DISK_FORMAT = 1
+_FORMAT_KEY = b"format"
+
+
+class _SharedEnv:
+    def __init__(self, env: Any) -> None:
+        self.env = env
+        self.refs = 1
+
+
+# LMDB permits exactly one environment handle per path per process; concurrent
+# access from other processes is handled by LMDB's own file locks. Multiple
+# DiskCache instances in one process therefore share a refcounted environment,
+# and the first opener's map_size wins for the life of the process.
+_ENV_REGISTRY: dict[str, _SharedEnv] = {}
+_ENV_LOCK = threading.Lock()
+
+
+def _acquire_env(path: str, map_size: int) -> tuple[str, Any]:
+    registry_key = os.path.realpath(path)
+    with _ENV_LOCK:
+        shared = _ENV_REGISTRY.get(registry_key)
+        if shared is not None:
+            shared.refs += 1
+            return registry_key, shared.env
+        try:
+            # sync=False trades durability of the last few writes for speed.
+            # A crash can lose recent entries, never corrupt the store, and a
+            # lost entry only costs one recompute.
+            env = lmdb.open(
+                path,
+                map_size=map_size,
+                max_dbs=3,
+                subdir=True,
+                sync=False,
+                metasync=False,
+            )
+        except lmdb.Error as exc:
+            raise PersistentCacheError(f"failed to open persistent cache at {path!r}: {exc}") from exc
+        _ENV_REGISTRY[registry_key] = _SharedEnv(env)
+        return registry_key, env
+
+
+def _release_env(registry_key: str) -> None:
+    with _ENV_LOCK:
+        shared = _ENV_REGISTRY.get(registry_key)
+        if shared is None:
+            return
+        shared.refs -= 1
+        if shared.refs <= 0:
+            del _ENV_REGISTRY[registry_key]
+            shared.env.sync(True)
+            shared.env.close()
+
+
+def entry_key(kind: str, function_id: str, args_blob: bytes) -> bytes:
+    """Deterministic cache address: Hash(kind + name + Hash(args))."""
+    args_hash = hashlib.blake2b(args_blob, digest_size=20).digest()
+    h = hashlib.blake2b(digest_size=20)
+    h.update(kind.encode("utf-8"))
+    h.update(b"\x00")
+    h.update(function_id.encode("utf-8"))
+    h.update(b"\x00")
+    h.update(args_hash)
+    return h.digest()
+
+
+class DiskCache:
+    def __init__(self, cache_dir: str | os.PathLike[str], *, map_size: int) -> None:
+        if lmdb is None:
+            raise PersistentCacheError(LMDB_INSTALL_HINT)
+        _canonical.require_msgpack()
+        path = os.fspath(cache_dir)
+        os.makedirs(path, exist_ok=True)
+        self._registry_key, self._env = _acquire_env(path, map_size)
+        self._meta = self._env.open_db(b"meta")
+        self._blobs = self._env.open_db(b"blobs")
+        self._sys = self._env.open_db(b"sys")
+        self._closed = False
+        self._ensure_format()
+
+    @property
+    def path(self) -> str:
+        return self._env.path()
+
+    def _ensure_format(self) -> None:
+        stamp = DISK_FORMAT.to_bytes(4, "big")
+        with self._env.begin(write=True) as txn:
+            current = txn.get(_FORMAT_KEY, db=self._sys)
+            if current == stamp:
+                return
+            if current is not None:
+                txn.drop(self._meta, delete=False)
+                txn.drop(self._blobs, delete=False)
+            txn.put(_FORMAT_KEY, stamp, db=self._sys)
+
+    def load_entry(self, key: bytes) -> dict[str, Any] | None:
+        with self._env.begin() as txn:
+            raw = txn.get(key, db=self._meta)
+        if raw is None:
+            return None  # pragma: no cover
+        try:
+            record = _canonical.decode(bytes(raw))
+        except Exception:  # pragma: no cover
+            return None  # pragma: no cover
+        if not isinstance(record, dict):
+            return None  # pragma: no cover
+        return record
+
+    def load_blob(self, value_hash: str) -> bytes | None:
+        with self._env.begin() as txn:
+            raw = txn.get(value_hash.encode("ascii"), db=self._blobs)
+        return None if raw is None else bytes(raw)  # pragma: no cover
+
+    def store_entry(self, key: bytes, record: dict[str, Any], value_hash: str, value_blob: bytes) -> None:
+        record_blob = _canonical.encode(record)
+        try:
+            with self._env.begin(write=True) as txn:
+                txn.put(value_hash.encode("ascii"), value_blob, db=self._blobs)
+                txn.put(key, record_blob, db=self._meta)
+        except lmdb.MapFullError as exc:
+            raise PersistentCacheError(
+                f"persistent cache at {self.path!r} is full; pass a larger cache_map_size "
+                "to Engine, or clear the cache with engine.clear_disk_cache()."
+            ) from exc
+
+    def clear(self) -> None:
+        with self._env.begin(write=True) as txn:
+            txn.drop(self._meta, delete=False)
+            txn.drop(self._blobs, delete=False)
+
+    def retain(self, wanted_entries: set[bytes], wanted_blobs: set[str]) -> None:
+        """Drop all meta entries and blobs not in the provided sets."""
+        with self._env.begin(write=True) as txn:
+            drop_meta = []
+            with txn.cursor(db=self._meta) as curs:
+                if curs.first():
+                    for key in curs.iternext(keys=True, values=False):
+                        if key not in wanted_entries:
+                            drop_meta.append(key)
+            for k in drop_meta:
+                txn.delete(k, db=self._meta)
+
+            drop_blobs = []
+            with txn.cursor(db=self._blobs) as curs:
+                if curs.first():
+                    for key in curs.iternext(keys=True, values=False):
+                        if key.decode("ascii") not in wanted_blobs:
+                            drop_blobs.append(key)
+            for k in drop_blobs:
+                txn.delete(k, db=self._blobs)
+
+    def close(self) -> None:
+        if not self._closed:
+            self._closed = True
+            _release_env(self._registry_key)