j-perm-sql 0.2.0__tar.gz → 0.3.0__tar.gz

{j_perm_sql-0.2.0 → j_perm_sql-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: j-perm-sql
-Version: 0.2.0
+Version: 0.3.0
 Summary: j-perm plugin for SQL
 Author-email: Roman <kuschanow@gmail.com>
 License: MIT
@@ -10,7 +10,7 @@ Project-URL: Tracker, https://github.com/kuschanow/j-perm/issues
 Project-URL: Documentation, https://github.com/kuschanow/j-perm
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: j-perm>=1.9.0
+Requires-Dist: j-perm>=1.10.0
 
 # j-perm-sql
 
@@ -39,8 +39,10 @@ A [j-perm](https://github.com/kuschanow/j-perm) plugin that builds and executes
 pip install j-perm-sql
 ```
 
-Requires `j-perm >= 1.9.0` (the version that made `run_pipeline` a passthrough
-invoker, which this plugin relies on).
+Requires `j-perm >= 1.10.0`: 1.9.0 made `run_pipeline` a passthrough invoker
+(which this plugin relies on), and 1.10.0 added the `nested_spec_pipeline`
+compile hook and per-pipeline `CompiledSpec` execution that let `op: sql` be
+compiled end-to-end (see [Compilation](#compilation)).
 
 ## Quick start
 
@@ -202,6 +204,25 @@ install_sql(engine, run_sql)                  # async
 await engine.apply_async(spec, source=…, dest=…)
 ```
 
+## Compilation
+
+`op: sql` / `op: sql_write` are compilable. `engine.compile(spec)` compiles the
+`query` subtree against the isolated SQL pipeline (the engine never needs to
+understand the SQL constructs — it routes the nested spec through the registered
+pipeline by name), and the rendered tree is dispatched through the compiled path
+with per-node memoisation. Re-applying the same `CompiledSpec` keeps every node
+compiled; only `$val` data is re-bound from the live context on each run.
+
+```python
+compiled = engine.compile([{"op": "sql", "to": "/rows", "query": query}])
+compiled.apply(source={"wanted": 1}, dest={})    # renders + executes, fully compiled
+compiled.apply(source={"wanted": 2}, dest={})    # reuses compiled nodes, re-binds values
+```
+
+This requires the `nested_spec_pipeline` compile hook and per-pipeline
+`CompiledSpec` execution added in the core engine (see the "What gets compiled"
+section of the main j-perm README).
+
 ## Construct reference
 
 **Query**

{j_perm_sql-0.2.0 → j_perm_sql-0.3.0}/README.md

@@ -25,8 +25,10 @@ A [j-perm](https://github.com/kuschanow/j-perm) plugin that builds and executes
 pip install j-perm-sql
 ```
 
-Requires `j-perm >= 1.9.0` (the version that made `run_pipeline` a passthrough
-invoker, which this plugin relies on).
+Requires `j-perm >= 1.10.0`: 1.9.0 made `run_pipeline` a passthrough invoker
+(which this plugin relies on), and 1.10.0 added the `nested_spec_pipeline`
+compile hook and per-pipeline `CompiledSpec` execution that let `op: sql` be
+compiled end-to-end (see [Compilation](#compilation)).
 
 ## Quick start
 
@@ -188,6 +190,25 @@ install_sql(engine, run_sql)                  # async
 await engine.apply_async(spec, source=…, dest=…)
 ```
 
+## Compilation
+
+`op: sql` / `op: sql_write` are compilable. `engine.compile(spec)` compiles the
+`query` subtree against the isolated SQL pipeline (the engine never needs to
+understand the SQL constructs — it routes the nested spec through the registered
+pipeline by name), and the rendered tree is dispatched through the compiled path
+with per-node memoisation. Re-applying the same `CompiledSpec` keeps every node
+compiled; only `$val` data is re-bound from the live context on each run.
+
+```python
+compiled = engine.compile([{"op": "sql", "to": "/rows", "query": query}])
+compiled.apply(source={"wanted": 1}, dest={})    # renders + executes, fully compiled
+compiled.apply(source={"wanted": 2}, dest={})    # reuses compiled nodes, re-binds values
+```
+
+This requires the `nested_spec_pipeline` compile hook and per-pipeline
+`CompiledSpec` execution added in the core engine (see the "What gets compiled"
+section of the main j-perm README).
+
 ## Construct reference
 
 **Query**

{j_perm_sql-0.2.0 → j_perm_sql-0.3.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "j-perm-sql"
-version = "0.2.0"
+version = "0.3.0"
 description = "j-perm plugin for SQL"
 authors = [
     { name = "Roman", email = "kuschanow@gmail.com" },
@@ -18,7 +18,7 @@ requires-python = ">=3.10"
 license = { text = "MIT" }
 
 dependencies = [
-    "j-perm>=1.9.0",
+    "j-perm>=1.10.0",
 ]
 
 [tool.pytest.ini_options]

{j_perm_sql-0.2.0 → j_perm_sql-0.3.0}/src/j_perm_sql/handler.py

@@ -17,9 +17,20 @@ shared :class:`SqlRenderer`.
 from __future__ import annotations
 
 from j_perm import ActionHandler, AsyncActionHandler
+from j_perm.core import Compound
 
 from .dialect import RenderOptions
-from .render import ACTIVE_PIPELINE_KEY, SQL_PIPELINE_NAME, is_fragment
+from .render import (
+    ACTIVE_PIPELINE_KEY,
+    COMPILE_CACHE_KEY,
+    SQL_PIPELINE_NAME,
+    is_fragment,
+)
+
+#: Attribute under which a compiled query spec carries its per-node compilation
+#: cache (see :func:`j_perm_sql.render.render`).  Stored on the spec — not in the
+#: context — so it survives across runs of the same compiled query.
+_NODE_CACHE_ATTR = "_sql_node_cache"
 
 
 class SqlRenderer:
@@ -34,24 +45,64 @@ class SqlRenderer:
         self.opts = opts
         self.pipeline_name = pipeline_name
 
-    def render(self, query, ctx) -> tuple:
+    def _render_ctx(self, ctx, extra_metadata: dict | None = None):
         # Render against a scratch dest so the real document is never clobbered,
         # but expose the real dest under _real_dest so @: pointers inside $val
         # can still read the document being built.  The active pipeline name is
         # threaded through metadata so recursion stays in this pipeline.
-        render_ctx = ctx.copy(
-            new_dest={},
-            new_metadata={
-                **ctx.metadata,
-                "_real_dest": ctx.dest,
-                ACTIVE_PIPELINE_KEY: self.pipeline_name,
-            },
-        )
-        frag = ctx.engine.run_pipeline(self.pipeline_name, query, render_ctx).dest
+        metadata = {
+            **ctx.metadata,
+            "_real_dest": ctx.dest,
+            ACTIVE_PIPELINE_KEY: self.pipeline_name,
+        }
+        if extra_metadata:
+            metadata.update(extra_metadata)
+        return ctx.copy(new_dest={}, new_metadata=metadata)
+
+    def _finalize(self, frag) -> tuple:
         if not is_fragment(frag):
             raise ValueError("top-level SQL query must be a SQL construct")
         return self.opts.finalize(frag["sql"], frag["params"])
 
+    def render(self, query, ctx) -> tuple:
+        """Render *query* through the interpreted SQL pipeline."""
+        render_ctx = self._render_ctx(ctx)
+        frag = ctx.engine.run_pipeline(self.pipeline_name, query, render_ctx).dest
+        return self._finalize(frag)
+
+    def render_compiled(self, compiled_query, ctx) -> tuple:
+        """Render a pre-compiled query spec, reusing per-node compilation.
+
+        *compiled_query* is the :class:`~j_perm.core.CompiledSpec` produced for
+        the ``query`` key at compile time (its top node is already resolved).
+        Nested nodes are compiled lazily on first run and memoised on the spec,
+        so repeated executions of the same compiled query stay fully compiled.
+        """
+        cache = getattr(compiled_query, _NODE_CACHE_ATTR, None)
+        if cache is None:
+            cache = {}
+            setattr(compiled_query, _NODE_CACHE_ATTR, cache)
+        render_ctx = self._render_ctx(ctx, {COMPILE_CACHE_KEY: cache})
+        ctx.engine.get_pipeline(self.pipeline_name).run_compiled(compiled_query, render_ctx)
+        return self._finalize(render_ctx.dest)
+
+
+class _SqlCompound(Compound):
+    """Mixin marking the ``op: sql`` handlers as compilable.
+
+    The ``query`` subtree is compiled against the handler's isolated SQL
+    pipeline (read or write) rather than the main pipeline, so the engine never
+    needs to know the SQL constructs.
+    """
+
+    _renderer: SqlRenderer
+
+    def nested_spec_keys(self, step) -> list[str]:
+        return ["query"] if "query" in step else []
+
+    def nested_spec_pipeline(self, step, key) -> str:
+        return self._renderer.pipeline_name
+
 
 def _write_result(step, ctx, result):
     if "to" in step:
@@ -60,7 +111,7 @@ def _write_result(step, ctx, result):
     return ctx.dest
 
 
-class SqlHandler(ActionHandler):
+class SqlHandler(ActionHandler, _SqlCompound):
     """``op: sql`` with a synchronous executor ``executor(sql, params) -> result``."""
 
     def __init__(self, executor, renderer: SqlRenderer) -> None:
@@ -72,8 +123,13 @@ class SqlHandler(ActionHandler):
         result = self._executor(sql, params)
         return _write_result(step, ctx, result)
 
+    def execute_compiled(self, step, ctx, nested):
+        sql, params = self._renderer.render_compiled(nested["query"], ctx)
+        result = self._executor(sql, params)
+        return _write_result(step, ctx, result)
+
 
-class AsyncSqlHandler(AsyncActionHandler):
+class AsyncSqlHandler(AsyncActionHandler, _SqlCompound):
     """``op: sql`` with an async executor ``await executor(sql, params) -> result``."""
 
     def __init__(self, executor, renderer: SqlRenderer) -> None:
@@ -84,3 +140,8 @@ class AsyncSqlHandler(AsyncActionHandler):
         sql, params = self._renderer.render(step["query"], ctx)
         result = await self._executor(sql, params)
         return _write_result(step, ctx, result)
+
+    async def execute_compiled(self, step, ctx, nested):
+        sql, params = self._renderer.render_compiled(nested["query"], ctx)
+        result = await self._executor(sql, params)
+        return _write_result(step, ctx, result)

{j_perm_sql-0.2.0 → j_perm_sql-0.3.0}/src/j_perm_sql/render.py

@@ -28,6 +28,12 @@ SQL_PIPELINE_NAME = "sql"
 #: pipeline when absent.
 ACTIVE_PIPELINE_KEY = "_sql_pipeline"
 
+#: Metadata key carrying the per-node compilation cache (``{id(node): CompiledSpec}``)
+#: for the *compiled* render path.  Present only when the top-level ``op: sql``
+#: was reached through a compiled pipeline; absent for the plain interpreted path
+#: (then :func:`render` dispatches through ``run_pipeline`` as before).
+COMPILE_CACHE_KEY = "_sql_compile_cache"
+
 #: Keys whose presence marks a node as a *query* (must be parenthesised when
 #: used as an operand, subquery, or derived table).
 _QUERY_KEYS = frozenset(
@@ -56,9 +62,25 @@ def render(node: Any, ctx) -> Any:
     The active pipeline name is read from ``ctx.metadata`` (set by the renderer)
     so recursion stays within the same pipeline the top-level operation chose;
     it defaults to the read-only :data:`SQL_PIPELINE_NAME`.
+
+    When a compilation cache is active (the top-level ``op: sql`` was compiled),
+    each node is compiled once against the SQL pipeline and the resulting
+    :class:`~j_perm.core.CompiledSpec` is memoised on the cache, so subsequent
+    runs of the same compiled query skip stage processing and handler resolution
+    for every node.  The cache lives on the top-level compiled query spec, so it
+    is bounded by that query's nodes and freed together with it.
     """
     name = ctx.metadata.get(ACTIVE_PIPELINE_KEY, SQL_PIPELINE_NAME)
-    return ctx.engine.run_pipeline(name, node, ctx).dest
+    cache = ctx.metadata.get(COMPILE_CACHE_KEY)
+    if cache is None:
+        return ctx.engine.run_pipeline(name, node, ctx).dest
+    pipeline = ctx.engine.get_pipeline(name)
+    compiled = cache.get(id(node))
+    if compiled is None:
+        compiled = pipeline.compile(node, ctx)
+        cache[id(node)] = compiled
+    pipeline.run_compiled(compiled, ctx)
+    return ctx.dest
 
 
 def render_construct(node: Any, ctx) -> dict:

{j_perm_sql-0.2.0 → j_perm_sql-0.3.0}/src/j_perm_sql.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: j-perm-sql
-Version: 0.2.0
+Version: 0.3.0
 Summary: j-perm plugin for SQL
 Author-email: Roman <kuschanow@gmail.com>
 License: MIT
@@ -10,7 +10,7 @@ Project-URL: Tracker, https://github.com/kuschanow/j-perm/issues
 Project-URL: Documentation, https://github.com/kuschanow/j-perm
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: j-perm>=1.9.0
+Requires-Dist: j-perm>=1.10.0
 
 # j-perm-sql
 
@@ -39,8 +39,10 @@ A [j-perm](https://github.com/kuschanow/j-perm) plugin that builds and executes
 pip install j-perm-sql
 ```
 
-Requires `j-perm >= 1.9.0` (the version that made `run_pipeline` a passthrough
-invoker, which this plugin relies on).
+Requires `j-perm >= 1.10.0`: 1.9.0 made `run_pipeline` a passthrough invoker
+(which this plugin relies on), and 1.10.0 added the `nested_spec_pipeline`
+compile hook and per-pipeline `CompiledSpec` execution that let `op: sql` be
+compiled end-to-end (see [Compilation](#compilation)).
 
 ## Quick start
 
@@ -202,6 +204,25 @@ install_sql(engine, run_sql)                  # async
 await engine.apply_async(spec, source=…, dest=…)
 ```
 
+## Compilation
+
+`op: sql` / `op: sql_write` are compilable. `engine.compile(spec)` compiles the
+`query` subtree against the isolated SQL pipeline (the engine never needs to
+understand the SQL constructs — it routes the nested spec through the registered
+pipeline by name), and the rendered tree is dispatched through the compiled path
+with per-node memoisation. Re-applying the same `CompiledSpec` keeps every node
+compiled; only `$val` data is re-bound from the live context on each run.
+
+```python
+compiled = engine.compile([{"op": "sql", "to": "/rows", "query": query}])
+compiled.apply(source={"wanted": 1}, dest={})    # renders + executes, fully compiled
+compiled.apply(source={"wanted": 2}, dest={})    # reuses compiled nodes, re-binds values
+```
+
+This requires the `nested_spec_pipeline` compile hook and per-pipeline
+`CompiledSpec` execution added in the core engine (see the "What gets compiled"
+section of the main j-perm README).
+
 ## Construct reference
 
 **Query**

j_perm_sql-0.3.0/src/j_perm_sql.egg-info/requires.txt

@@ -0,0 +1 @@
+j-perm>=1.10.0

j_perm_sql-0.2.0/src/j_perm_sql.egg-info/requires.txt

@@ -1 +0,0 @@
-j-perm>=1.9.0