execsql2 2.17.0__py3-none-any.whl → 2.17.2__py3-none-any.whl

execsql/state.py

@@ -31,8 +31,62 @@ import re
 import sys
 import threading
 import types
+from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
+
+@dataclass
+class ExecFrame:
+    """One frame on the AST executor's unified execution stack.
+
+    Every nesting construct the AST executor enters (IF/ELSEIF/ELSE branches,
+    LOOP iterations, BATCH blocks, INCLUDE'd files, EXECUTE SCRIPT calls,
+    plus the top-level ``<main>`` script) pushes one of these via try/finally
+    so the debug REPL ``.stack`` command and ``DEBUG WRITE COMMANDLISTSTACK``
+    can show real execution context.
+
+    Frames with ``kind in ("main", "script")`` are **scope frames** — they
+    own a ``LocalSubVarSet`` (``localvars``) for ``~``-prefixed variables and
+    a ``ScriptArgSubVarSet`` (``paramvals``) for ``#``-prefixed parameters.
+    All other kinds (if/elseif/else/loop_*/batch/include) are non-scope and
+    cache a reference to their enclosing scope in ``scope_ref`` so that
+    ``current_localvars()`` lookups stay O(1) regardless of nesting depth.
+
+    Attributes:
+        kind: One of ``"main"`` / ``"script"`` / ``"include"`` / ``"if"`` /
+            ``"elseif"`` / ``"else"`` / ``"loop_while"`` / ``"loop_until"`` /
+            ``"batch"``.
+        label: Human-readable summary — condition text for IF, file basename
+            for INCLUDE, script name + params for SCRIPT, etc.
+        source: Path of the source file the block lives in.
+        line: Source line where the block opens, or ``None`` for ``main``.
+        iteration: Current 1-based iteration count for LOOP frames; 0
+            otherwise.
+        params: Bound parameter values for SCRIPT frames (display-only dict
+            of ``name -> str(value)``); ``None`` otherwise.
+        localvars: ``LocalSubVarSet`` for ``~`` variables; only populated for
+            ``main`` / ``script`` frames.
+        paramvals: ``ScriptArgSubVarSet`` for ``#`` script parameters; only
+            populated for ``script`` frames.
+        paramnames: Formal parameter names declared on BEGIN SCRIPT, used for
+            display purposes; only populated for ``script`` frames.
+        scope_ref: Cached pointer to the enclosing scope frame
+            (``main``/``script``) for non-scope frames; ``None`` for scope
+            frames themselves.
+    """
+
+    kind: str
+    label: str = ""
+    source: str = ""
+    line: int | None = None
+    iteration: int = 0
+    params: dict[str, str] | None = None
+    localvars: Any = None  # LocalSubVarSet — TYPE_CHECKING import would be circular
+    paramvals: Any = None  # ScriptArgSubVarSet
+    paramnames: list[str] | None = None
+    scope_ref: ExecFrame | None = None
+
+
 if TYPE_CHECKING:
     import multiprocessing as _mp
 
@@ -40,9 +94,7 @@ if TYPE_CHECKING:
     from execsql.db.base import DatabasePool
     from execsql.exporters.base import ExportMetadata, WriteSpec
     from execsql.script import (
-        CommandList,
         CounterVars,
-        IfLevels,
         MetaCommandList,
         ScriptCmd,
         ScriptExecSpec,
@@ -66,13 +118,8 @@ __all__ = [
     "cancel_halt_writespec",
     "cancel_halt_mailspec",
     "cancel_halt_exec",
-    "commandliststack",
-    "savedscripts",
-    "loopcommandstack",
-    "compiling_loop",
     "endloop_rx",
     "loop_rx",
-    "loop_nest_level",
     "cmds_run",
     "defer_rx",
     "stringtypes",
@@ -80,7 +127,6 @@ __all__ = [
     "subvars",
     "status",
     # Lazy singletons
-    "if_stack",
     "counters",
     "timer",
     "output",
@@ -103,7 +149,6 @@ __all__ = [
     "tertiary_vno",
     # Functions
     "xcmd_test",
-    "endloop",
     "reset",
     "initialize",
     # New public API
@@ -170,11 +215,6 @@ _CONTEXT_ATTRS: frozenset[str] = frozenset(
         "cancel_halt_mailspec",
         "cancel_halt_exec",
         # Execution stack
-        "commandliststack",
-        "savedscripts",
-        "loopcommandstack",
-        "compiling_loop",
-        "loop_nest_level",
         "cmds_run",
         # I/O
         "exec_log",
@@ -183,7 +223,6 @@ _CONTEXT_ATTRS: frozenset[str] = frozenset(
         "output",
         "filewriter",
         # Lazy singletons
-        "if_stack",
         "counters",
         "timer",
         "dbs",
@@ -202,6 +241,7 @@ _CONTEXT_ATTRS: frozenset[str] = frozenset(
         # AST executor
         "ast_scripts",
         "include_chain",
+        "ast_exec_stack",
     },
 )
 
@@ -228,11 +268,6 @@ class RuntimeContext:
         "cancel_halt_mailspec",
         "cancel_halt_exec",
         # Execution stack
-        "commandliststack",
-        "savedscripts",
-        "loopcommandstack",
-        "compiling_loop",
-        "loop_nest_level",
         "cmds_run",
         # I/O
         "exec_log",
@@ -241,7 +276,6 @@ class RuntimeContext:
         "output",
         "filewriter",
         # Lazy singletons
-        "if_stack",
         "counters",
         "timer",
         "dbs",
@@ -260,6 +294,7 @@ class RuntimeContext:
         # AST executor
         "ast_scripts",
         "include_chain",
+        "ast_exec_stack",
     )
 
     def __init__(self) -> None:
@@ -278,11 +313,6 @@ class RuntimeContext:
         self.cancel_halt_exec: ScriptExecSpec | None = None
 
         # Execution stack
-        self.commandliststack: list[CommandList] = []
-        self.savedscripts: dict[str, CommandList] = {}
-        self.loopcommandstack: list[CommandList] = []
-        self.compiling_loop: bool = False
-        self.loop_nest_level: int = 0
         self.cmds_run: int = 0
 
         # I/O
@@ -293,7 +323,6 @@ class RuntimeContext:
         self.filewriter: FileWriter | None = None
 
         # Lazy singletons
-        self.if_stack: IfLevels | None = None
         self.counters: CounterVars | None = None
         self.timer: Timer | None = None
         self.dbs: DatabasePool | None = None
@@ -317,6 +346,58 @@ class RuntimeContext:
         # AST executor — script block registry and include-chain tracking.
         self.ast_scripts: dict = {}
         self.include_chain: list[str] = []
+        # Unified execution stack maintained by the AST executor for every
+        # nesting construct: top-level script, EXECUTE SCRIPT calls, INCLUDE'd
+        # files, IF/ELSEIF/ELSE branches, LOOP iterations, BATCH blocks. See
+        # :class:`ExecFrame` for frame structure. Read by the debug REPL's
+        # ``.stack`` command and ``DEBUG WRITE COMMANDLISTSTACK`` for genuine
+        # execution context — the legacy ``commandliststack`` only records
+        # SCRIPT call frames and is therefore insufficient for the debugger.
+        self.ast_exec_stack: list[ExecFrame] = []
+
+    # -----------------------------------------------------------------
+    # Unified-stack scope accessors
+    # -----------------------------------------------------------------
+
+    def current_scope(self) -> ExecFrame | None:
+        """Return the innermost SCRIPT or ``<main>`` frame, or ``None`` if empty.
+
+        Non-scope frames (if/elseif/else/loop_*/batch/include) cache a
+        ``scope_ref`` to their enclosing scope at push time, so this lookup
+        is O(1) regardless of nesting depth.
+        """
+        if not self.ast_exec_stack:
+            return None
+        top = self.ast_exec_stack[-1]
+        if top.kind in ("main", "script"):
+            return top
+        return top.scope_ref
+
+    def current_localvars(self) -> Any:  # LocalSubVarSet | None
+        """Return the current scope's ``~`` variable container, or ``None``."""
+        scope = self.current_scope()
+        return scope.localvars if scope is not None else None
+
+    def current_paramvals(self) -> Any:  # ScriptArgSubVarSet | None
+        """Return the current SCRIPT frame's ``#`` parameter container.
+
+        Returns ``None`` when the current scope is ``<main>`` (parameters
+        only exist for named SCRIPT blocks).
+        """
+        scope = self.current_scope()
+        if scope is None or scope.kind != "script":
+            return None
+        return scope.paramvals
+
+    def outer_script_scopes(self) -> list[ExecFrame]:
+        """Return the list of enclosing scope frames excluding the innermost.
+
+        Used by ``utils/strings.get_subvarset`` for ``+``-prefixed outer-scope
+        variable lookup — the caller iterates this list in reverse order to
+        find the most recently entered outer scope that defines the variable.
+        """
+        scopes = [f for f in self.ast_exec_stack if f.kind in ("main", "script")]
+        return scopes[:-1]
 
 
 # ---------------------------------------------------------------------------
@@ -373,16 +454,24 @@ def xcmd_test(teststr: str) -> bool:
     raise _exc.ErrInfo(type="cmd", command_text=teststr, other_msg="Unrecognized conditional")
 
 
-def endloop() -> None:
-    """Complete the current loop being compiled and push it onto the command stack."""
-    import execsql.exceptions as _exc
+def current_scope() -> ExecFrame | None:
+    """Module-level wrapper for :meth:`RuntimeContext.current_scope`."""
+    return _get_ctx().current_scope()
 
-    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()
+
+def current_localvars() -> Any:
+    """Module-level wrapper for :meth:`RuntimeContext.current_localvars`."""
+    return _get_ctx().current_localvars()
+
+
+def current_paramvals() -> Any:
+    """Module-level wrapper for :meth:`RuntimeContext.current_paramvals`."""
+    return _get_ctx().current_paramvals()
+
+
+def outer_script_scopes() -> list[ExecFrame]:
+    """Module-level wrapper for :meth:`RuntimeContext.outer_script_scopes`."""
+    return _get_ctx().outer_script_scopes()
 
 
 # ---------------------------------------------------------------------------
@@ -502,7 +591,6 @@ def initialize(
 
     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()

execsql/utils/errors.py

@@ -164,7 +164,6 @@ def exit_now(exit_status: int, errinfo: ErrInfo | None, logmsg: str | None = Non
     if errinfo is not None and _state.err_halt_exec is not None:
         errexec = _state.err_halt_exec
         _state.err_halt_exec = None
-        _state.commandliststack = []
         _run_deferred_script(errexec)
     if exit_status == 2 and _state.cancel_halt_mailspec is not None:
         try:
@@ -175,7 +174,6 @@ def exit_now(exit_status: int, errinfo: ErrInfo | None, logmsg: str | None = Non
     if exit_status == 2 and _state.cancel_halt_exec is not None:
         cancelexec = _state.cancel_halt_exec
         _state.cancel_halt_exec = None
-        _state.commandliststack = []
         _run_deferred_script(cancelexec)
     if exit_status > 0 and _state.exec_log:
         if logmsg:

execsql/utils/fileio.py

@@ -311,51 +311,95 @@ fw_input: multiprocessing.Queue = multiprocessing.Queue()
 fw_output: multiprocessing.Queue = multiprocessing.Queue()
 
 
+def _writer_alive() -> bool:
+    """True if the FileWriter subprocess is running and consuming fw_input.
+
+    Every entry-point that puts a command on ``fw_input`` should guard on this:
+    if the subprocess isn't running (test contexts that bypass
+    ``_state.initialize()``, or a subprocess that crashed), unbounded ``put()``
+    calls eventually fill the OS pipe buffer (smaller on macOS than Linux) and
+    deadlock the caller. ``fw_output.get()`` calls would block forever on a
+    dead writer for the same reason.
+    """
+    return filewriter is not None and filewriter.is_alive()
+
+
 def filewriter_filestatus(filename: str) -> int:
+    if not _writer_alive():
+        return FileWriter.FileControl.STATUS_CLOSED
     fw_input.put((FileWriter.CMD_GET_STATUS, (filename,)))
     return fw_output.get()
 
 
 def filewriter_write(filename: str, message: str) -> None:
+    if not _writer_alive():
+        return
     fw_input.put((FileWriter.CMD_WRITE, (filename, message)))
 
 
 def filewriter_open_as_new(filename: str) -> None:
     # FileWriter opens files in append mode ("a") by default.  This ensures that it
     # will be opened in write mode ("w") instead.  If the file is open, it will be closed.
+    if not _writer_alive():
+        return
     fw_input.put((FileWriter.CMD_OPEN_AS_NEW, (filename,)))
 
 
 def filewriter_close(filename: str) -> None:
     # This is intended to be used by the main process to ensure that a file
     # is closed before that process writes to it.
+    if not _writer_alive():
+        return
     fw_input.put((FileWriter.CMD_CLOSE_IF_OPEN, (filename,)))
     while filewriter_filestatus(filename) == FileWriter.FileControl.STATUS_OPEN:
         time.sleep(0.05)
 
 
 def filewriter_close_all_after_write() -> None:
+    if not _writer_alive():
+        return
     fw_input.put((FileWriter.CMD_CLOSE_ALL_AFTER_WRITE, ()))
     all_closed = False
     while not all_closed:
+        # Re-check liveness on every iteration: if the subprocess dies
+        # mid-loop, fw_output.get() would block forever otherwise.
+        if not _writer_alive():
+            return
         fw_input.put((FileWriter.CMD_CLOSED_STATUS, ()))
-        close_status = fw_output.get()
+        try:
+            close_status = fw_output.get(timeout=2.0)
+        except queue.Empty:
+            # Either the writer is too slow or it died after the alive
+            # check above — recheck on the next iteration.
+            continue
         all_closed = close_status == FileWriter.FileControl.STATUS_CLOSED
         time.sleep(0.05)
 
 
 def filewriter_closeall() -> None:
+    if not _writer_alive():
+        return
     fw_input.put((FileWriter.CMD_CLOSE_ALL, ()))
 
 
 def filewriter_shutdown() -> None:
+    if not _writer_alive():
+        return
     fw_input.put((FileWriter.CMD_SHUTDOWN, ()))
 
 
 def filewriter_end() -> None:
+    # join() with no timeout blocks forever if the subprocess is stuck;
+    # cap it so atexit handlers can't wedge Python shutdown.
+    if filewriter is None:
+        return
     try:
-        filewriter_shutdown()
-        filewriter.join()
+        if filewriter.is_alive():
+            filewriter_shutdown()
+            filewriter.join(timeout=5.0)
+        if filewriter.is_alive():
+            filewriter.terminate()
+            filewriter.join(timeout=2.0)
     except Exception:
         pass  # Best-effort cleanup at interpreter shutdown.
 

execsql/utils/mail.py

@@ -138,8 +138,9 @@ class MailSpec:
     def _expand(text: str) -> str:
         """Expand local and global substitution variables in *text*."""
         result = text
-        if _state.commandliststack:
-            result, _ = _state.commandliststack[-1].localvars.substitute_all(result)
+        localvars = _state.current_localvars()
+        if localvars is not None:
+            result, _ = localvars.substitute_all(result)
         result, _ = _state.subvars.substitute_all(result)
         return result
 

execsql/utils/strings.py

@@ -250,11 +250,11 @@ def get_subvarset(varname: str, metacommandline: str) -> tuple:
     # Outer scope variable
     if varname[0] == "+":
         varname = re.sub("^[+]", "~", varname)
-        for cl in reversed(_state.commandliststack[0:-1]):
-            if cl.localvars.sub_exists(varname):
-                subvarset = cl.localvars
+        for frame in reversed(_state.outer_script_scopes()):
+            if frame.localvars is not None and frame.localvars.sub_exists(varname):
+                subvarset = frame.localvars
                 break
-        # Raise error if local variable not found anywhere down in commandliststack
+        # Raise error if local variable not found anywhere in the enclosing scopes
         if not subvarset:
             raise ErrInfo(
                 type="cmd",
@@ -266,5 +266,5 @@ def get_subvarset(varname: str, metacommandline: str) -> tuple:
             )
     # Global or local variable
     else:
-        subvarset = _state.subvars if varname[0] != "~" else _state.commandliststack[-1].localvars
+        subvarset = _state.subvars if varname[0] != "~" else _state.current_localvars()
     return subvarset, varname

{execsql2-2.17.0.dist-info → execsql2-2.17.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.17.0
+Version: 2.17.2
 Summary: Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables.
 Project-URL: Homepage, https://execsql2.readthedocs.io
 Project-URL: Repository, https://github.com/geocoug/execsql
@@ -59,6 +59,7 @@ Requires-Dist: pymysql; extra == 'all'
 Requires-Dist: pyodbc; extra == 'all'
 Requires-Dist: pyyaml; extra == 'all'
 Requires-Dist: tables; extra == 'all'
+Requires-Dist: tkintermapview>=1.29; extra == 'all'
 Requires-Dist: xlrd; extra == 'all'
 Provides-Extra: all-db
 Requires-Dist: duckdb; extra == 'all-db'
@@ -106,6 +107,8 @@ Requires-Dist: polars; extra == 'formats'
 Requires-Dist: pyyaml; extra == 'formats'
 Requires-Dist: tables; extra == 'formats'
 Requires-Dist: xlrd; extra == 'formats'
+Provides-Extra: map
+Requires-Dist: tkintermapview>=1.29; extra == 'map'
 Provides-Extra: mssql
 Requires-Dist: pyodbc; extra == 'mssql'
 Provides-Extra: mysql
@@ -220,41 +223,44 @@ execsql script.sql                          # read connection from config file
 
 ## Options
 
-| Flag                                  | Description                                                      |
-| ------------------------------------- | ---------------------------------------------------------------- |
-| `-t {p,m,s,l,k,a,f,o,d}`              | Database type                                                    |
-| `-u USER`                             | Database username                                                |
-| `-p PORT`                             | Server port                                                      |
-| `-a VALUE`                            | Set substitution variable `$ARG_x`                               |
-| `-b` / `--boolean-int`                | Treat integers 0 and 1 as boolean values                         |
-| `-c SCRIPT`                           | Execute inline SQL or metacommand string                         |
-| `-d`                                  | Auto-create export directories                                   |
-| `-e ENCODING` / `--database-encoding` | Character encoding used in the database                          |
-| `-f ENCODING`                         | Script file encoding (default: UTF-8)                            |
-| `-g ENCODING` / `--output-encoding`   | Encoding for WRITE and EXPORT output                             |
-| `-i ENCODING` / `--import-encoding`   | Encoding for data files used with IMPORT                         |
-| `-l`                                  | Write run log to `~/execsql.log`                                 |
-| `-m`                                  | List metacommands and exit                                       |
-| `-n`                                  | Create a new SQLite or PostgreSQL database if it does not exist  |
-| `-o` / `--online-help`                | Open the online documentation in the default browser             |
-| `-s N` / `--scan-lines`               | Lines to scan for IMPORT format detection (0 = scan entire file) |
-| `-v {0,1,2,3}`                        | GUI level (0=none, 1=password, 2=selection, 3=full)              |
-| `-w`                                  | Skip password prompt when a username is supplied                 |
-| `-y` / `--encodings`                  | List available encoding names and exit                           |
-| `-z KB` / `--import-buffer`           | Import buffer size in KB (default: 32)                           |
-| `--dsn URL`                           | Connection string (e.g. `postgresql://user:pass@host/db`)        |
-| `--output-dir DIR`                    | Default base directory for EXPORT output files                   |
-| `--dry-run`                           | Parse the script and report commands without executing           |
-| `--lint`                              | Static analysis: check structure and warn on issues (no DB)      |
-| `--parse-tree`                        | Print the script's AST structure and exit (no DB)                |
-| `--list-plugins`                      | List discovered plugins and exit                                 |
-| `--ping`                              | Test database connectivity and exit                              |
-| `--profile`                           | Show per-statement timing summary after execution                |
-| `--progress`                          | Show a progress bar for long-running IMPORT operations           |
-| `--config FILE`                       | Load an explicit config file (highest priority after CLI args)   |
-| `--debug`                             | Start in step-through debug mode (REPL pauses before each stmt)  |
-| `--dump-keywords`                     | Print metacommand keywords as JSON and exit                      |
-| `--gui-framework {tkinter,textual}`   | GUI framework for interactive prompts                            |
+| Flag                                  | Description                                                       |
+| ------------------------------------- | ----------------------------------------------------------------- |
+| `-t {p,m,s,l,k,a,f,o,d}`              | Database type                                                     |
+| `-u USER`                             | Database username                                                 |
+| `-p PORT`                             | Server port                                                       |
+| `-a VALUE`                            | Set substitution variable `$ARG_x`                                |
+| `-b` / `--boolean-int`                | Treat integers 0 and 1 as boolean values                          |
+| `-c SCRIPT`                           | Execute inline SQL or metacommand string                          |
+| `-d`                                  | Auto-create export directories                                    |
+| `-e ENCODING` / `--database-encoding` | Character encoding used in the database                           |
+| `-f ENCODING`                         | Script file encoding (default: UTF-8)                             |
+| `-g ENCODING` / `--output-encoding`   | Encoding for WRITE and EXPORT output                              |
+| `-i ENCODING` / `--import-encoding`   | Encoding for data files used with IMPORT                          |
+| `-l`                                  | Write run log to `~/execsql.log`                                  |
+| `-m`                                  | List metacommands and exit                                        |
+| `-n`                                  | Create a new SQLite or PostgreSQL database if it does not exist   |
+| `-o` / `--online-help`                | Open the online documentation in the default browser              |
+| `-s N` / `--scan-lines`               | Lines to scan for IMPORT format detection (0 = scan entire file)  |
+| `-v {0,1,2,3}`                        | GUI level (0=none, 1=password, 2=selection, 3=full)               |
+| `-w`                                  | Skip password prompt when a username is supplied                  |
+| `-y` / `--encodings`                  | List available encoding names and exit                            |
+| `-z KB` / `--import-buffer`           | Import buffer size in KB (default: 32)                            |
+| `--dsn URL`                           | Connection string (e.g. `postgresql://user:pass@host/db`)         |
+| `--output-dir DIR`                    | Default base directory for EXPORT output files                    |
+| `--dry-run`                           | Parse the script and report commands without executing            |
+| `--lint`                              | Static analysis: check structure and warn on issues (no DB)       |
+| `--parse-tree`                        | Print the script's AST structure and exit (no DB)                 |
+| `--list-plugins`                      | List discovered plugins and exit                                  |
+| `--ping`                              | Test database connectivity and exit                               |
+| `--profile`                           | Show per-statement timing summary after execution                 |
+| `--profile-limit N`                   | Top N statements to display in `--profile` summary (default: 20)  |
+| `--progress`                          | Show a progress bar for long-running IMPORT operations            |
+| `--config FILE`                       | Load an explicit config file (highest priority after CLI args)    |
+| `--no-system-cmd`                     | Disable the `SYSTEM_CMD` metacommand (safer for CI / shared envs) |
+| `--init-config`                       | Print a default `execsql.conf` template to stdout and exit        |
+| `--debug`                             | Start in step-through debug mode (REPL pauses before each stmt)   |
+| `--dump-keywords`                     | Print metacommand keywords as JSON and exit                       |
+| `--gui-framework {tkinter,textual}`   | GUI framework for interactive prompts                             |
 
 Run `execsql --help` for the full option list, or `execsql -m` to list all metacommands.