execsql2 2.24.0__py3-none-any.whl → 2.25.0__py3-none-any.whl

execsql/plugins.py

@@ -61,6 +61,8 @@ adds entries::
 from __future__ import annotations
 
 import logging
+import threading
+import weakref
 from collections.abc import Callable
 from importlib.metadata import entry_points
 from typing import Any
@@ -71,6 +73,7 @@ __all__ = [
     "ImporterEntry",
     "ImporterRegistry",
     "discover_metacommand_plugins",
+    "register_metacommand_plugins_once",
     "discover_exporter_plugins",
     "discover_importer_plugins",
     "discover_all_plugins",
@@ -344,6 +347,27 @@ def discover_metacommand_plugins(mcl: Any) -> int:
     return loaded
 
 
+_registered_tables: weakref.WeakSet[Any] = weakref.WeakSet()
+_registration_lock = threading.Lock()
+
+
+def register_metacommand_plugins_once(mcl: Any) -> int:
+    """Register metacommand plugins into *mcl* unless that was already done.
+
+    Every run in a process shares one dispatch table, so registering on each
+    run would prepend another copy of every plugin command each time, while
+    other threads may be dispatching from the table.
+
+    Returns:
+        Number of plugins loaded by this call (0 if *mcl* already had them).
+    """
+    with _registration_lock:
+        if mcl in _registered_tables:
+            return 0
+        _registered_tables.add(mcl)
+        return discover_metacommand_plugins(mcl)
+
+
 def discover_exporter_plugins(registry: ExporterRegistry | None = None) -> int:
     """Discover and register exporter plugins.
 

execsql/script/engine.py

@@ -50,12 +50,16 @@ __all__ = [
 class MetaCommand:
     """A single entry in the metacommand dispatch table.
 
-    Holds a compiled regex, a handler function, and execution-control flags.
-    Call :meth:`run` with a raw command string to attempt a match and invoke
-    the handler.
+    Holds a regex, a handler function, and execution-control flags.  Call
+    :meth:`run` with a raw command string to attempt a match and invoke the
+    handler.
+
+    *rx* is a compiled pattern, or a pattern string that is compiled
+    (case-insensitively) the first time :attr:`rx` is read.  The dispatch
+    table registers some 1,700 patterns and a script uses a few dozen, so
+    compiling them all up front cost most of a second on every run.
     """
 
-    # A compiled metacommand that can be run if it matches a metacommand command string.
     def __init__(
         self,
         rx: Any,
@@ -64,6 +68,8 @@ class MetaCommand:
         set_error_flag: bool = True,
         category: str | None = None,
     ) -> None:
+        self._pattern: str
+        self._rx: Any = None
         self.rx = rx
         self.exec_fn = exec_func
         self.description = description
@@ -71,8 +77,32 @@ class MetaCommand:
         self.category = category
         self.hitcount = 0
 
+    @property
+    def rx(self) -> Any:
+        """The compiled pattern, compiled on first use."""
+        if self._rx is None:
+            self._rx = re.compile(self._pattern, re.I)
+        return self._rx
+
+    @rx.setter
+    def rx(self, value: Any) -> None:
+        if isinstance(value, str):
+            self._pattern, self._rx = value, None
+        else:
+            self._pattern, self._rx = value.pattern, value
+
+    @property
+    def pattern(self) -> str:
+        """The pattern string, without compiling it."""
+        return self._pattern
+
+    @property
+    def compiled(self) -> bool:
+        """Whether :attr:`rx` has been compiled yet."""
+        return self._rx is not None
+
     def __repr__(self) -> str:
-        return f"MetaCommand({self.rx.pattern!r}, {self.exec_fn!r}, {self.description!r})"
+        return f"MetaCommand({self.pattern!r}, {self.exec_fn!r}, {self.description!r})"
 
     def run(self, cmd_str: str) -> tuple:
         """Match *cmd_str* against this entry's regex and, if it matches, invoke the handler.
@@ -165,18 +195,17 @@ class MetaCommandList:
         """Register one or more regex patterns as a new :class:`MetaCommand` entry.
 
         *matching_regexes* may be a single pattern string or a list/tuple of
-        patterns; each compiles into a separate :class:`MetaCommand` prepended to
-        the dispatch list so that later registrations take priority.
+        patterns; each becomes a separate :class:`MetaCommand` prepended to
+        the dispatch list so that later registrations take priority.  The
+        patterns are compiled when first matched, not here.
         """
         if isinstance(matching_regexes, (tuple, list)):
             raw_patterns = list(matching_regexes)
-            regexes = [re.compile(rx, re.I) for rx in raw_patterns]
         else:
             raw_patterns = [matching_regexes]
-            regexes = [re.compile(matching_regexes, re.I)]
-        for rx, raw in zip(regexes, raw_patterns):
+        for raw in raw_patterns:
             mc = MetaCommand(
-                rx,
+                raw,
                 exec_func,
                 description,
                 set_error_flag,

execsql/script/executor.py

@@ -69,7 +69,7 @@ from execsql import manifest as _manifest
 from execsql.script.engine import set_dynamic_system_vars, set_static_system_vars, substitute_vars
 from execsql.script.variables import SubVarSet
 from execsql.state import ExecFrame, RuntimeContext, active_context, get_context, xcmd_test
-from execsql.utils.errors import exception_desc, exit_now, stamp_errinfo
+from execsql.utils.errors import exception_desc, exit_now, logged_error, stamp_errinfo
 
 __all__ = ["execute", "execute_input"]
 
@@ -254,8 +254,10 @@ def _exec_sql(
     effective_locals = _stack_localvars(ctx) or localvars
     cmd = substitute_vars(text, effective_locals, ctx=ctx)
     if _VARLIKE.search(cmd):
+        from execsql.utils.fileio import redact
+
         output.write(
-            f"Warning: There is a potential un-substituted variable in the command\n     {cmd}\n",
+            f"Warning: There is a potential un-substituted variable in the command\n     {redact(cmd)}\n",
         )
     e = None
     result = None
@@ -282,7 +284,7 @@ def _exec_sql(
         subvars.add_substitution("$ERROR_MESSAGE", e.errmsg())
         status.sql_error = True
         if ctx.exec_log is not None:
-            ctx.exec_log.log_status_info(f"SQL error: {e.errmsg()}")
+            ctx.exec_log.log_status_info(f"SQL error: {logged_error(e)}")
         if status.halt_on_err:
             exit_now(1, e)
         status.error_history.append((source, line_no, cmd, e.errmsg()))
@@ -321,8 +323,10 @@ def _exec_metacommand(
     assert subvars is not None
 
     if _VARLIKE.search(cmd):
+        from execsql.utils.fileio import redact
+
         output.write(
-            f"Warning: There is a potential un-substituted variable in the command\n     {cmd}\n",
+            f"Warning: There is a potential un-substituted variable in the command\n     {redact(cmd)}\n",
         )
     e = None
     try:
@@ -344,7 +348,7 @@ def _exec_metacommand(
         subvars.add_substitution("$LAST_ERROR", cmd)
         subvars.add_substitution("$ERROR_MESSAGE", e.errmsg())
         if ctx.exec_log is not None:
-            ctx.exec_log.log_status_info(f"Metacommand error: {e.errmsg()}")
+            ctx.exec_log.log_status_info(f"Metacommand error: {logged_error(e)}")
         if status.halt_on_metacommand_err:
             raise e
         status.error_history.append((source, line_no, cmd, e.errmsg()))

execsql/script/parser.py

@@ -257,8 +257,15 @@ class _BlockFrame:
 # ---------------------------------------------------------------------------
 
 
-def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
-    """Core parsing logic: convert an iterable of lines into a Script AST."""
+def _parse_lines(lines: Iterable[str], source_name: str, errors: list[ErrInfo] | None = None) -> Script:
+    """Core parsing logic: convert an iterable of lines into a Script AST.
+
+    A block-structure error raises :class:`ErrInfo`, unless *errors* is a
+    list: then each error is appended to it and parsing recovers (a closing
+    keyword with nothing to close is skipped, one that skips past an open
+    block closes that block too, and blocks still open at the end are
+    closed), so the whole script is parsed.
+    """
     body: list[Node] = []
     block_stack: list[_BlockFrame] = []
     in_block_comment = False
@@ -288,6 +295,38 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
             return node.body
         return body  # pragma: no cover — defensive fallback
 
+    def _structural_error(exc: ErrInfo) -> None:
+        """Raise *exc*, or record it when the caller collects errors and lets parsing recover."""
+        if errors is None:
+            raise exc
+        errors.append(exc)
+
+    def _close_block(frame: _BlockFrame, line_no: int) -> None:
+        """Give a popped block its end line and add it to the enclosing body."""
+        frame.node.span = SourceSpan(source_name, frame.start_line, line_no)
+        _current_body().append(frame.node)
+
+    def _pop_block(kind: str, line: str, line_no: int, no_match_msg: str) -> _BlockFrame | None:
+        """Pop the open block of *kind* that the closing keyword on *line* ends.
+
+        ``None`` (after reporting the error) when no such block is open.  A
+        block of another kind opened inside it and left open is an error of
+        its own; when recovering, it is closed here too.
+        """
+        if block_stack and block_stack[-1].kind == kind:
+            return block_stack.pop()
+        if errors is None:
+            msg = _unclosed_block_msg(block_stack[-1]) if block_stack else no_match_msg
+            raise ErrInfo(type="cmd", command_text=line, other_msg=msg)
+        if not any(frame.kind == kind for frame in block_stack):
+            errors.append(ErrInfo(type="cmd", command_text=line, other_msg=no_match_msg))
+            return None
+        while block_stack[-1].kind != kind:
+            frame = block_stack.pop()
+            errors.append(ErrInfo(type="cmd", command_text=line, other_msg=_unclosed_block_msg(frame)))
+            _close_block(frame, line_no)
+        return block_stack.pop()
+
     def _flush_sql(line_no: int) -> None:
         """If there's accumulated SQL text, emit a SqlStatement node."""
         nonlocal sql_accum, sql_start_line
@@ -322,6 +361,7 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
                 if doc_text and isinstance(frame.node, ScriptBlock):
                     frame.node.doc = doc_text
 
+    file_lineno = 0
     for file_lineno, raw_line in enumerate(lines, 1):
         line = raw_line.rstrip()
 
@@ -485,14 +525,15 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
                 _flush_sql(file_lineno)
                 in_sql_block = False
                 if not block_stack or block_stack[-1].kind != "sqlblock":
-                    raise ErrInfo(
-                        type="cmd",
-                        command_text=line,
-                        other_msg=f"Unmatched END SQL on line {file_lineno} of {source_name}.",
+                    _structural_error(
+                        ErrInfo(
+                            type="cmd",
+                            command_text=line,
+                            other_msg=f"Unmatched END SQL on line {file_lineno} of {source_name}.",
+                        ),
                     )
-                frame = block_stack.pop()
-                frame.node.span = SourceSpan(source_name, frame.start_line, file_lineno)
-                _current_body().append(frame.node)
+                    continue
+                _close_block(block_stack.pop(), file_lineno)
                 continue
 
             # Inside a SQL block, non-END SQL metacommands are silently
@@ -517,12 +558,18 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
                 if paramexpr:
                     wp = _WITH_PARAMS_RX.match(paramexpr)
                     if not wp:
-                        raise ErrInfo(
-                            type="cmd",
-                            command_text=line,
-                            other_msg=f"Invalid BEGIN SCRIPT metacommand on line {file_lineno} of file {source_name}.",
+                        _structural_error(
+                            ErrInfo(
+                                type="cmd",
+                                command_text=line,
+                                other_msg=f"Invalid BEGIN SCRIPT metacommand on line {file_lineno} of file {source_name}.",
+                            ),
                         )
-                    param_defs = _parse_param_defs(wp.group("params"), file_lineno, source_name)
+                    else:
+                        try:
+                            param_defs = _parse_param_defs(wp.group("params"), file_lineno, source_name)
+                        except ErrInfo as exc:
+                            _structural_error(exc)
                 block_stack.append(
                     _BlockFrame(
                         ScriptBlock(
@@ -543,38 +590,36 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
                 end_name = m.group("name")
                 if end_name is not None:
                     end_name = end_name.lower()
-                if not block_stack:
-                    raise ErrInfo(
-                        type="cmd",
-                        command_text=line,
-                        other_msg=f"END SCRIPT on line {file_lineno} of {source_name} has no matching BEGIN SCRIPT.",
-                    )
-                if block_stack[-1].kind != "script":
-                    raise ErrInfo(
-                        type="cmd",
-                        command_text=line,
-                        other_msg=_unclosed_block_msg(block_stack[-1]),
-                    )
-                frame = block_stack[-1]
-                script_node = cast(ScriptBlock, frame.node)
-                if end_name is not None and end_name != script_node.name:  # type: ignore[union-attr]
-                    raise ErrInfo(
-                        type="cmd",
-                        command_text=line,
-                        other_msg=f"Mismatched script name in the END SCRIPT metacommand on line {file_lineno} of file {source_name}.",
+                closed = _pop_block(
+                    "script",
+                    line,
+                    file_lineno,
+                    f"END SCRIPT on line {file_lineno} of {source_name} has no matching BEGIN SCRIPT.",
+                )
+                if closed is None:
+                    continue
+                script_node = cast(ScriptBlock, closed.node)
+                if end_name is not None and end_name != script_node.name:
+                    _structural_error(
+                        ErrInfo(
+                            type="cmd",
+                            command_text=line,
+                            other_msg=f"Mismatched script name in the END SCRIPT metacommand on line {file_lineno} of file {source_name}.",
+                        ),
                     )
                 if sql_accum:
-                    raise ErrInfo(
-                        type="cmd",
-                        command_text=line,
-                        other_msg=(
-                            f"Incomplete SQL statement\n  ({sql_accum})\n"
-                            f"at END SCRIPT metacommand on line {file_lineno} of file {source_name}."
+                    _structural_error(
+                        ErrInfo(
+                            type="cmd",
+                            command_text=line,
+                            other_msg=(
+                                f"Incomplete SQL statement\n  ({sql_accum})\n"
+                                f"at END SCRIPT metacommand on line {file_lineno} of file {source_name}."
+                            ),
                         ),
                     )
-                frame = block_stack.pop()
-                frame.node.span = SourceSpan(source_name, frame.start_line, file_lineno)
-                _current_body().append(frame.node)
+                    _flush_sql(file_lineno)
+                _close_block(closed, file_lineno)
                 continue
 
             # -- IF (block form) --
@@ -612,11 +657,14 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
             m = _ELSEIF_RX.match(cmd_text)
             if m:
                 if not block_stack or block_stack[-1].kind != "if":
-                    raise ErrInfo(
-                        type="cmd",
-                        command_text=line,
-                        other_msg=f"ELSEIF on line {file_lineno} of {source_name} has no matching IF.",
+                    _structural_error(
+                        ErrInfo(
+                            type="cmd",
+                            command_text=line,
+                            other_msg=f"ELSEIF on line {file_lineno} of {source_name} has no matching IF.",
+                        ),
                     )
+                    continue
                 frame = block_stack[-1]
                 frame._in_else = False
                 frame._in_elseif = True
@@ -633,11 +681,14 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
             m = _ANDIF_RX.match(cmd_text)
             if m:
                 if not block_stack or block_stack[-1].kind != "if":
-                    raise ErrInfo(
-                        type="cmd",
-                        command_text=line,
-                        other_msg=f"ANDIF on line {file_lineno} of {source_name} has no matching IF.",
+                    _structural_error(
+                        ErrInfo(
+                            type="cmd",
+                            command_text=line,
+                            other_msg=f"ANDIF on line {file_lineno} of {source_name} has no matching IF.",
+                        ),
                     )
+                    continue
                 modifier = ConditionModifier(
                     kind="AND",
                     condition=m.group("cond").strip(),
@@ -655,11 +706,14 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
             m = _ORIF_RX.match(cmd_text)
             if m:
                 if not block_stack or block_stack[-1].kind != "if":
-                    raise ErrInfo(
-                        type="cmd",
-                        command_text=line,
-                        other_msg=f"ORIF on line {file_lineno} of {source_name} has no matching IF.",
+                    _structural_error(
+                        ErrInfo(
+                            type="cmd",
+                            command_text=line,
+                            other_msg=f"ORIF on line {file_lineno} of {source_name} has no matching IF.",
+                        ),
                     )
+                    continue
                 modifier = ConditionModifier(
                     kind="OR",
                     condition=m.group("cond").strip(),
@@ -677,11 +731,14 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
             m = _ELSE_RX.match(cmd_text)
             if m:
                 if not block_stack or block_stack[-1].kind != "if":
-                    raise ErrInfo(
-                        type="cmd",
-                        command_text=line,
-                        other_msg=f"ELSE on line {file_lineno} of {source_name} has no matching IF.",
+                    _structural_error(
+                        ErrInfo(
+                            type="cmd",
+                            command_text=line,
+                            other_msg=f"ELSE on line {file_lineno} of {source_name} has no matching IF.",
+                        ),
                     )
+                    continue
                 frame = block_stack[-1]
                 frame._in_else = True
                 frame._in_elseif = False
@@ -691,21 +748,14 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
             # -- ENDIF --
             m = _ENDIF_RX.match(cmd_text)
             if m:
-                if not block_stack:
-                    raise ErrInfo(
-                        type="cmd",
-                        command_text=line,
-                        other_msg=f"ENDIF on line {file_lineno} of {source_name} has no matching IF.",
-                    )
-                if block_stack[-1].kind != "if":
-                    raise ErrInfo(
-                        type="cmd",
-                        command_text=line,
-                        other_msg=_unclosed_block_msg(block_stack[-1]),
-                    )
-                frame = block_stack.pop()
-                frame.node.span = SourceSpan(source_name, frame.start_line, file_lineno)
-                _current_body().append(frame.node)
+                closed = _pop_block(
+                    "if",
+                    line,
+                    file_lineno,
+                    f"ENDIF on line {file_lineno} of {source_name} has no matching IF.",
+                )
+                if closed is not None:
+                    _close_block(closed, file_lineno)
                 continue
 
             # -- LOOP --
@@ -728,21 +778,14 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
             # -- ENDLOOP --
             m = _ENDLOOP_RX.match(cmd_text)
             if m:
-                if not block_stack:
-                    raise ErrInfo(
-                        type="cmd",
-                        command_text=line,
-                        other_msg=f"ENDLOOP on line {file_lineno} of {source_name} has no matching LOOP.",
-                    )
-                if block_stack[-1].kind != "loop":
-                    raise ErrInfo(
-                        type="cmd",
-                        command_text=line,
-                        other_msg=_unclosed_block_msg(block_stack[-1]),
-                    )
-                frame = block_stack.pop()
-                frame.node.span = SourceSpan(source_name, frame.start_line, file_lineno)
-                _current_body().append(frame.node)
+                closed = _pop_block(
+                    "loop",
+                    line,
+                    file_lineno,
+                    f"ENDLOOP on line {file_lineno} of {source_name} has no matching LOOP.",
+                )
+                if closed is not None:
+                    _close_block(closed, file_lineno)
                 continue
 
             # -- BEGIN BATCH --
@@ -761,21 +804,14 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
             # -- END BATCH --
             m = _END_BATCH_RX.match(cmd_text)
             if m:
-                if not block_stack:
-                    raise ErrInfo(
-                        type="cmd",
-                        command_text=line,
-                        other_msg=f"END BATCH on line {file_lineno} of {source_name} has no matching BEGIN BATCH.",
-                    )
-                if block_stack[-1].kind != "batch":
-                    raise ErrInfo(
-                        type="cmd",
-                        command_text=line,
-                        other_msg=_unclosed_block_msg(block_stack[-1]),
-                    )
-                frame = block_stack.pop()
-                frame.node.span = SourceSpan(source_name, frame.start_line, file_lineno)
-                _current_body().append(frame.node)
+                closed = _pop_block(
+                    "batch",
+                    line,
+                    file_lineno,
+                    f"END BATCH on line {file_lineno} of {source_name} has no matching BEGIN BATCH.",
+                )
+                if closed is not None:
+                    _close_block(closed, file_lineno)
                 continue
 
             # -- INCLUDE --
@@ -846,24 +882,33 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
     # Flush any trailing consecutive -- comments
     _flush_line_comments()
 
-    # Unclosed blocks
-    if block_stack:
-        frame = block_stack[-1]
-        raise ErrInfo(
-            type="error",
-            other_msg=f"Unmatched {frame.kind.upper()} block starting on line {frame.start_line} at end of file {source_name}.",
+    # Unclosed blocks, innermost first
+    for frame in reversed(block_stack):
+        _structural_error(
+            ErrInfo(
+                type="error",
+                other_msg=f"Unmatched {frame.kind.upper()} block starting on line {frame.start_line} at end of file {source_name}.",
+            ),
         )
 
     # Trailing SQL without semicolon
     if sql_accum:
-        raise ErrInfo(
-            type="error",
-            other_msg=(
-                f"Incomplete SQL statement starting on line {sql_start_line} at end of file {source_name}."
-                + (" Metacommands must be prefixed with '-- !x!'." if source_name == "<inline>" else "")
+        _structural_error(
+            ErrInfo(
+                type="error",
+                other_msg=(
+                    f"Incomplete SQL statement starting on line {sql_start_line} at end of file {source_name}."
+                    + (" Metacommands must be prefixed with '-- !x!'." if source_name == "<inline>" else "")
+                ),
             ),
         )
 
+    # When recovering, keep the trailing SQL and close what is still open;
+    # otherwise both are already empty here.
+    _flush_sql(file_lineno)
+    while block_stack:
+        _close_block(block_stack.pop(), file_lineno)
+
     return Script(source=source_name, body=body)
 
 
@@ -872,7 +917,7 @@ def _parse_lines(lines: Iterable[str], source_name: str) -> Script:
 # ---------------------------------------------------------------------------
 
 
-def parse_script(filename: str, encoding: str = "utf-8") -> Script:
+def parse_script(filename: str, encoding: str = "utf-8", *, errors: list[ErrInfo] | None = None) -> Script:
     """Parse a ``.sql`` file and return a :class:`Script` AST.
 
     Reads the file directly (no dependency on runtime state) so it can be
@@ -881,22 +926,26 @@ def parse_script(filename: str, encoding: str = "utf-8") -> Script:
     Args:
         filename: Path to the SQL script file.
         encoding: File encoding (default ``utf-8``).
+        errors: When a list, block-structure errors are appended to it
+            and parsing recovers instead of raising (see ``_parse_lines``).
 
     Returns:
         A :class:`Script` tree representing the parsed file.
     """
     text = Path(filename).read_text(encoding=encoding)
-    return _parse_lines(text.splitlines(), filename)
+    return _parse_lines(text.splitlines(), filename, errors)
 
 
-def parse_string(content: str, source_name: str = "<inline>") -> Script:
+def parse_string(content: str, source_name: str = "<inline>", *, errors: list[ErrInfo] | None = None) -> Script:
     """Parse an inline script string and return a :class:`Script` AST.
 
     Args:
         content: The script content as a string.
         source_name: Name to use in source spans (default ``"<inline>"``).
+        errors: When a list, block-structure errors are appended to it
+            and parsing recovers instead of raising (see ``_parse_lines``).
 
     Returns:
         A :class:`Script` tree representing the parsed content.
     """
-    return _parse_lines(content.splitlines(), source_name)
+    return _parse_lines(content.splitlines(), source_name, errors)