execsql2 2.16.0__py3-none-any.whl → 2.16.2__py3-none-any.whl

execsql/script/executor.py

@@ -57,7 +57,7 @@ from execsql.script.ast import (
     SqlBlock,
     SqlStatement,
 )
-from execsql.script.engine import set_dynamic_system_vars, set_static_system_vars, substitute_vars
+from execsql.script.engine import CommandList, set_dynamic_system_vars, set_static_system_vars, substitute_vars
 from execsql.script.variables import SubVarSet
 from execsql.state import RuntimeContext, active_context, get_context, xcmd_test
 from execsql.utils.errors import exception_desc, exit_now, stamp_errinfo
@@ -80,6 +80,50 @@ _VARLIKE = re.compile(r"!![$@&~#]?\w+!!", re.I)
 # on the RuntimeContext.  Kept as a comment for grep-ability.
 
 
+def _stack_localvars(ctx: RuntimeContext) -> SubVarSet | None:
+    """Build the merged local+param variable overlay from the current stack frame.
+
+    Returns ``frame.localvars.merge(frame.paramvals)`` for the top frame on
+    ``ctx.commandliststack``, or ``None`` if the stack is empty.  This mirrors
+    the legacy ``CommandList.run_and_increment()`` pattern (line 517 of
+    engine.py) so that both ``substitute_vars`` and ``get_subvarset`` (used by
+    ``x_sub``, ``x_rm_sub``, etc.) operate on the same scope.
+    """
+    if ctx.commandliststack:
+        frame = ctx.commandliststack[-1]
+        return frame.localvars.merge(frame.paramvals)
+    return None
+
+
+def _push_frame(
+    ctx: RuntimeContext,
+    name: str,
+    source: str,
+    line_no: int = 0,
+    *,
+    paramnames: list[str] | None = None,
+) -> CommandList:
+    """Push a synthetic CommandList frame onto the command-list stack.
+
+    Creates a minimal frame with a sentinel :class:`ScriptCmd` so that
+    ``current_script_line()`` and ``get_subvarset()`` work correctly.
+    Returns the frame so the caller can set ``paramvals`` or pre-populate
+    ``localvars``.
+    """
+    from execsql.script.engine import MetacommandStmt, ScriptCmd
+
+    sentinel = ScriptCmd(source, line_no, "cmd", MetacommandStmt(f"BEGIN SCRIPT {name}"))
+    frame = CommandList([sentinel], name, paramnames)
+    ctx.commandliststack.append(frame)
+    return frame
+
+
+def _pop_frame(ctx: RuntimeContext) -> None:
+    """Pop the top frame from the command-list stack."""
+    if ctx.commandliststack:
+        ctx.commandliststack.pop()
+
+
 def _convert_deferred_vars(text: str) -> str:
     """Convert deferred substitution variables to regular ones.
 
@@ -96,12 +140,13 @@ def _eval_condition(
     modifiers: list[ConditionModifier] | None = None,
 ) -> bool:
     """Evaluate a condition string with optional ANDIF/ORIF modifiers."""
-    expanded = substitute_vars(condition, ctx=ctx)
+    effective_locals = _stack_localvars(ctx)
+    expanded = substitute_vars(condition, effective_locals, ctx=ctx)
     result = xcmd_test(expanded)
 
     if modifiers:
         for mod in modifiers:
-            mod_expanded = substitute_vars(mod.condition, ctx=ctx)
+            mod_expanded = substitute_vars(mod.condition, effective_locals, ctx=ctx)
             mod_result = xcmd_test(mod_expanded)
             if mod.kind == "AND":
                 result = result and mod_result
@@ -143,7 +188,12 @@ def _exec_sql(
     ctx.status.sql_error = False
     if ctx.status.batch.in_batch():
         ctx.status.batch.using_db(ctx.dbs.current())
-    cmd = substitute_vars(text, localvars, ctx=ctx)
+    # Build localvars from the command-list stack frame so that ~ and # vars
+    # written by x_sub/get_subvarset are visible.  The stack frame is the
+    # canonical source; the `localvars` parameter is kept for backward compat
+    # but superseded when the stack is populated.
+    effective_locals = _stack_localvars(ctx) or localvars
+    cmd = substitute_vars(text, effective_locals, ctx=ctx)
     if _VARLIKE.search(cmd):
         ctx.output.write(
             f"Warning: There is a potential un-substituted variable in the command\n     {cmd}\n",
@@ -188,7 +238,9 @@ def _exec_metacommand(
     localvars: SubVarSet | None = None,
 ) -> Any:
     """Dispatch a metacommand through the dispatch table."""
-    cmd = substitute_vars(command, localvars, ctx=ctx)
+    # Build localvars from the command-list stack frame (see _exec_sql comment).
+    effective_locals = _stack_localvars(ctx) or localvars
+    cmd = substitute_vars(command, effective_locals, ctx=ctx)
     if _VARLIKE.search(cmd):
         ctx.output.write(
             f"Warning: There is a potential un-substituted variable in the command\n     {cmd}\n",
@@ -293,7 +345,8 @@ def _execute_node(
         if in_loop:
             command = _convert_deferred_vars(command)
         # Intercept BREAK before dispatch — it controls loop flow
-        expanded = substitute_vars(command, localvars, ctx=ctx)
+        effective_locals = _stack_localvars(ctx) or localvars
+        expanded = substitute_vars(command, effective_locals, ctx=ctx)
         if _BREAK_RX.match(expanded):
             raise _BreakLoop
         ctx.last_command = _FakeScriptCmd(node)
@@ -337,7 +390,8 @@ def _execute_if(
 
     # Try ELSEIF clauses
     for clause in node.elseif_clauses:
-        expanded = substitute_vars(clause.condition, ctx=ctx)
+        effective_locals = _stack_localvars(ctx)
+        expanded = substitute_vars(clause.condition, effective_locals, ctx=ctx)
         if xcmd_test(expanded):
             _execute_nodes(ctx, clause.body, node.span.file, localvars, in_loop=in_loop)
             return
@@ -358,7 +412,8 @@ def _execute_loop(
 
     if node.loop_type == "WHILE":
         while True:
-            expanded = substitute_vars(condition, ctx=ctx)
+            effective_locals = _stack_localvars(ctx)
+            expanded = substitute_vars(condition, effective_locals, ctx=ctx)
             if not xcmd_test(expanded):
                 break
             try:
@@ -371,7 +426,8 @@ def _execute_loop(
                 _execute_nodes(ctx, node.body, node.span.file, localvars, in_loop=True)
             except _BreakLoop:
                 break
-            expanded = substitute_vars(condition, ctx=ctx)
+            effective_locals = _stack_localvars(ctx)
+            expanded = substitute_vars(condition, effective_locals, ctx=ctx)
             if xcmd_test(expanded):
                 break
 
@@ -586,23 +642,35 @@ def _execute_script_native(
     script_block: ScriptBlock,
     localvars: SubVarSet | None = None,
 ) -> None:
-    """Execute a SCRIPT block natively through the AST executor."""
+    """Execute a SCRIPT block natively through the AST executor.
+
+    Pushes a :class:`CommandList` frame onto ``ctx.commandliststack`` so that
+    legacy metacommand handlers (``x_sub``, ``x_rm_sub``, ``xf_sub_defined``,
+    prompt handlers, etc.) can access ``~`` local variables and ``#`` script
+    arguments via ``get_subvarset()`` / ``commandliststack[-1]``.  The frame
+    is popped on exit (including on error) via ``try/finally``.
+    """
     from execsql.script.variables import ScriptArgSubVarSet
     from execsql.utils.strings import wo_quotes
 
     # Parse arguments (replicates ScriptExecSpec logic)
-    script_localvars = None
+    # Expand the argument string in the *caller's* scope so that references
+    # like val=!!#parent_param!! or val=!!~parent_local!! resolve correctly
+    # before we push a new scope for this script.
+    paramvals: ScriptArgSubVarSet | None = None
     if node.arguments is not None:
+        caller_locals = _stack_localvars(ctx)
+        expanded_args = substitute_vars(node.arguments, caller_locals, ctx=ctx)
         args_rx = re.compile(
             r'(?P<param>#?\w+)\s*=\s*(?P<arg>(?:(?:[^"\'\[][^,\)]*)|(?:"[^"]*")|(?:\'[^\']*\')|(?:\[[^\]]*\])))',
             re.I,
         )
-        all_args = re.findall(args_rx, node.arguments)
+        all_args = re.findall(args_rx, expanded_args)
         all_cleaned_args = [(ae[0], wo_quotes(ae[1])) for ae in all_args]
         all_prepared_args = [(ae[0] if ae[0][0] == "#" else "#" + ae[0], ae[1]) for ae in all_cleaned_args]
-        scriptvarset = ScriptArgSubVarSet()
+        paramvals = ScriptArgSubVarSet()
         for param, arg in all_prepared_args:
-            scriptvarset.add_substitution(param, arg)
+            paramvals.add_substitution(param, arg)
 
         # Validate parameter names match
         if script_block.param_names is not None:
@@ -612,7 +680,6 @@ def _execute_script_native(
                     "error",
                     other_msg=f"Formal and actual parameter name mismatch in call to {script_block.name}.",
                 )
-        script_localvars = scriptvarset
     else:
         if script_block.param_names is not None:
             raise ErrInfo(
@@ -623,39 +690,57 @@ def _execute_script_native(
                 ),
             )
 
-    # Merge script-local vars with any existing local vars
-    merged = script_localvars
+    # Push a CommandList frame onto the stack so that:
+    #   - get_subvarset() can find ~local and +outer-scope variables
+    #   - xf_sub_defined/xf_sub_empty can check ~local and #param variables
+    #   - current_script_line() returns meaningful source location
+    #   - REPL .vars/.stack commands show the correct scope
+    frame = _push_frame(
+        ctx,
+        script_block.name,
+        script_block.span.file,
+        script_block.span.start_line,
+        paramnames=script_block.param_names,
+    )
+    if paramvals is not None:
+        frame.paramvals = paramvals
 
-    def _run_body() -> None:
-        # Deep-copy the body to avoid mutation across iterations
-        body = copy.deepcopy(script_block.body)
-        _execute_nodes(ctx, body, script_block.span.file, merged, in_loop=False)
-
-    # Handle WHILE/UNTIL loops
-    # Convert deferred vars once — node.loop_condition is immutable after parsing
-    if node.loop_type is not None:
-        condition = _convert_deferred_vars(node.loop_condition)
+    try:
 
-    if node.loop_type == "WHILE":
-        while True:
-            expanded = substitute_vars(condition, ctx=ctx)
-            if not xcmd_test(expanded):
-                break
-            try:
-                _run_body()
-            except _BreakLoop:
-                break
-    elif node.loop_type == "UNTIL":
-        while True:
-            try:
-                _run_body()
-            except _BreakLoop:
-                break
-            expanded = substitute_vars(condition, ctx=ctx)
-            if xcmd_test(expanded):
-                break
-    else:
-        _run_body()
+        def _run_body() -> None:
+            # Deep-copy the body to avoid mutation across iterations
+            body = copy.deepcopy(script_block.body)
+            _execute_nodes(ctx, body, script_block.span.file, in_loop=False)
+
+        # Handle WHILE/UNTIL loops
+        # Convert deferred vars once — node.loop_condition is immutable after parsing
+        if node.loop_type is not None:
+            condition = _convert_deferred_vars(node.loop_condition)
+
+        if node.loop_type == "WHILE":
+            while True:
+                effective_locals = _stack_localvars(ctx)
+                expanded = substitute_vars(condition, effective_locals, ctx=ctx)
+                if not xcmd_test(expanded):
+                    break
+                try:
+                    _run_body()
+                except _BreakLoop:
+                    break
+        elif node.loop_type == "UNTIL":
+            while True:
+                try:
+                    _run_body()
+                except _BreakLoop:
+                    break
+                effective_locals = _stack_localvars(ctx)
+                expanded = substitute_vars(condition, effective_locals, ctx=ctx)
+                if xcmd_test(expanded):
+                    break
+        else:
+            _run_body()
+    finally:
+        _pop_frame(ctx)
 
 
 def _execute_include_native(
@@ -672,7 +757,13 @@ def _execute_include_native(
     from execsql.utils.errors import file_size_date
 
     # Substitute variables in the target path
-    target = substitute_vars(node.target, localvars, ctx=ctx).strip()
+    effective_locals = _stack_localvars(ctx) or localvars
+    target = substitute_vars(node.target, effective_locals, ctx=ctx).strip()
+
+    # Strip surrounding quotes — the AST parser captures the full target
+    # including any quotes, but the legacy dispatch regex stripped them.
+    if len(target) >= 2 and target[0] in ('"', "'") and target[-1] == target[0]:
+        target = target[1:-1]
 
     # Tilde expansion (matches x_include legacy handler)
     if len(target) > 1 and target[0] == "~" and target[1] == os.sep:
@@ -824,6 +915,11 @@ def execute(script: Script, *, ctx: RuntimeContext | None = None) -> None:
             except (OSError, ValueError):
                 ctx.include_chain.append(script.source)
         set_static_system_vars(ctx)
+        # Push a root frame so commandliststack is never empty during AST
+        # execution.  This ensures get_subvarset(), current_script_line(),
+        # xf_sub_defined(), the REPL, and all other commandliststack readers
+        # work correctly even at the top level.
+        _push_frame(ctx, "<main>", script.source)
         try:
             _execute_nodes(ctx, script.body, script.source)
         except _BreakLoop as exc:
@@ -831,3 +927,5 @@ def execute(script: Script, *, ctx: RuntimeContext | None = None) -> None:
                 type="cmd",
                 other_msg="BREAK metacommand outside of a LOOP block.",
             ) from exc
+        finally:
+            _pop_frame(ctx)

execsql/script/parser.py

@@ -95,6 +95,14 @@ _INCLUDE_RX = re.compile(
     re.I,
 )
 
+
+def _strip_quotes(s: str) -> str:
+    """Strip a matching pair of surrounding quotes from *s*."""
+    if len(s) >= 2 and s[0] in ('"', "'") and s[-1] == s[0]:
+        return s[1:-1]
+    return s
+
+
 _EXEC_SCRIPT_RX = re.compile(
     r"^\s*(?:EXEC(?:UTE)?|RUN)\s+SCRIPT"
     r"(?P<exists>\s+IF\s+EXISTS)?"
@@ -545,7 +553,7 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
                 _current_body().append(
                     IncludeDirective(
                         span=SourceSpan(source_name, file_lineno),
-                        target=m.group("target").strip(),
+                        target=_strip_quotes(m.group("target").strip()),
                         if_exists=m.group("exists") is not None,
                     ),
                 )

execsql/state.py

@@ -13,16 +13,15 @@ inside function/method bodies — never at class-definition time — to avoid
 circular-import issues at load time.
 
 Internally, all mutable state lives on a :class:`RuntimeContext` instance
-(``_ctx``).  The module's ``__class__`` is swapped to a custom
+stored in a :class:`threading.local` so that each thread has its own
+isolated context.  The module's ``__class__`` is swapped to a custom
 :class:`types.ModuleType` subclass that transparently proxies attribute
-reads and writes to the active context.  This means:
+reads and writes to the active thread's context via :func:`_get_ctx`.
 
 - External code continues to use ``_state.conf``, ``_state.subvars = ...``,
   etc. with zero changes.
-- Functions *within* this module use ``_ctx.conf``, ``_ctx.subvars``, etc.
-  directly, because Python's ``LOAD_GLOBAL`` / ``STORE_GLOBAL`` bytecodes
-  access ``__dict__`` directly and do not trigger ``__getattr__`` /
-  ``__setattr__`` on the module class.
+- Functions *within* this module use ``_get_ctx()`` to obtain the active
+  context, ensuring thread-safe access.
 
 Use :func:`get_context` / :func:`set_context` to obtain or replace the
 active context programmatically.
@@ -30,12 +29,12 @@ active context programmatically.
 
 import re
 import sys
+import threading
 import types
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     import multiprocessing as _mp
-    import threading as _threading
 
     from execsql.config import ConfigData, StatObj, WriteHooks
     from execsql.db.base import DatabasePool
@@ -306,7 +305,7 @@ class RuntimeContext:
         # GUI
         self.gui_console: Any = None
         self.gui_manager_queue: _mp.Queue | None = None
-        self.gui_manager_thread: _threading.Thread | None = None
+        self.gui_manager_thread: threading.Thread | None = None
 
         # Profiling — None means profiling is disabled; a list means it is enabled.
         # Each entry: (source, line_no, command_type, elapsed_secs, command_text_preview)
@@ -330,12 +329,12 @@ class _StateModule(types.ModuleType):
 
     def __getattr__(self, name: str) -> Any:
         if name in _CONTEXT_ATTRS:
-            return getattr(self.__dict__["_ctx"], name)
+            return getattr(_get_ctx(), name)
         raise AttributeError(f"module {self.__name__!r} has no attribute {name!r}")
 
     def __setattr__(self, name: str, value: Any) -> None:
         if name in _CONTEXT_ATTRS:
-            setattr(self.__dict__["_ctx"], name, value)
+            setattr(_get_ctx(), name, value)
         else:
             super().__setattr__(name, value)
 
@@ -345,12 +344,12 @@ class _StateModule(types.ModuleType):
             # unittest.mock.patch compatibility: patch checks
             # ``name in target.__dict__`` to decide whether to restore
             # via setattr (local) or delattr (non-local).  Since context
-            # attrs live on _ctx, not __dict__, patch takes the delattr
-            # path.  We reset to the default rather than truly deleting.
-            # Instantiate a fresh context each time to avoid sharing
-            # mutable defaults (lists/dicts) with a cached snapshot.
+            # attrs live on the RuntimeContext, not __dict__, patch takes
+            # the delattr path.  We reset to the default rather than truly
+            # deleting.  Instantiate a fresh context each time to avoid
+            # sharing mutable defaults (lists/dicts) with a cached snapshot.
             fresh = RuntimeContext()
-            setattr(self.__dict__["_ctx"], name, getattr(fresh, name))
+            setattr(_get_ctx(), name, getattr(fresh, name))
         else:
             super().__delattr__(name)
 
@@ -359,7 +358,7 @@ class _StateModule(types.ModuleType):
 
 
 # ---------------------------------------------------------------------------
-# Utility functions — use _ctx directly (LOAD_GLOBAL bypasses the proxy)
+# Utility functions
 # ---------------------------------------------------------------------------
 
 
@@ -378,11 +377,12 @@ def endloop() -> None:
     """Complete the current loop being compiled and push it onto the command stack."""
     import execsql.exceptions as _exc
 
-    if len(_ctx.loopcommandstack) == 0:
+    ctx = _get_ctx()
+    if len(ctx.loopcommandstack) == 0:
         raise _exc.ErrInfo("error", other_msg="END LOOP metacommand without a matching preceding LOOP metacommand.")
-    _ctx.compiling_loop = False
-    _ctx.commandliststack.append(_ctx.loopcommandstack[-1])
-    _ctx.loopcommandstack.pop()
+    ctx.compiling_loop = False
+    ctx.commandliststack.append(ctx.loopcommandstack[-1])
+    ctx.loopcommandstack.pop()
 
 
 # ---------------------------------------------------------------------------
@@ -391,19 +391,18 @@ def endloop() -> None:
 
 
 def get_context() -> RuntimeContext:
-    """Return the active :class:`RuntimeContext`."""
-    return _ctx
+    """Return the active :class:`RuntimeContext` for the current thread."""
+    return _get_ctx()
 
 
 def set_context(ctx: RuntimeContext) -> None:
-    """Replace the active :class:`RuntimeContext`.
+    """Replace the active :class:`RuntimeContext` for the current thread.
 
     Args:
         ctx: The new context to install.  All subsequent ``_state.foo``
-            accesses will resolve against this instance.
+            accesses **in this thread** will resolve against this instance.
     """
-    global _ctx
-    _ctx = ctx
+    _tls.ctx = ctx
 
 
 class active_context:
@@ -413,12 +412,9 @@ class active_context:
     the given context.  The previous context is restored on exit, even if
     an exception occurs.
 
-    .. warning::
-
-        **Not thread-safe.**  ``set_context()`` modifies a module-level
-        variable.  If two threads call ``execute()`` concurrently, they
-        will overwrite each other's context.  For thread-level isolation,
-        use thread-local storage (a future enhancement for PARALLEL blocks).
+    Thread-safe: each thread has its own context via :data:`threading.local`,
+    so concurrent ``active_context`` blocks in different threads do not
+    interfere with each other.
 
     Usage::
 
@@ -433,14 +429,15 @@ class active_context:
 
     def __init__(self, ctx: RuntimeContext) -> None:
         self._ctx = ctx
-        self._prev: RuntimeContext = get_context()
+        self._prev: RuntimeContext | None = None
 
     def __enter__(self) -> RuntimeContext:
-        set_context(self._ctx)
+        self._prev = _get_ctx()
+        _tls.ctx = self._ctx
         return self._ctx
 
     def __exit__(self, *exc: Any) -> None:
-        set_context(self._prev)
+        _tls.ctx = self._prev
 
 
 # ---------------------------------------------------------------------------
@@ -455,20 +452,21 @@ def reset() -> None:
     preserving only the ``filewriter`` subprocess (which is ``atexit``-managed
     and must not be discarded while alive).
     """
-    global _ctx
+    ctx = _get_ctx()
 
     # Preserve filewriter — it's atexit-managed and must survive resets.
-    old_fw = _ctx.filewriter
+    old_fw = ctx.filewriter
 
     # Close open database connections before discarding the pool.
-    if _ctx.dbs is not None:
+    if ctx.dbs is not None:
         try:
-            _ctx.dbs.closeall()
+            ctx.dbs.closeall()
         except Exception:
             pass
 
-    _ctx = RuntimeContext()
-    _ctx.filewriter = old_fw
+    new_ctx = RuntimeContext()
+    new_ctx.filewriter = old_fw
+    _tls.ctx = new_ctx
 
 
 def initialize(
@@ -502,15 +500,16 @@ def initialize(
     import execsql.utils.fileio as _fileio_mod
     import execsql.utils.timer as _timer_mod
 
-    _ctx.conf = config
-    _ctx.if_stack = _script.IfLevels()
-    _ctx.counters = _script.CounterVars()
-    _ctx.timer = _timer_mod.Timer()
-    _ctx.dbs = _db_base.DatabasePool()
-    _ctx.tempfiles = _fileio_mod.TempFileMgr()
-    _ctx.export_metadata = _exporters_base.ExportMetadata()
-    _ctx.metacommandlist = dispatch_table
-    _ctx.conditionallist = conditional_table
+    ctx = _get_ctx()
+    ctx.conf = config
+    ctx.if_stack = _script.IfLevels()
+    ctx.counters = _script.CounterVars()
+    ctx.timer = _timer_mod.Timer()
+    ctx.dbs = _db_base.DatabasePool()
+    ctx.tempfiles = _fileio_mod.TempFileMgr()
+    ctx.export_metadata = _exporters_base.ExportMetadata()
+    ctx.metacommandlist = dispatch_table
+    ctx.conditionallist = conditional_table
 
     # Discover and register metacommand plugins via entry points.
     # Runs here (not at import time) to avoid I/O side effects during import.
@@ -519,9 +518,31 @@ def initialize(
     discover_metacommand_plugins(dispatch_table)
 
 
+# ---------------------------------------------------------------------------
+# Thread-local storage and context helper
+# ---------------------------------------------------------------------------
+
+_tls = threading.local()
+
+
+def _get_ctx() -> RuntimeContext:
+    """Return the current thread's :class:`RuntimeContext`, creating one if needed.
+
+    Each thread gets its own isolated context via :data:`threading.local`.
+    The first access in a new thread lazily creates a fresh
+    :class:`RuntimeContext` so that code which reads ``_state.foo`` never
+    encounters an ``AttributeError``.
+    """
+    ctx = getattr(_tls, "ctx", None)
+    if ctx is None:
+        ctx = RuntimeContext()
+        _tls.ctx = ctx
+    return ctx
+
+
 # ---------------------------------------------------------------------------
 # Bootstrap — create the initial context and swap the module class
 # ---------------------------------------------------------------------------
 
-_ctx = RuntimeContext()
+_tls.ctx = RuntimeContext()
 sys.modules[__name__].__class__ = _StateModule