query-cascade 0.2.4__tar.gz → 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- query_cascade-0.3.0/PKG-INFO +379 -0
- query_cascade-0.3.0/README.md +360 -0
- {query_cascade-0.2.4 → query_cascade-0.3.0}/pyproject.toml +59 -45
- {query_cascade-0.2.4 → query_cascade-0.3.0}/setup.cfg +4 -4
- {query_cascade-0.2.4 → query_cascade-0.3.0}/src/cascade/__init__.py +6 -0
- query_cascade-0.3.0/src/cascade/_ast_rewrite.py +464 -0
- query_cascade-0.3.0/src/cascade/_canonical.py +258 -0
- query_cascade-0.3.0/src/cascade/_collections.py +774 -0
- query_cascade-0.3.0/src/cascade/_disk_cache.py +320 -0
- {query_cascade-0.2.4 → query_cascade-0.3.0}/src/cascade/_errors.py +4 -0
- query_cascade-0.3.0/src/cascade/_evaluator.py +1520 -0
- {query_cascade-0.2.4 → query_cascade-0.3.0}/src/cascade/_graph_export.py +58 -2
- query_cascade-0.3.0/src/cascade/_incremental.py +643 -0
- {query_cascade-0.2.4 → query_cascade-0.3.0}/src/cascade/_persistence.py +3 -1
- {query_cascade-0.2.4 → query_cascade-0.3.0}/src/cascade/_runtime.py +7 -0
- {query_cascade-0.2.4 → query_cascade-0.3.0}/src/cascade/_serde.py +120 -23
- {query_cascade-0.2.4 → query_cascade-0.3.0}/src/cascade/_state.py +3 -0
- {query_cascade-0.2.4 → query_cascade-0.3.0}/src/cascade/_store.py +169 -15
- {query_cascade-0.2.4 → query_cascade-0.3.0}/src/cascade/engine.py +706 -482
- query_cascade-0.3.0/src/query_cascade.egg-info/PKG-INFO +379 -0
- {query_cascade-0.2.4 → query_cascade-0.3.0}/src/query_cascade.egg-info/SOURCES.txt +26 -1
- query_cascade-0.3.0/src/query_cascade.egg-info/requires.txt +14 -0
- query_cascade-0.3.0/tests/test_ast_rewrite.py +365 -0
- query_cascade-0.3.0/tests/test_async.py +106 -0
- query_cascade-0.3.0/tests/test_async_coverage.py +116 -0
- query_cascade-0.3.0/tests/test_code_versioning.py +119 -0
- query_cascade-0.3.0/tests/test_datetime.py +114 -0
- query_cascade-0.3.0/tests/test_disk_cache.py +894 -0
- {query_cascade-0.2.4 → query_cascade-0.3.0}/tests/test_engine.py +73 -7
- {query_cascade-0.2.4 → query_cascade-0.3.0}/tests/test_engine_compute_many.py +12 -4
- {query_cascade-0.2.4 → query_cascade-0.3.0}/tests/test_engine_concurrency.py +28 -9
- {query_cascade-0.2.4 → query_cascade-0.3.0}/tests/test_engine_persistence_and_tracing.py +44 -10
- query_cascade-0.3.0/tests/test_engine_private.py +110 -0
- query_cascade-0.3.0/tests/test_engine_private2.py +38 -0
- query_cascade-0.3.0/tests/test_engine_sweep.py +93 -0
- query_cascade-0.3.0/tests/test_error_caching.py +125 -0
- query_cascade-0.3.0/tests/test_error_caching_persistence.py +40 -0
- {query_cascade-0.2.4 → query_cascade-0.3.0}/tests/test_evaluator_and_synthetic_coverage.py +3 -1
- {query_cascade-0.2.4 → query_cascade-0.3.0}/tests/test_examples.py +3 -1
- query_cascade-0.3.0/tests/test_fixed_point.py +40 -0
- query_cascade-0.3.0/tests/test_incremental_collections.py +454 -0
- query_cascade-0.3.0/tests/test_incremental_graph.py +153 -0
- query_cascade-0.3.0/tests/test_incremental_persistence.py +232 -0
- query_cascade-0.3.0/tests/test_incremental_pipeline.py +813 -0
- {query_cascade-0.2.4 → query_cascade-0.3.0}/tests/test_internal_invariants.py +4 -1
- query_cascade-0.3.0/tests/test_memoize_false.py +79 -0
- {query_cascade-0.2.4 → query_cascade-0.3.0}/tests/test_repro_touch_memo_keyerror.py +3 -1
- {query_cascade-0.2.4 → query_cascade-0.3.0}/tests/test_scale_behavior.py +44 -16
- {query_cascade-0.2.4 → query_cascade-0.3.0}/tests/test_serde.py +10 -6
- {query_cascade-0.2.4 → query_cascade-0.3.0}/tests/test_stateful_engine_invariants.py +22 -6
- query_cascade-0.3.0/tests/test_store_coverage.py +49 -0
- query_cascade-0.3.0/tests/test_sweep_unaccessed.py +34 -0
- query_cascade-0.3.0/tests/test_ttl.py +71 -0
- query_cascade-0.2.4/PKG-INFO +0 -148
- query_cascade-0.2.4/README.md +0 -135
- query_cascade-0.2.4/src/cascade/_evaluator.py +0 -305
- query_cascade-0.2.4/src/query_cascade.egg-info/PKG-INFO +0 -148
- query_cascade-0.2.4/src/query_cascade.egg-info/requires.txt +0 -7
- {query_cascade-0.2.4 → query_cascade-0.3.0}/src/cascade/_scheduler.py +0 -0
- {query_cascade-0.2.4 → query_cascade-0.3.0}/src/cascade/_synthetic_graph.py +0 -0
- {query_cascade-0.2.4 → query_cascade-0.3.0}/src/query_cascade.egg-info/dependency_links.txt +0 -0
- {query_cascade-0.2.4 → query_cascade-0.3.0}/src/query_cascade.egg-info/top_level.txt +0 -0
- {query_cascade-0.2.4 → query_cascade-0.3.0}/tests/test_dependency_parallelism.py +0 -0
- {query_cascade-0.2.4 → query_cascade-0.3.0}/tests/test_performance.py +0 -0
- {query_cascade-0.2.4 → query_cascade-0.3.0}/tests/test_subgraph_stats_export.py +0 -0
|
@@ -0,0 +1,379 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: query-cascade
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Minimal demand-driven query framework for incremental computation.
|
|
5
|
+
Requires-Python: >=3.12
|
|
6
|
+
Description-Content-Type: text/markdown
|
|
7
|
+
Provides-Extra: disk
|
|
8
|
+
Requires-Dist: libmdbx; extra == "disk"
|
|
9
|
+
Requires-Dist: msgpack; extra == "disk"
|
|
10
|
+
Provides-Extra: dev
|
|
11
|
+
Requires-Dist: hypothesis; extra == "dev"
|
|
12
|
+
Requires-Dist: libmdbx; extra == "dev"
|
|
13
|
+
Requires-Dist: msgpack; extra == "dev"
|
|
14
|
+
Requires-Dist: mutmut; extra == "dev"
|
|
15
|
+
Requires-Dist: pytest; extra == "dev"
|
|
16
|
+
Requires-Dist: pytest-asyncio; extra == "dev"
|
|
17
|
+
Requires-Dist: pytest-cov; extra == "dev"
|
|
18
|
+
Requires-Dist: ruff; extra == "dev"
|
|
19
|
+
|
|
20
|
+
# Cascade Query
|
|
21
|
+
|
|
22
|
+
Cascade Query is a Python library for incremental dependency tracking. It caches function results and re-executes them only when their specific inputs or upstream dependencies change.
|
|
23
|
+
|
|
24
|
+
[](https://pypi.org/project/query-cascade/)
|
|
25
|
+
[](https://pypi.org/project/query-cascade/)
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## 1. Introduction & Quickstart
|
|
30
|
+
|
|
31
|
+
### Core Principles
|
|
32
|
+
|
|
33
|
+
1. **Automatic Caching:** Results are stored. If dependencies are unchanged, the function body does not execute.
|
|
34
|
+
2. **Dependency Tracking:** Cascade records every `@engine.input` or `@engine.query` accessed during execution.
|
|
35
|
+
3. **Targeted Updates:** When an input changes, Cascade identifies and invalidates only the affected downstream functions.
|
|
36
|
+
4. **Early Bail-out:** If a function's output remains identical after its dependencies change, re-computation stops for that branch.
|
|
37
|
+
|
|
38
|
+
### Installation
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
pip install query-cascade
|
|
42
|
+
# Or to enable persistent disk caching:
|
|
43
|
+
pip install query-cascade[disk]
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
### Quickstart
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
import time
|
|
50
|
+
from cascade import Engine
|
|
51
|
+
|
|
52
|
+
engine = Engine()
|
|
53
|
+
|
|
54
|
+
@engine.input
|
|
55
|
+
def user_id():
|
|
56
|
+
return "user_1"
|
|
57
|
+
|
|
58
|
+
@engine.query
|
|
59
|
+
def fetch_data():
|
|
60
|
+
time.sleep(2)
|
|
61
|
+
return {"id": user_id(), "data": "value"}
|
|
62
|
+
|
|
63
|
+
@engine.query
|
|
64
|
+
def get_result():
|
|
65
|
+
data = fetch_data()
|
|
66
|
+
return f"Result for {data['id']}"
|
|
67
|
+
|
|
68
|
+
# First run: Executes for 2 seconds.
|
|
69
|
+
print(get_result())
|
|
70
|
+
|
|
71
|
+
# Second run: Returns immediately from cache.
|
|
72
|
+
print(get_result())
|
|
73
|
+
|
|
74
|
+
# Update input:
|
|
75
|
+
user_id.set("user_2")
|
|
76
|
+
|
|
77
|
+
# Third run: Executes for 2 seconds to refresh.
|
|
78
|
+
print(get_result())
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## 2. Core Concepts
|
|
84
|
+
|
|
85
|
+
### Engine Initialization & Configuration
|
|
86
|
+
|
|
87
|
+
The `Engine` manages caching, execution, and state tracking.
|
|
88
|
+
|
|
89
|
+
* **`Engine(*, max_entries=10000, trace_limit=50000, stats=False, cache_dir=None, cache_map_size=2**30, incremental=True)`**: Initializes the engine.
|
|
90
|
+
* `max_entries` sets the limit for the Least Recently Used (LRU) in-memory cache.
|
|
91
|
+
* Passing `cache_dir` enables persistent disk caching.
|
|
92
|
+
|
|
93
|
+
### Defining Nodes: `@engine.input` and `@engine.query`
|
|
94
|
+
|
|
95
|
+
* **`@engine.input`**: Decorator for mutable data roots.
|
|
96
|
+
* `input.set(value)`: Updates the value and increments the global revision.
|
|
97
|
+
* `input.set(*args, value=value)`: Updates a keyed input.
|
|
98
|
+
* **`@engine.query`**: Decorator for cached computations. Re-evaluates only if upstream data changes.
|
|
99
|
+
|
|
100
|
+
### Snapshots & Transactions (Input Debouncing)
|
|
101
|
+
|
|
102
|
+
* **`engine.snapshot()`**: Returns a `Snapshot` object pinning the current global revision. Use `query(snapshot=s)` to read data as it existed at that revision.
|
|
103
|
+
* **`engine.transaction()`**: When updating multiple inputs, intermediate read states ("flapping") can cause inconsistent evaluations. Use a transaction block to batch updates so they are committed atomically.
|
|
104
|
+
|
|
105
|
+
```python
|
|
106
|
+
with engine.transaction():
|
|
107
|
+
theme.set("dark")
|
|
108
|
+
layout.set("grid")
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## 3. Execution Modes
|
|
114
|
+
|
|
115
|
+
### Synchronous Execution
|
|
116
|
+
Standard functions evaluate eagerly when called.
|
|
117
|
+
|
|
118
|
+
### Asynchronous Execution
|
|
119
|
+
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.
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
import asyncio
|
|
123
|
+
from cascade import Engine
|
|
124
|
+
|
|
125
|
+
engine = Engine()
|
|
126
|
+
|
|
127
|
+
@engine.query
|
|
128
|
+
async def fetch_user(uid: str):
|
|
129
|
+
await asyncio.sleep(0.5) # Network I/O
|
|
130
|
+
return {"id": uid, "name": "Alice"}
|
|
131
|
+
|
|
132
|
+
@engine.query
|
|
133
|
+
async def process_user(uid: str):
|
|
134
|
+
# Await downstream async queries seamlessly
|
|
135
|
+
user = await fetch_user(uid)
|
|
136
|
+
return user["name"].upper()
|
|
137
|
+
|
|
138
|
+
async def main():
|
|
139
|
+
print(await process_user("123"))
|
|
140
|
+
|
|
141
|
+
asyncio.run(main())
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
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.
|
|
145
|
+
|
|
146
|
+
### Parallel & Background Execution
|
|
147
|
+
* **`engine.submit(query, *args, executor=None)`**: Schedules a query for background execution. Returns a `concurrent.futures.Future`.
|
|
148
|
+
* **`engine.compute_many(calls, workers=None)`**: Executes a list of queries in parallel using a thread pool. Blocks until all are complete and returns a list of results.
|
|
149
|
+
* **`engine.compute_many_stream(calls, workers=None)`**: Yields completed results as each call finishes. Yields `(index, value, call_effects)` in completion order.
|
|
150
|
+
* **`engine.shutdown(*, wait=True, cancel_futures=False)`**: Shuts down the default thread pool executor used by `submit`.
|
|
151
|
+
* **`QueryCancelled`**: Exception raised if a background query's dependencies change before it completes.
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## 4. Cache Management & Invalidations
|
|
156
|
+
|
|
157
|
+
### Targeted Updates & Early Bail-out
|
|
158
|
+
If a function's logic evaluates to a result identical to its previous run, early bail-out prevents re-computation of downstream queries.
|
|
159
|
+
|
|
160
|
+
### Code-Aware Auto-Invalidation
|
|
161
|
+
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.
|
|
162
|
+
|
|
163
|
+
### Time-To-Live (TTL) Caching
|
|
164
|
+
Cascade supports expiring cache entries automatically based on wall-clock time. By passing the `ttl` flag to `@engine.query`, you can guarantee that a node will recompute its value if it is accessed after the specified number of seconds has elapsed.
|
|
165
|
+
|
|
166
|
+
```python
|
|
167
|
+
@engine.query(ttl=5.0)
|
|
168
|
+
def fetch_external_data():
|
|
169
|
+
return request.get("https://api.example.com/data")
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
### Error Caching
|
|
173
|
+
By default, queries intercept and cache exceptions (excluding control flow exceptions like `QueryCancelled`).
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
@engine.query(cache_exceptions=(ValueError, TypeError))
|
|
177
|
+
def parse(source: str):
|
|
178
|
+
if not source:
|
|
179
|
+
raise ValueError("Empty source")
|
|
180
|
+
return {"ast": source}
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
### Pass-Through Queries (`memoize=False`)
|
|
184
|
+
For intermediate queries generating large outputs, set `memoize=False`. This saves significant memory. Downstream nodes will still accurately detect when the query's inputs change, and the unmemoized query will recompute its output on-demand when an active caller needs it.
|
|
185
|
+
|
|
186
|
+
```python
|
|
187
|
+
@engine.query(memoize=False)
|
|
188
|
+
def mapped_data() -> list[int]:
|
|
189
|
+
data = raw_data()
|
|
190
|
+
return [x * 2 for x in data]
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
### Garbage Collection & Pruning
|
|
194
|
+
* **`engine.prune(roots, vacuum_disk=False)`**: Removes cached query results from the in-memory LRU cache that are not reachable from the specified roots. Set `vacuum_disk=True` to deep vacuum the persistent MDBX disk cache.
|
|
195
|
+
* **`engine.access_id`**: Property returning a monotonically increasing sequence number for memo accesses.
|
|
196
|
+
* **`engine.sweep_unaccessed(since_access_id)`**: Evicts all memos that haven't been accessed since `since_access_id`. Useful for generational garbage collection.
|
|
197
|
+
|
|
198
|
+
---
|
|
199
|
+
|
|
200
|
+
## 5. State, Side-Effects & Persistence
|
|
201
|
+
|
|
202
|
+
### Side-Effect Accumulators
|
|
203
|
+
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.
|
|
204
|
+
|
|
205
|
+
```python
|
|
206
|
+
warnings = engine.accumulator("warnings")
|
|
207
|
+
|
|
208
|
+
@engine.query
|
|
209
|
+
def validate_data():
|
|
210
|
+
data = fetch_data()
|
|
211
|
+
if not data:
|
|
212
|
+
warnings.push("No data found")
|
|
213
|
+
return data
|
|
214
|
+
|
|
215
|
+
# On cache hit, 'warnings' are re-populated into the effects dictionary.
|
|
216
|
+
effects = {}
|
|
217
|
+
validate_data(effects=effects)
|
|
218
|
+
print(effects["warnings"])
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
### Persistent Disk Caching
|
|
222
|
+
Passing `cache_dir` to the `Engine` turns on zero-config persistence. Cascade provisions an embedded MDBX store, serializes query results with a deterministic msgpack encoding, and fingerprints every input value by hashing its serialized bytes with blake2b.
|
|
223
|
+
|
|
224
|
+
```python
|
|
225
|
+
from cascade import Engine
|
|
226
|
+
engine = Engine(max_entries=10_000, cache_dir=".cascade_cache")
|
|
227
|
+
```
|
|
228
|
+
* `libmdbx` and `msgpack` are required (`pip install query-cascade[disk]`).
|
|
229
|
+
* Values and arguments must be serializable (primitives, bytes, lists, dicts, dataclasses, etc.).
|
|
230
|
+
* **`engine.clear_disk_cache()`**: Deletes every entry in the persistent disk cache.
|
|
231
|
+
|
|
232
|
+
### Export / Import
|
|
233
|
+
* **`engine.save(path)` / `engine.load(path)`**: Persists all inputs and cached results to a SQLite database. Note: Collection event logs are not saved here, use persistent collections instead.
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
## 6. Observability & Debugging
|
|
238
|
+
|
|
239
|
+
### Graph Inspection & Visualization
|
|
240
|
+
* **`engine.inspect_graph(condense=False)`**: Returns a dictionary of all nodes and edges in the dependency graph.
|
|
241
|
+
* **`engine.subgraph(roots, direction="deps")`**: Filters the graph to the dependency chain of the specified root nodes.
|
|
242
|
+
|
|
243
|
+
Cascade provides renderers for the dependency graph:
|
|
244
|
+
```python
|
|
245
|
+
from cascade import export_dot, export_mermaid
|
|
246
|
+
|
|
247
|
+
graph = engine.inspect_graph()
|
|
248
|
+
# Generate Graphviz DOT format
|
|
249
|
+
dot_text = export_dot(graph)
|
|
250
|
+
# Generate Mermaid flowchart format
|
|
251
|
+
mermaid_text = export_mermaid(graph)
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
### Performance Metrics
|
|
255
|
+
Set `stats=True` or use `engine.enable_stats()` to track execution timing.
|
|
256
|
+
* **`engine.enable_stats(enabled=True)`**: Dynamically enables or disables performance tracking.
|
|
257
|
+
* **`engine.stats_summary()`**: Returns wall-clock time spent in function bodies and cache eviction counts.
|
|
258
|
+
* **`engine.reset_stats()`**: Clears accumulated timing data.
|
|
259
|
+
|
|
260
|
+
### Event Tracing
|
|
261
|
+
* **`engine.traces()`**: Returns a list of `TraceEvent` objects detailing internal operations (like recomputes, backdates).
|
|
262
|
+
* **`engine.clear_traces()`**: Clears the internal trace buffer.
|
|
263
|
+
|
|
264
|
+
---
|
|
265
|
+
|
|
266
|
+
## 7. Incremental Collections & Native Map/Reduce
|
|
267
|
+
|
|
268
|
+
`CascadeList`, `CascadeSet`, and `CascadeDict` behave like their builtin counterparts, but every mutation appends a diff to an event log. Queries written with ordinary comprehensions and reducers are rewritten at registration time into incremental pipelines that consume only new diffs. Appending one element to a list of a million reruns your mapping function once.
|
|
269
|
+
|
|
270
|
+
```python
|
|
271
|
+
from cascade import Engine, CascadeList
|
|
272
|
+
|
|
273
|
+
engine = Engine()
|
|
274
|
+
docs = CascadeList(engine, ["alpha", "beta", "gamma"], name="docs")
|
|
275
|
+
|
|
276
|
+
@engine.query
|
|
277
|
+
def long_doc_count():
|
|
278
|
+
# Standard Python. Rewritten into filter -> len over the diff stream.
|
|
279
|
+
return len([d for d in docs if len(d) > 4])
|
|
280
|
+
|
|
281
|
+
long_doc_count() # walks all elements once
|
|
282
|
+
docs.append("delta") # one diff
|
|
283
|
+
long_doc_count() # processes only "delta"
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
### The collections
|
|
287
|
+
|
|
288
|
+
* **`CascadeList`** emits insert/update/remove diffs with hidden monotonic uids.
|
|
289
|
+
* **`CascadeSet`** emits add/remove diffs.
|
|
290
|
+
* **`CascadeDict`** emits upsert/remove diffs.
|
|
291
|
+
|
|
292
|
+
### What gets rewritten
|
|
293
|
+
|
|
294
|
+
Rewriting covers comprehensions (`[...]`, `{...}`, `{k: v ...}`), `map`, `filter`, `reversed`, and reducers: `sum`, `len`, `min`, `max`, `any`, `all`, `sorted`, `list`, `set`, `dict`, and string-literal `.join`.
|
|
295
|
+
|
|
296
|
+
| Reducer | Ingest per diff | Finalize |
|
|
297
|
+
|---------|-----------------|----------|
|
|
298
|
+
| `sum`, `len`, `any`, `all` | O(1) | O(1) |
|
|
299
|
+
| `min`, `max` | O(log N) | O(1) |
|
|
300
|
+
| `sorted` | O(log N) | O(output) |
|
|
301
|
+
| `list`, `set`, `dict`, `.join` | O(1) | O(output) |
|
|
302
|
+
| `reversed` | O(1) positional flip | inherited |
|
|
303
|
+
|
|
304
|
+
* Arbitrary `for` loops are never rewritten, but invalidate through read tracking.
|
|
305
|
+
* `enumerate()` and `zip()` sources are explicitly excluded.
|
|
306
|
+
* Opt out globally via `Engine(incremental=False)` or per-query `@engine.query(incremental=False)`.
|
|
307
|
+
|
|
308
|
+
### Batching Mutations for Disk Performance
|
|
309
|
+
|
|
310
|
+
By design, Cascade collections use an immediate write-ahead pattern for crash-safety. Every time you mutate a collection (`__setitem__`, `append()`, `add()`), Cascade immediately opens a disk transaction, writes the diff to the MDBX event log, and forces an OS sync (`fsync`).
|
|
311
|
+
|
|
312
|
+
If you iterate through a loop inserting thousands of records one by one, you will trigger thousands of physical disk syncs, resulting in extremely slow performance (e.g., waiting on disk I/O).
|
|
313
|
+
|
|
314
|
+
To avoid this, always align disk syncs with your **logical units of work** by batching bulk-inserts using `.update()` or `extend()`. This allows Cascade to group all changes into a single disk transaction:
|
|
315
|
+
|
|
316
|
+
```python
|
|
317
|
+
# SLOW (10,000 separate disk syncs)
|
|
318
|
+
for i in range(10000):
|
|
319
|
+
docs[f"doc_{i}"] = i
|
|
320
|
+
|
|
321
|
+
# FAST (1 single disk sync)
|
|
322
|
+
docs.update({f"doc_{i}": i for i in range(10000)})
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
*(Note: `.update()` behaves exactly like a standard Python dictionary. If a key already exists, it will seamlessly overwrite the old value by batching an `"upsert"` event to the underlying log, ensuring downstream queries receive the correct diffs.)*
|
|
326
|
+
|
|
327
|
+
### Persistence & Inspection
|
|
328
|
+
|
|
329
|
+
A **named** collection on an engine with `cache_dir` event-sources its log to disk automatically.
|
|
330
|
+
|
|
331
|
+
```python
|
|
332
|
+
engine = Engine(cache_dir="./cache")
|
|
333
|
+
items = CascadeList(engine, name="items", compact_every=1024)
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
* **`engine.inspect_pipelines()`**: Lists every observed pipeline with its source, logical stages, fused stage count, checkpoint revision, and consuming queries.
|
|
337
|
+
|
|
338
|
+
---
|
|
339
|
+
|
|
340
|
+
## 8. Limitations & Development
|
|
341
|
+
|
|
342
|
+
### Limitations
|
|
343
|
+
|
|
344
|
+
1. **Cycle Detection:** Cascade detects and rejects recursive function calls (cycles) with a `CycleError`.
|
|
345
|
+
2. **Thread Safety:** While Cascade supports parallel query execution, the `Engine` object itself should be modified (`.set()`, `@engine.query`) from a single thread or with external synchronization.
|
|
346
|
+
3. **Persistence Security:** `engine.load()` and the persistent disk cache resolve `@dataclass` and `NamedTuple` types via `importlib`. Only load databases or open cache directories from trusted sources.
|
|
347
|
+
4. **Python Version:** Optimization for parallel CPU-bound work requires **CPython 3.14+ free-threaded** builds with `PYTHON_GIL=0`.
|
|
348
|
+
5. **Collections & `engine.save()`:** State snapshots via `engine.save()`/`engine.load()` do not carry collection event logs; use a named collection with `cache_dir` for durable collection state.
|
|
349
|
+
|
|
350
|
+
### Examples (in `examples/`)
|
|
351
|
+
|
|
352
|
+
| Script | What it shows |
|
|
353
|
+
|--------|----------------|
|
|
354
|
+
| `compiler_pipeline.py` | `source → parse → symbols → typecheck`, warnings accumulator, cache-hit narration |
|
|
355
|
+
| `incremental_collections.py` | CascadeList/Set/Dict diffs, comprehension rewriting, O(1) ingest, pipeline inspection |
|
|
356
|
+
| `async_execution.py` | Asynchronous query evaluation and asyncio event loop integration for IO-bound work |
|
|
357
|
+
| `ttl_invalidation.py` | Expiring stale query caches automatically based on wall-clock time |
|
|
358
|
+
| `error_caching.py` | Basic exception caching to prevent repeated re-evaluation on failure |
|
|
359
|
+
| `error_caching_persistence.py` | Disk cache hydration of exceptions across process runs |
|
|
360
|
+
| `code_versioning.py` | Automatic cache invalidation when a function's bytecode logic changes |
|
|
361
|
+
| `pass_through_queries.py` | `memoize=False` tracking inputs without keeping large outputs in the LRU cache |
|
|
362
|
+
| `dynamic_macro_expansion.py` | Query that **changes downstream dependencies** at runtime |
|
|
363
|
+
| `snapshot_isolation.py` | Snapshot reads while live inputs change |
|
|
364
|
+
| `concurrent_background_work.py` | Dedup under concurrency + cancellation after input changes |
|
|
365
|
+
| `compute_many_with_accumulators.py` | `compute_many(..., effects=...)` accumulator collection |
|
|
366
|
+
| `persistence_and_inspection.py` | Save/load and graph summaries |
|
|
367
|
+
| `gil_parallel_speedup.py` | Threaded CPU benchmark: GIL vs free-threaded |
|
|
368
|
+
|
|
369
|
+
### Development & Tests
|
|
370
|
+
|
|
371
|
+
```bash
|
|
372
|
+
export PYTHON_GIL=0
|
|
373
|
+
python3.14t -m pip install -e ".[dev]"
|
|
374
|
+
python3.14t -m pytest -q --cov=src/cascade --cov-branch --cov-report=term-missing
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
* **Stateful fuzz**: `PYTHON_GIL=0 python3.14t -m pytest -q tests/test_stateful_engine_invariants.py`
|
|
378
|
+
* **Formal model**: TLA+ specs live under `docs/formal/`.
|
|
379
|
+
* **Performance suite**: `python -m benchmarks.performance_suite --report-dir artifacts/performance --assert-thresholds`
|