execsql2 2.16.7__py3-none-any.whl → 2.16.12__py3-none-any.whl

execsql/debug/repl.py

@@ -111,6 +111,8 @@ _HELP_COMMANDS = [
     (".where", ".w", "Show the current script location and upcoming statement"),
     (".stack", "", "Show the command-list stack (script name, line, depth)"),
     (".set VAR VAL", ".s", "Set or update a substitution variable"),
+    (".scripts", "", "List all registered SCRIPT definitions"),
+    (".scripts NAME", "", "Show detail for a specific SCRIPT"),
     (".help", ".h", "Show this help text"),
 ]
 
@@ -290,6 +292,12 @@ def _handle_dot_command(line: str) -> None:
             varname = parts[0]
             value = parts[1] if len(parts) > 1 else ""
             _set_var(varname, value)
+    elif cmd.startswith("scripts"):
+        rest = cmd[7:].strip()
+        if rest:
+            _print_script_detail(rest)
+        else:
+            _print_scripts()
     else:
         _write(f"  {_c(_RED, 'Unknown command:')} {line!r}. Type '.help' for available commands.\n")
 
@@ -507,3 +515,54 @@ def _set_var(varname: str, value: str) -> None:
     else:
         subvars.add_substitution(varname, value)
     _write(f"  {_c(_CYAN, varname)} {_c(_DIM, '=')} {value}\n")
+
+
+def _print_scripts() -> None:
+    """Print all registered SCRIPT definitions."""
+    from execsql.metacommands.debug import _format_script_signature, _format_script_source
+
+    scripts = _state.ast_scripts
+    if not scripts:
+        _write("  (no scripts registered)\n\n")
+        return
+    _write_rule(f" {_c(_BOLD + _YELLOW, 'Scripts')} {_c(_DIM, f'({len(scripts)})')} ")
+    sigs = {name: _format_script_signature(name, block.param_defs) for name, block in scripts.items()}
+    max_sig = max(len(s) for s in sigs.values())
+    for name, block in scripts.items():
+        sig = sigs[name]
+        src = _format_script_source(block.span)
+        _write(f"  {_c(_CYAN, sig):<{max_sig + len(_CYAN) + len(_RESET)}}  {_c(_DIM, src)}\n")
+    _write("\n")
+
+
+def _print_script_detail(name: str) -> None:
+    """Print detail for a single SCRIPT definition."""
+    from execsql.metacommands.debug import _format_script_signature, _format_script_source
+
+    script_name = name.lower()
+    scripts = _state.ast_scripts
+    if script_name not in scripts:
+        _write(f"  {_c(_RED, 'No script named')} {_c(_CYAN, repr(script_name))} {_c(_RED, 'is registered.')}\n")
+        return
+    block = scripts[script_name]
+    sig = _format_script_signature(block.name, block.param_defs)
+    src = _format_script_source(block.span)
+    _write_rule(f" {_c(_BOLD + _YELLOW, 'Script')} {_c(_DIM, '──')} {_c(_CYAN, sig)} ")
+    _write(f"  {_c(_BOLD, 'Source:')}     {src}\n")
+    if block.param_defs:
+        _write(f"  {_c(_BOLD, 'Parameters:')}\n")
+        max_name = max(len(p.name) for p in block.param_defs)
+        for p in block.param_defs:
+            if p.default is not None:
+                _write(
+                    f"    {_c(_CYAN, p.name):<{max_name + len(_CYAN) + len(_RESET)}}  {_c(_DIM, f'(optional, default: {p.default})')}\n",
+                )
+            else:
+                _write(f"    {_c(_CYAN, p.name):<{max_name + len(_CYAN) + len(_RESET)}}  {_c(_DIM, '(required)')}\n")
+    else:
+        _write(f"  {_c(_BOLD, 'Parameters:')} (none)\n")
+    if block.doc:
+        _write("\n")
+        for doc_line in block.doc.split("\n"):
+            _write(f"  {_c(_DIM, doc_line)}\n")
+    _write("\n")

execsql/format.py

@@ -73,6 +73,8 @@ MULTIWORD_KEYWORDS = [
     "PROMPT ASK",
     "WITH TEMPLATE",
     "IN ZIPFILE",
+    "SHOW SCRIPTS",
+    "SHOW SCRIPT",
 ]
 
 # Depth-tracking sets

execsql/metacommands/debug.py

@@ -1,5 +1,4 @@
 from __future__ import annotations
-from execsql.utils.errors import fatal_error
 
 """
 Debug metacommand handlers for execsql.
@@ -7,11 +6,16 @@ Debug metacommand handlers for execsql.
 Provides ``x_debug_write_metacommands``, which implements the
 ``WRITE METACOMMANDS`` debug metacommand that prints the full registered
 metacommand list to the log/console for troubleshooting.
+
+Also provides ``x_show_scripts`` and ``x_show_script`` for runtime
+introspection of registered SCRIPT blocks.
 """
 
+from pathlib import Path
 from typing import Any
 
 import execsql.state as _state
+from execsql.utils.errors import fatal_error
 from execsql.utils.fileio import EncodedFile, filewriter_open_as_new, filewriter_write
 
 
@@ -173,3 +177,87 @@ def x_debug_write_config(**kwargs: Any) -> None:
 
     for line in lines:
         write(f"{line}\n")
+
+
+# ---------------------------------------------------------------------------
+# Helpers for SCRIPT introspection (shared by metacommands and REPL)
+# ---------------------------------------------------------------------------
+
+
+def _format_script_signature(name: str, param_defs: Any) -> str:
+    """Return ``name(param1, param2, opt=default)`` or ``name()``.
+
+    *param_defs* may be a list of :class:`ParamDef` objects (preferred) or
+    a plain list of strings (backward compat).
+    """
+    if not param_defs:
+        return f"{name}()"
+    parts: list[str] = []
+    for p in param_defs:
+        if hasattr(p, "default") and p.default is not None:
+            parts.append(f"{p.name}={p.default}")
+        elif hasattr(p, "name"):
+            parts.append(p.name)
+        else:
+            parts.append(str(p))
+    return f"{name}({', '.join(parts)})"
+
+
+def _format_script_source(span: Any) -> str:
+    """Return ``file:start-end`` from a SourceSpan."""
+    filename = Path(span.file).name if span and span.file else "<unknown>"
+    if span and span.start_line is not None:
+        if span.end_line is not None and span.end_line != span.start_line:
+            return f"{filename}:{span.start_line}-{span.end_line}"
+        return f"{filename}:{span.start_line}"
+    return filename
+
+
+# ---------------------------------------------------------------------------
+# SHOW SCRIPTS / SHOW SCRIPT metacommand handlers
+# ---------------------------------------------------------------------------
+
+
+def x_show_scripts(**kwargs: Any) -> None:
+    """List all registered SCRIPT definitions with parameters and source location."""
+    scripts = _state.ast_scripts
+    if not scripts:
+        _state.output.write("No scripts registered.\n")
+        return
+    _state.output.write(f"Registered scripts ({len(scripts)}):\n\n")
+    # Compute column width for alignment
+    sigs = {name: _format_script_signature(name, block.param_defs) for name, block in scripts.items()}
+    max_sig = max(len(s) for s in sigs.values())
+    for name, block in scripts.items():
+        sig = sigs[name]
+        src = _format_script_source(block.span)
+        _state.output.write(f"  {sig:<{max_sig}}  {src}\n")
+    _state.output.write("\n")
+
+
+def x_show_script(**kwargs: Any) -> None:
+    """Show detail for a single registered SCRIPT definition."""
+    script_name = kwargs.get("script_id", "").lower()
+    scripts = _state.ast_scripts
+    if script_name not in scripts:
+        _state.output.write(f"No script named '{script_name}' is registered.\n")
+        return
+    block = scripts[script_name]
+    sig = _format_script_signature(block.name, block.param_defs)
+    src = _format_script_source(block.span)
+    _state.output.write(f"Script: {sig}\n")
+    _state.output.write(f"Source: {src}\n")
+    if block.param_defs:
+        _state.output.write("Parameters:\n")
+        max_name = max(len(p.name) for p in block.param_defs)
+        for p in block.param_defs:
+            if p.default is not None:
+                _state.output.write(f"  {p.name:<{max_name}}  (optional, default: {p.default})\n")
+            else:
+                _state.output.write(f"  {p.name:<{max_name}}  (required)\n")
+    else:
+        _state.output.write("Parameters: (none)\n")
+    if block.doc:
+        _state.output.write("\n")
+        for doc_line in block.doc.split("\n"):
+            _state.output.write(f"  {doc_line}\n")

execsql/metacommands/dispatch.py

@@ -99,6 +99,8 @@ from execsql.metacommands.debug import (
     x_debug_write_metacommands,
     x_debug_write_odbc_drivers,
     x_debug_write_subvars,
+    x_show_script,
+    x_show_scripts,
 )
 from execsql.debug.repl import x_breakpoint
 from execsql.metacommands.io import (
@@ -1747,6 +1749,22 @@ def build_dispatch_table() -> MetaCommandList:
         run_when_false=False,
     )
 
+    # ------------------------------------------------------------------
+    # SHOW SCRIPTS / SHOW SCRIPT
+    # ------------------------------------------------------------------
+    mcl.add(
+        r"^\s*SHOW\s+SCRIPTS\s*$",
+        x_show_scripts,
+        description="SHOW SCRIPTS",
+        category="action",
+    )
+    mcl.add(
+        r"^\s*SHOW\s+SCRIPT\s+(?P<script_id>\w+)\s*$",
+        x_show_script,
+        description="SHOW SCRIPT",
+        category="action",
+    )
+
     # ------------------------------------------------------------------
     # IF / ORIF / ANDIF / ELSEIF / ELSE / ENDIF
     # ------------------------------------------------------------------

execsql/script/ast.py

@@ -52,6 +52,7 @@ __all__ = [
     "IfBlock",
     "LoopBlock",
     "BatchBlock",
+    "ParamDef",
     "ScriptBlock",
     "SqlBlock",
     "IncludeDirective",
@@ -290,6 +291,24 @@ class BatchBlock(Node):
         return f"BatchBlock({self.span}, body={len(self.body)})"
 
 
+@dataclass(frozen=True, slots=True)
+class ParamDef:
+    """A single SCRIPT parameter definition with an optional default value.
+
+    Attributes:
+        name: The parameter name (as declared, without ``#`` prefix).
+        default: The default value string, or ``None`` for required parameters.
+    """
+
+    name: str
+    default: str | None = None
+
+    @property
+    def required(self) -> bool:
+        """Return ``True`` if this parameter has no default value."""
+        return self.default is None
+
+
 @dataclass
 class ScriptBlock(Node):
     """A BEGIN SCRIPT name ... END SCRIPT structure.
@@ -299,20 +318,31 @@ class ScriptBlock(Node):
 
     Attributes:
         name: The script block name (lowercased).
-        param_names: Optional list of formal parameter names.
+        param_defs: Optional list of :class:`ParamDef` parameter definitions.
+        doc: Optional docstring extracted from comments immediately following
+            the BEGIN SCRIPT line.
         body: Nodes within the script block.
     """
 
     name: str
-    param_names: list[str] | None = None
+    param_defs: list[ParamDef] | None = None
+    doc: str | None = None
     body: list[Node] = field(default_factory=list)
 
+    @property
+    def param_names(self) -> list[str] | None:
+        """Return parameter names only (backward compatibility)."""
+        if self.param_defs is None:
+            return None
+        return [p.name for p in self.param_defs]
+
     def children(self) -> Iterator[Node]:
         yield from self.body
 
     def __repr__(self) -> str:
-        params = f", params={self.param_names}" if self.param_names else ""
-        return f"ScriptBlock({self.span}, name={self.name!r}{params}, body={len(self.body)})"
+        params = f", params={self.param_names}" if self.param_defs else ""
+        doc_tag = ", doc=True" if self.doc else ""
+        return f"ScriptBlock({self.span}, name={self.name!r}{params}{doc_tag}, body={len(self.body)})"
 
 
 @dataclass
@@ -547,8 +577,15 @@ def _node_label(node: Node) -> str:
     if isinstance(node, BatchBlock):
         return f"{_tag('BATCH')} BEGIN BATCH"
     if isinstance(node, ScriptBlock):
-        params = f" ({', '.join(node.param_names)})" if node.param_names else ""
-        return f"{_tag('SCRIPT')} {node.name}{params}"
+        if node.param_defs:
+            parts = []
+            for p in node.param_defs:
+                parts.append(f"{p.name}={p.default}" if p.default is not None else p.name)
+            params = f" ({', '.join(parts)})"
+        else:
+            params = ""
+        doc_tag = " [doc]" if node.doc else ""
+        return f"{_tag('SCRIPT')} {node.name}{params}{doc_tag}"
     if isinstance(node, SqlBlock):
         return f"{_tag('SQL_BLK')} BEGIN SQL"
     if isinstance(node, IncludeDirective):

execsql/script/executor.py

@@ -648,7 +648,10 @@ def _execute_include(
     WHILE/UNTIL loops are handled natively too.
     """
     if node.is_execute_script:
-        target = node.target.lower()
+        # Substitute variables in the target — the script name may be passed
+        # as a parameter (e.g., EXECUTE SCRIPT !!#script_name!!).
+        effective_locals = _stack_localvars(ctx) or localvars
+        target = substitute_vars(node.target, effective_locals, ctx=ctx).strip().lower()
 
         # Native path: target is in our AST registry
         if target in ctx.ast_scripts:
@@ -713,23 +716,35 @@ def _execute_script_native(
         for param, arg in all_prepared_args:
             paramvals.add_substitution(param, arg)
 
-        # Validate parameter names match
-        if script_block.param_names is not None:
+        # Validate parameter names match — with default parameter support
+        if script_block.param_defs is not None:
             passed_names = [p[0].lstrip("#") for p in all_prepared_args]
-            if not all(p in passed_names for p in script_block.param_names):
+            required = [p.name for p in script_block.param_defs if p.required]
+            missing = [p for p in required if p not in passed_names]
+            if missing:
                 raise ErrInfo(
                     "error",
-                    other_msg=f"Formal and actual parameter name mismatch in call to {script_block.name}.",
+                    other_msg=(f"Missing required parameter(s) ({', '.join(missing)}) in call to {script_block.name}."),
                 )
+            # Inject defaults for optional params not provided
+            for pdef in script_block.param_defs:
+                if pdef.default is not None and pdef.name not in passed_names:
+                    paramvals.add_substitution(f"#{pdef.name}", pdef.default)
     else:
-        if script_block.param_names is not None:
-            raise ErrInfo(
-                "error",
-                other_msg=(
-                    f"Missing expected parameters ({', '.join(script_block.param_names)}) "
-                    f"in call to {script_block.name}."
-                ),
-            )
+        if script_block.param_defs is not None:
+            required = [p.name for p in script_block.param_defs if p.required]
+            if required:
+                raise ErrInfo(
+                    "error",
+                    other_msg=(
+                        f"Missing required parameter(s) ({', '.join(required)}) in call to {script_block.name}."
+                    ),
+                )
+            # No args provided but all params have defaults — inject them all
+            paramvals = ScriptArgSubVarSet()
+            for pdef in script_block.param_defs:
+                if pdef.default is not None:
+                    paramvals.add_substitution(f"#{pdef.name}", pdef.default)
 
     # Push a CommandList frame onto the stack so that:
     #   - get_subvarset() can find ~local and +outer-scope variables

execsql/script/parser.py

@@ -42,6 +42,7 @@ from execsql.script.ast import (
     LoopBlock,
     MetaCommandStatement,
     Node,
+    ParamDef,
     Script,
     ScriptBlock,
     SourceSpan,
@@ -106,7 +107,7 @@ def _strip_quotes(s: str) -> str:
 _EXEC_SCRIPT_RX = re.compile(
     r"^\s*(?:EXEC(?:UTE)?|RUN)\s+SCRIPT"
     r"(?P<exists>\s+IF\s+EXISTS)?"
-    r"\s+(?P<script_id>\w+)"
+    r"\s+(?P<script_id>(?:\w+|!(?:['\"]?)![^!]+!(?:['\"]?)!))"
     r"(?:(?:\s+WITH)?(?:\s+ARG(?:UMENT)?S?)?\s*\(\s*(?P<argexp>.+?)\s*\))?"
     r"(?:\s+(?P<looptype>WHILE|UNTIL)\s*\(\s*(?P<loopcond>.+)\s*\))?"
     r"\s*$",
@@ -114,10 +115,52 @@ _EXEC_SCRIPT_RX = re.compile(
 )
 
 _WITH_PARAMS_RX = re.compile(
-    r"(?:\s+WITH)?(?:\s+PARAM(?:ETER)?S)?\s*\(\s*(?P<params>\w+(?:\s*,\s*\w+)*)\s*\)\s*$",
+    r"(?:\s+WITH)?(?:\s+PARAM(?:ETER)?S)?\s*\(\s*(?P<params>"
+    r"\w+(?:\s*=\s*\S+)?(?:\s*,\s*\w+(?:\s*=\s*\S+)?)*"
+    r")\s*\)\s*$",
     re.I,
 )
 
+_PARAM_TOKEN_RX = re.compile(r"(\w+)(?:\s*=\s*(\S+))?")
+
+
+def _parse_param_defs(
+    params_str: str,
+    lineno: int,
+    source: str,
+) -> list[ParamDef]:
+    """Parse ``'a, b, c=100, d=false'`` into a list of :class:`ParamDef`.
+
+    Required parameters (no default) must precede optional parameters
+    (with default).  Raises :class:`ErrInfo` if ordering is violated.
+    """
+    tokens = [t.strip() for t in params_str.split(",")]
+    defs: list[ParamDef] = []
+    seen_optional: str | None = None  # name of first optional param
+    for token in tokens:
+        m = _PARAM_TOKEN_RX.match(token.strip())
+        if not m:
+            raise ErrInfo(
+                type="cmd",
+                other_msg=(f"Invalid parameter token '{token}' on line {lineno} of {source}."),
+            )
+        name, default = m.group(1), m.group(2)
+        if default is not None:
+            if seen_optional is None:
+                seen_optional = name
+        elif seen_optional is not None:
+            raise ErrInfo(
+                type="cmd",
+                other_msg=(
+                    f"Required parameter '{name}' after optional parameter "
+                    f"'{seen_optional}' on line {lineno} of {source}. "
+                    f"Required parameters must precede optional parameters."
+                ),
+            )
+        defs.append(ParamDef(name=name, default=default))
+    return defs
+
+
 # Line classification
 _EXEC_LINE_RX = re.compile(r"^\s*--\s*!x!\s*(?P<cmd>.+)$", re.I)
 _COMMENT_LINE_RX = re.compile(r"^\s*--")
@@ -135,7 +178,16 @@ class _BlockFrame:
     to close the block correctly.
     """
 
-    __slots__ = ("node", "kind", "start_line", "source", "_in_else", "_in_elseif")
+    __slots__ = (
+        "node",
+        "kind",
+        "start_line",
+        "source",
+        "_in_else",
+        "_in_elseif",
+        "collecting_doc",
+        "doc_lines",
+    )
 
     def __init__(self, node: Node, kind: str, start_line: int, source: str) -> None:
         self.node = node
@@ -144,6 +196,8 @@ class _BlockFrame:
         self.source = source
         self._in_else = False
         self._in_elseif = False
+        self.collecting_doc: bool = kind == "script"  # auto-collect doc after BEGIN SCRIPT
+        self.doc_lines: list[str] = []
 
 
 # ---------------------------------------------------------------------------
@@ -163,6 +217,7 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
     in_sql_block = False  # inside BEGIN SQL ... END SQL
     sql_accum = ""  # multi-line SQL accumulator
     sql_start_line = 0
+    sql_accum_at_block_comment = False  # was sql_accum non-empty when /* started?
 
     def _current_body() -> list[Node]:
         """Return the body list that new nodes should be appended to."""
@@ -205,9 +260,67 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
             )
             line_comment_lines = []
 
+    def _stop_doc_collection() -> None:
+        """Stop collecting docstring lines and finalize the doc on the script node."""
+        if block_stack and block_stack[-1].collecting_doc:
+            frame = block_stack[-1]
+            frame.collecting_doc = False
+            if frame.doc_lines:
+                doc_text = "\n".join(frame.doc_lines).strip()
+                if doc_text and isinstance(frame.node, ScriptBlock):
+                    frame.node.doc = doc_text
+
     for file_lineno, raw_line in enumerate(lines, 1):
         line = raw_line.rstrip()
 
+        # --- Docstring collection for SCRIPT blocks ---
+        # Comments immediately following BEGIN SCRIPT are captured as the
+        # docstring.  A blank line terminates the doc.
+        if block_stack and block_stack[-1].collecting_doc and not in_block_comment:
+            frame = block_stack[-1]
+            if not line:
+                # Blank line terminates doc collection
+                _stop_doc_collection()
+                _flush_line_comments()
+                continue
+            # Check for block comment opening
+            stripped = line.lstrip()
+            if stripped.startswith("/*"):
+                # Collect block comment as doc lines
+                comment_body = stripped[2:]
+                if comment_body.rstrip().endswith("*/"):
+                    # Single-line block comment: /* text */
+                    comment_body = comment_body.rstrip()[:-2].strip()
+                    if comment_body:
+                        frame.doc_lines.append(comment_body)
+                    continue
+                # Multi-line block comment — collect until */
+                if comment_body.strip():
+                    frame.doc_lines.append(comment_body.rstrip())
+                # Let the block comment tracker handle the rest, but mark
+                # that we're collecting doc inside a block comment.
+                in_block_comment = True
+                block_comment_lines = [line]
+                block_comment_start = file_lineno
+                sql_accum_at_block_comment = False
+                # We'll handle the doc finalization when */ is found below.
+                # For now, mark doc as still collecting.
+                continue
+            # Check for single-line comment (not metacommand)
+            metacommand_match_doc = _EXEC_LINE_RX.match(line)
+            if not metacommand_match_doc and _COMMENT_LINE_RX.match(line):
+                # Strip -- prefix and optional leading space
+                text = stripped
+                if text.startswith("--"):
+                    text = text[2:]
+                    if text.startswith(" "):
+                        text = text[1:]
+                frame.doc_lines.append(text.rstrip())
+                continue
+            # Non-comment line (metacommand or SQL) — stop doc collection
+            _stop_doc_collection()
+            # Fall through to normal processing
+
         # --- Block comment tracking ---
         if not line:
             _flush_line_comments()
@@ -217,14 +330,38 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
             block_comment_lines.append(line)
             if len(line) > 1 and line.rstrip().endswith("*/"):
                 in_block_comment = False
-                _flush_sql(file_lineno)
-                _current_body().append(
-                    Comment(
-                        span=SourceSpan(source_name, block_comment_start, file_lineno),
-                        text="\n".join(block_comment_lines),
-                    ),
-                )
+                comment_text = "\n".join(block_comment_lines)
+                # If we were collecting doc lines when the block comment opened,
+                # feed the content into the docstring instead of creating a node.
+                if block_stack and block_stack[-1].collecting_doc:
+                    frame = block_stack[-1]
+                    # Extract text between /* and */, stripping delimiters
+                    for bc_line in block_comment_lines:
+                        stripped_bc = bc_line.strip()
+                        if stripped_bc.startswith("/*"):
+                            stripped_bc = stripped_bc[2:]
+                        if stripped_bc.endswith("*/"):
+                            stripped_bc = stripped_bc[:-2]
+                        stripped_bc = stripped_bc.strip()
+                        if stripped_bc:
+                            frame.doc_lines.append(stripped_bc)
+                    block_comment_lines = []
+                    sql_accum_at_block_comment = False
+                    continue
+                if sql_accum_at_block_comment:
+                    # Block comment started inside a SQL statement — fold it
+                    # back into sql_accum so the statement isn't split.
+                    sql_accum += "\n" + comment_text
+                else:
+                    _flush_sql(file_lineno)
+                    _current_body().append(
+                        Comment(
+                            span=SourceSpan(source_name, block_comment_start, file_lineno),
+                            text=comment_text,
+                        ),
+                    )
                 block_comment_lines = []
+                sql_accum_at_block_comment = False
             continue
 
         # --- Single-line comment classification ---
@@ -232,12 +369,17 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
         comment_match = _COMMENT_LINE_RX.match(line)
 
         if comment_match and not metacommand_match and not in_sql_block:
-            # Accumulate consecutive -- comment lines into a single Comment node.
-            # Inside a BEGIN SQL block, comments are part of the SQL text (not emitted separately).
-            _flush_sql(file_lineno)
-            if not line_comment_lines:
-                line_comment_start = file_lineno
-            line_comment_lines.append(line.rstrip())
+            if sql_accum:
+                # Inside a multi-line SQL statement — keep the comment as part
+                # of the SQL text so that commented-out columns, WHERE clauses,
+                # etc. don't split the statement.
+                sql_accum += "\n" + line.rstrip()
+            else:
+                # Standalone comment (not inside a SQL statement) — accumulate
+                # consecutive -- lines into a single Comment node.
+                if not line_comment_lines:
+                    line_comment_start = file_lineno
+                line_comment_lines.append(line.rstrip())
             continue
 
         # Non-comment line — flush any accumulated -- comment group before proceeding.
@@ -248,17 +390,24 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
         if len(stripped) > 1 and stripped.startswith("/*"):
             block_comment_start = file_lineno
             block_comment_lines = [line]
+            # Remember whether we were inside a SQL statement when the block
+            # comment started, so we can fold it back on close.
+            sql_accum_at_block_comment = bool(sql_accum)
             in_block_comment = True
             if stripped.endswith("*/"):
                 in_block_comment = False
-                _flush_sql(file_lineno)
-                _current_body().append(
-                    Comment(
-                        span=SourceSpan(source_name, file_lineno),
-                        text=line,
-                    ),
-                )
+                if sql_accum_at_block_comment:
+                    sql_accum += "\n" + line.rstrip()
+                else:
+                    _flush_sql(file_lineno)
+                    _current_body().append(
+                        Comment(
+                            span=SourceSpan(source_name, file_lineno),
+                            text=line,
+                        ),
+                    )
                 block_comment_lines = []
+                sql_accum_at_block_comment = False
             continue
 
         # --- Metacommand handling ---
@@ -312,7 +461,7 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
             if m:
                 name = m.group("name").lower()
                 paramexpr = m.group("paramexpr")
-                param_names = None
+                param_defs = None
                 if paramexpr:
                     wp = _WITH_PARAMS_RX.match(paramexpr)
                     if not wp:
@@ -321,13 +470,13 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
                             command_text=line,
                             other_msg=f"Invalid BEGIN SCRIPT metacommand on line {file_lineno} of file {source_name}.",
                         )
-                    param_names = re.findall(r"\w+", wp.group("params"))
+                    param_defs = _parse_param_defs(wp.group("params"), file_lineno, source_name)
                 block_stack.append(
                     _BlockFrame(
                         ScriptBlock(
                             span=SourceSpan(source_name, file_lineno),
                             name=name,
-                            param_names=param_names,
+                            param_defs=param_defs,
                         ),
                         kind="script",
                         start_line=file_lineno,

execsql/utils/fileio.py

@@ -284,7 +284,15 @@ class FileWriter(multiprocessing.Process):
         self.active = False
         self.close_all()
 
-    def run(self) -> None:
+    def run(self) -> None:  # pragma: no cover – runs in a subprocess
+        # Ignore SIGINT in the child process — the parent owns Ctrl+C handling
+        # and will shut us down via CMD_SHUTDOWN on the queue.  Without this,
+        # KeyboardInterrupt races through queue.get() and close_all(), producing
+        # ugly tracebacks on stderr.
+        import signal
+
+        signal.signal(signal.SIGINT, signal.SIG_IGN)
+
         # Messages in the input queue consist of a 2-tuple, of which the first element
         # is a command and the second is a tuple of arguments for the function indicated
         # by that command.

{execsql2-2.16.7.dist-info → execsql2-2.16.12.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.16.7
+Version: 2.16.12
 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

{execsql2-2.16.7.dist-info → execsql2-2.16.12.dist-info}/RECORD

@@ -3,7 +3,7 @@ execsql/__main__.py,sha256=HdbK-SAhyUmfB6xINY5AzxdMSxGzWSGEG_2dv42Jn64,315
 execsql/api.py,sha256=0D2Rl329fvDXERNrJBUzoWEt_VxqCHwRgaGzrq04rVs,19709
 execsql/config.py,sha256=6icjr8PKenUGfFF6lciSclvejjDzY8GTW1OZ1-IZt-Y,29480
 execsql/exceptions.py,sha256=j8hykBiof9H3Za9hwLIbDcVB2Xn65ODXXplp1jkvdgM,8453
-execsql/format.py,sha256=IsCM5T1iBC54CkBJNfO55ycJk-aKRZJjtnwXk0jepTA,12723
+execsql/format.py,sha256=RZVxfIHduF6AU2c_O6k93I0kxTUa8gfUn6bRbcgxHYM,12762
 execsql/models.py,sha256=kCTUQg9-vReM6WNFfB_ZrEppuOW5u1uMBQThSkfPC0o,13264
 execsql/parser.py,sha256=P3ea8k7T_XLMrbhpFNZXwytdShrY302MKnhosqza1lo,15493
 execsql/plugins.py,sha256=2voLwT6eFap6BCBoZYndNNC_bMEJO1f_aP6xQTVXwYI,12815
@@ -29,7 +29,7 @@ execsql/db/postgres.py,sha256=-GpaA9fi6_vdIDTGyRGxNRaPYAAkEB_aCb-EyLFShsM,21120
 execsql/db/sqlite.py,sha256=or2JDDt_MyBTAtSXBVhNTcojE9jCE4b98tq39sNOyUg,10401
 execsql/db/sqlserver.py,sha256=d8PwfNumt-Spit_0llafqQ900suv3CZMbrRsHLU1iB4,7683
 execsql/debug/__init__.py,sha256=j6EGUR0dHzUhWN1mHHtf1-Lhjq3Sb1V-vmnq2Ztgj1M,178
-execsql/debug/repl.py,sha256=rlddBAg7lelHYmeyeXhDqkK8XkKF2t2dVv4nsEMvleU,18247
+execsql/debug/repl.py,sha256=TlIw6XrxwP3QUxuOaQZKp9vbJI55kEfiMtRNMxQRZo8,20747
 execsql/exporters/__init__.py,sha256=-Cnji-OgodJV8ftcDcOyTof0kQMy9J5kKVC8GVFpc3o,670
 execsql/exporters/base.py,sha256=Uhq0PBz8N_pJ7WlIN9225wY-HyxfzWSb9YabHXicBA8,6387
 execsql/exporters/delimited.py,sha256=Po9RV4UwBLOuRZmPFJk5CErpFvTdLCy--nFJJffZgxM,32383
@@ -69,8 +69,8 @@ execsql/metacommands/conditions.py,sha256=B6fBumkqoPO4wcQbw_ypYITaSnzPemAA1g5GrN
 execsql/metacommands/connect.py,sha256=Wnlp5PeeaNDaVlaWjCetvarTgQIwIeMPYe8cyslPYeA,14969
 execsql/metacommands/control.py,sha256=PlTAq34OkcmnOsPm3bZxF4mg1MaNBpENa8wzIKVEY10,8302
 execsql/metacommands/data.py,sha256=tRQBGTAuW-eJ2tBNWaoZI9OjTyNNyHJISo7gOdL-sm8,11370
-execsql/metacommands/debug.py,sha256=IfyvGLYclb5i6hzOcIQN_N0gqi5xQhitY_Z5j3CmmKU,8264
-execsql/metacommands/dispatch.py,sha256=rY259pp5Bcq1q0N86NvxFgmFyOhYrNtgByzrNjocipI,87083
+execsql/metacommands/debug.py,sha256=3QVm0N5uc7mcZco36kqlDq8tiWW0sdo8E8BoQZkE_DI,11784
+execsql/metacommands/dispatch.py,sha256=Gao7rwiBFdghmYKcbWVm21Va30evobQuoghLY_FOZto,87602
 execsql/metacommands/io.py,sha256=vlGBje5sgnqeilooMdhJDgSRIhysHy5_7LrKtik9Xjs,3011
 execsql/metacommands/io_export.py,sha256=J2FnXA6452FIGStv6vbZXORmA-Ges70na0W7YwpMESA,13253
 execsql/metacommands/io_fileops.py,sha256=QKFj-94W32zxJiDcMpRsaohSCdtCRPIOG10K0WPigFk,9616
@@ -81,42 +81,42 @@ execsql/metacommands/script_ext.py,sha256=sw4YKUQl0SRlVlmhIoGbMokOo_hVqh1EcTuYCN
 execsql/metacommands/system.py,sha256=azRbv_P8l0t8BkDM9bmAUkhpnLSLHSCcmByqs-a3FxQ,7352
 execsql/metacommands/upsert.py,sha256=XE_P3mjaUkqT-LR4_28n2NbXwdjSgAGXJyZmKZC4Oy4,21136
 execsql/script/__init__.py,sha256=3WaBklMVIWjtCsYQ-BVo9UAVEIATOgeGsuyv21YKnxo,3969
-execsql/script/ast.py,sha256=yFw9ZvLLDNNSmSgy7cwK2fXLatpp2CKYAAyOneJoKVc,18836
+execsql/script/ast.py,sha256=SLn1fp0QDsqvJegNeIuyKV9f1BFnkEdzRota5EaNTfo,20053
 execsql/script/control.py,sha256=s-1eZdGARM6H1FwZ6VDdO_f50j7bvvRtTHesfUm9tbc,6144
 execsql/script/engine.py,sha256=EhuVBniOrFkzAW4I3NIZLt3INHTZJvlYoF7B99rZBLI,29391
-execsql/script/executor.py,sha256=SeY7Xiky1hBrNG8Z-MV6uhLhayvVFByUH02N5YZbyHA,36546
-execsql/script/parser.py,sha256=nAyLaDP-nL6C-chvlaSu0Oqh8ACcCCZjFacv0Fhyp58,24983
+execsql/script/executor.py,sha256=T-pGa3o5S0oX1ySB5zztzRoJHYRZI58CKw3qcFz_95Q,37602
+execsql/script/parser.py,sha256=huznh4RnW6Y_yJyIIoMG5McUS2T9o3kfOW37CXPR5dk,31689
 execsql/script/variables.py,sha256=ZSBGQUsoii6w3dLDVY9xxoPIV6wY0sAV_BNIQ6pgQAE,14328
 execsql/utils/__init__.py,sha256=0uR6JwVJQRX3vceByNBduCAf5dd5assKjeqJUWvpZoA,278
 execsql/utils/auth.py,sha256=onXzNkNZQZxGC5w7eey06sjvAIAX_Lf9g7nUJtcsel0,7009
 execsql/utils/crypto.py,sha256=KlT6lPk-v0-qQQfAMfWvT9Q6kRdCD3_5JVaLajNocKM,3051
 execsql/utils/datetime.py,sha256=rMCXAbvj6bxKCYzC97vrludO6PU5DYQ39buZ0smDC5A,3573
 execsql/utils/errors.py,sha256=I3xiPyDYS8Ftv7Y8P0uqzrTKlCN1dTXe1pMKKFFjmoA,8651
-execsql/utils/fileio.py,sha256=3HDm6QFGeXwFMmCsbea4H5Ub6u2Jrx-oNsWA3Q5aytQ,23860
+execsql/utils/fileio.py,sha256=x0kl2oLydCIGbhRCAJDHFknUyGcbKEOnV_M4lWcFmTk,24259
 execsql/utils/gui.py,sha256=h_7V2zYfp0l6C3Ft8QtUJAPgxCUrFkgIqwimz5s1bbQ,22821
 execsql/utils/mail.py,sha256=4QXwdPgMh6vQBKLtkdH7IDh3JBczumc3l5up2AUSOZU,5483
 execsql/utils/numeric.py,sha256=xh02ANSRk3nUpQ-rtm66ILoMqoi7HtzCoRMIOT9U8QI,1570
 execsql/utils/regex.py,sha256=diEzTZqU_HHwVMadPAvN1Vgzhl7I03eVaEFGCXyGGL8,3770
 execsql/utils/strings.py,sha256=5Dvzrk-9SIw2lpxXZQkiJbNyo1sy7iXXAtSULlZ0KG8,8488
 execsql/utils/timer.py,sha256=eDYf5VzCNFk7oo90InJucUm3XcBdhYMogjZMqeg9xzc,1899
-execsql2-2.16.7.data/data/execsql2_extras/README.md,sha256=sxwVyU0ZahCfANv56LahkyuM505kFjrMhe-1SvWE69E,4845
-execsql2-2.16.7.data/data/execsql2_extras/config_settings.sqlite,sha256=aY5cxR7Q7J6zJ4bC9lu5mHUrhy211Cq3MNKPQVCt02E,20480
-execsql2-2.16.7.data/data/execsql2_extras/example_config_prompt.sql,sha256=SY3Jxn1qcVm4kPW9xmmTfknHfvURXmeEYTbRjYrjGSw,7487
-execsql2-2.16.7.data/data/execsql2_extras/execsql.conf,sha256=_45iJ-KWZnB8uMW_gEg067MM5pmGJ-dVl7VbAZMunAE,9530
-execsql2-2.16.7.data/data/execsql2_extras/make_config_db.sql,sha256=WwyC6dK-Eh5CAVppiBCDHqiI1_wEI9U95Ytpr4lsZkg,8726
-execsql2-2.16.7.data/data/execsql2_extras/md_compare.sql,sha256=B8Wd7LZ0vnMY2qvA139JIEBkPObgRH2i5xj6PejTQt8,24092
-execsql2-2.16.7.data/data/execsql2_extras/md_glossary.sql,sha256=DJRHcU5NbFpxTTX-IwH3yRlsboj1q6BBGrUAHKn4Cuo,10796
-execsql2-2.16.7.data/data/execsql2_extras/md_upsert.sql,sha256=v_7GbWh_N1mBTmw3gvTrkagOVp2q0KmXvM8hE-DlFxY,112524
-execsql2-2.16.7.data/data/execsql2_extras/pg_compare.sql,sha256=9dWa8hnfy5dVJI-z2iGpd9JzQmI4j2ziMlEdpnr66ro,24352
-execsql2-2.16.7.data/data/execsql2_extras/pg_glossary.sql,sha256=pKjIIDsROAgJq2H-1qNEcRMAWManivcZ_AEVHzUUlic,9908
-execsql2-2.16.7.data/data/execsql2_extras/pg_upsert.sql,sha256=k7AFiGTLBy3nf-qO5QIaZrEYTAKvdxxU3JDLx9jqkzs,108315
-execsql2-2.16.7.data/data/execsql2_extras/script_template.sql,sha256=1Estacb_vm1FgK41k_G9nuduP1yiA-fQ1Kn4Z4mv5Ao,11153
-execsql2-2.16.7.data/data/execsql2_extras/ss_compare.sql,sha256=TsVxWm3cEpR5-EiMYXNhtaY0arSNeKZhsJdHdLA7xeI,24833
-execsql2-2.16.7.data/data/execsql2_extras/ss_glossary.sql,sha256=cLM7nN8JOIu9ZVP9oY9qdSK3hrnWJiDcX6nZmQQbQWI,13065
-execsql2-2.16.7.data/data/execsql2_extras/ss_upsert.sql,sha256=BCqmBykXBF-BpCgOFeG1qhf2XfScKsxPD17wd1hYfHw,120647
-execsql2-2.16.7.dist-info/METADATA,sha256=oHrJqm7vLZkhceyfwOT40zUVOIZs_kSp_0F2UGXgblw,20920
-execsql2-2.16.7.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-execsql2-2.16.7.dist-info/entry_points.txt,sha256=sUOxkM-dN1eBGGpSpDLsAaE0yNXYQKWZAfxPOlMkQyk,90
-execsql2-2.16.7.dist-info/licenses/LICENSE.txt,sha256=LBdhuxejF8_bLCHZ2kWfmDXpDGUu914Gbd6_3JjCRe0,676
-execsql2-2.16.7.dist-info/licenses/NOTICE,sha256=sqVrM73Ys9zfvWC_P797lHfTnoPW_ETeBSrUTFaob0A,339
-execsql2-2.16.7.dist-info/RECORD,,
+execsql2-2.16.12.data/data/execsql2_extras/README.md,sha256=sxwVyU0ZahCfANv56LahkyuM505kFjrMhe-1SvWE69E,4845
+execsql2-2.16.12.data/data/execsql2_extras/config_settings.sqlite,sha256=aY5cxR7Q7J6zJ4bC9lu5mHUrhy211Cq3MNKPQVCt02E,20480
+execsql2-2.16.12.data/data/execsql2_extras/example_config_prompt.sql,sha256=SY3Jxn1qcVm4kPW9xmmTfknHfvURXmeEYTbRjYrjGSw,7487
+execsql2-2.16.12.data/data/execsql2_extras/execsql.conf,sha256=_45iJ-KWZnB8uMW_gEg067MM5pmGJ-dVl7VbAZMunAE,9530
+execsql2-2.16.12.data/data/execsql2_extras/make_config_db.sql,sha256=WwyC6dK-Eh5CAVppiBCDHqiI1_wEI9U95Ytpr4lsZkg,8726
+execsql2-2.16.12.data/data/execsql2_extras/md_compare.sql,sha256=B8Wd7LZ0vnMY2qvA139JIEBkPObgRH2i5xj6PejTQt8,24092
+execsql2-2.16.12.data/data/execsql2_extras/md_glossary.sql,sha256=DJRHcU5NbFpxTTX-IwH3yRlsboj1q6BBGrUAHKn4Cuo,10796
+execsql2-2.16.12.data/data/execsql2_extras/md_upsert.sql,sha256=v_7GbWh_N1mBTmw3gvTrkagOVp2q0KmXvM8hE-DlFxY,112524
+execsql2-2.16.12.data/data/execsql2_extras/pg_compare.sql,sha256=9dWa8hnfy5dVJI-z2iGpd9JzQmI4j2ziMlEdpnr66ro,24352
+execsql2-2.16.12.data/data/execsql2_extras/pg_glossary.sql,sha256=pKjIIDsROAgJq2H-1qNEcRMAWManivcZ_AEVHzUUlic,9908
+execsql2-2.16.12.data/data/execsql2_extras/pg_upsert.sql,sha256=k7AFiGTLBy3nf-qO5QIaZrEYTAKvdxxU3JDLx9jqkzs,108315
+execsql2-2.16.12.data/data/execsql2_extras/script_template.sql,sha256=1Estacb_vm1FgK41k_G9nuduP1yiA-fQ1Kn4Z4mv5Ao,11153
+execsql2-2.16.12.data/data/execsql2_extras/ss_compare.sql,sha256=TsVxWm3cEpR5-EiMYXNhtaY0arSNeKZhsJdHdLA7xeI,24833
+execsql2-2.16.12.data/data/execsql2_extras/ss_glossary.sql,sha256=cLM7nN8JOIu9ZVP9oY9qdSK3hrnWJiDcX6nZmQQbQWI,13065
+execsql2-2.16.12.data/data/execsql2_extras/ss_upsert.sql,sha256=BCqmBykXBF-BpCgOFeG1qhf2XfScKsxPD17wd1hYfHw,120647
+execsql2-2.16.12.dist-info/METADATA,sha256=Op2AjS7Au3YMFnJ8rX0eE3DJm4SZcRVCzoCIhE3cDEo,20921
+execsql2-2.16.12.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+execsql2-2.16.12.dist-info/entry_points.txt,sha256=sUOxkM-dN1eBGGpSpDLsAaE0yNXYQKWZAfxPOlMkQyk,90
+execsql2-2.16.12.dist-info/licenses/LICENSE.txt,sha256=LBdhuxejF8_bLCHZ2kWfmDXpDGUu914Gbd6_3JjCRe0,676
+execsql2-2.16.12.dist-info/licenses/NOTICE,sha256=sqVrM73Ys9zfvWC_P797lHfTnoPW_ETeBSrUTFaob0A,339
+execsql2-2.16.12.dist-info/RECORD,,