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

execsql/format.py

@@ -17,12 +17,12 @@ import re
 from collections.abc import Iterator
 from pathlib import Path
 
-__all__ = ["collect_paths", "format_file", "parse_keyword", "run_formatter"]
+__all__ = ["collect_paths", "format_file", "open_dollar_quote", "parse_keyword", "run_formatter"]
 
 
 _SQLGLOT_MISSING_MSG = (
     "execsql format requires sqlglot for SQL reformatting.\n"
-    "  Install with:  pip install execsql2[formatter]\n"
+    '  Install the formatter extra:  uv tool install "execsql2[formatter]"  (or pip install "execsql2[formatter]")\n'
     "  Or skip SQL reformatting with the --no-sql flag."
 )
 
@@ -286,6 +286,33 @@ def _iter_sql_spans(sql: str) -> Iterator[tuple[int, int, str]]:
         i += 1
 
 
+def open_dollar_quote(sql: str, open_tag: str | None = None) -> str | None:
+    """The dollar-quote tag (``$$`` or ``$tag$``) still open at the end of *sql*, or ``None``.
+
+    *open_tag* is a tag already open where *sql* starts, as when a script is
+    split at a ``;`` inside a dollar-quoted body and *sql* is a later piece.
+    Comments, quoted identifiers and ``'...'`` literals are skipped, so a
+    ``$$`` inside them is not taken for a marker.
+    """
+    start = 0
+    if open_tag is not None:
+        close = sql.find(open_tag)
+        if close < 0:
+            return open_tag
+        start = close + len(open_tag)
+    rest = sql[start:]
+    for span_start, span_stop, kind in _iter_sql_spans(rest):
+        if kind != "dollar":
+            continue
+        m = _DOLLAR_QUOTE_RE.match(rest, span_start)
+        assert m is not None
+        tag = m.group(0)
+        body = rest[span_start:span_stop]
+        if len(body) < 2 * len(tag) or not body.endswith(tag):
+            return tag
+    return None
+
+
 def _iter_sql_literals(sql: str) -> Iterator[tuple[int, int, str]]:
     """Yield ``(start, end, kind)`` spans for every string literal in *sql*.
 

execsql/gui/desktop.py

@@ -162,7 +162,6 @@ class MsgDialog:
 class PauseDialog:
     def __init__(self, root: tk.Tk, args: dict) -> None:
         self.result: dict = {}
-        self._quit = False
 
         win = tk.Toplevel(root)
         win.title(args.get("title", "Pause"))
@@ -177,7 +176,6 @@ class PauseDialog:
         )
 
         countdown = args.get("countdown")
-        self._remaining = countdown
 
         status_var = tk.StringVar(value="")
         ttk.Label(frame, textvariable=status_var).pack()
@@ -897,7 +895,7 @@ class MapDialog:
                 frame,
                 text=(
                     "(Interactive map requires the tkintermapview package — "
-                    "`pip install execsql2[map]` — showing tabular data)"
+                    "install the map extra, execsql2[map] — showing tabular data)"
                 ),
                 wraplength=580,
                 justify="left",

execsql/gui/tui.py

@@ -12,7 +12,7 @@ SQL script in a background thread and keeps the main thread for the Textual
 ``_state.gui_manager_queue``; the conductor polls that queue and serves each
 request by pushing the appropriate ``ModalScreen`` via ``push_screen_wait()``.
 
-Install with: pip install "execsql2[tui]"
+Textual is a dependency of execsql2, so it is installed with the package.
 """
 
 from __future__ import annotations
@@ -33,7 +33,7 @@ try:
     import textual  # noqa: F401
 except ImportError as _e:
     raise ImportError(
-        "Textual is not installed. Install it with: pip install 'execsql2[tui]'",
+        "Textual is not installed. It is a dependency of execsql2; reinstall execsql2 to restore it.",
     ) from _e
 
 from textual import on

execsql/importers/base.py

@@ -16,7 +16,39 @@ from execsql.exceptions import ErrInfo
 from execsql.db.base import Database
 import execsql.state as _state
 
-__all__ = ["import_data_table"]
+__all__ = ["import_data_table", "refuse_existing_table", "table_exists_if_known"]
+
+
+def table_exists_if_known(db: Database, table_name: str, schema_name: str | None = None) -> bool | None:
+    """Whether the table exists, or ``None`` when the database cannot say (no catalog access, ...)."""
+    try:
+        return db.table_exists(table_name, schema_name)
+    except Exception:
+        return None
+
+
+def refuse_existing_table(db: Database, schema_name: str | None, table_name: str) -> None:
+    """Stop a ``TO NEW`` before any DDL when the target table already exists.
+
+    Only the schema the CREATE TABLE will use counts: for an unqualified
+    name, the database's current schema (MySQL: database).  Best effort:
+    when the database cannot say, the command goes ahead and the CREATE
+    TABLE reports any conflict itself.
+    """
+    lookup_schema = schema_name
+    if schema_name is None and not db.unqualified_lookup_is_scoped:
+        try:
+            lookup_schema = db.current_schema()
+        except Exception:
+            lookup_schema = None
+        if lookup_schema is None:
+            return  # An unqualified lookup would search every schema.
+    if table_exists_if_known(db, table_name, lookup_schema):
+        name = db.schema_qualified_table_name(schema_name, table_name)
+        raise ErrInfo(
+            type="cmd",
+            other_msg=f"Table {name} already exists",
+        )
 
 
 def import_data_table(
@@ -74,6 +106,8 @@ def import_data_table(
         return tablespec_cache
 
     if is_new:
+        if is_new == 1:
+            refuse_existing_table(db, schemaname, tablename)
         if is_new == 2:
             tblspec = db.schema_qualified_table_name(schemaname, tablename)
             try:

execsql/importers/csv.py

@@ -14,6 +14,7 @@ from typing import Any
 
 from execsql.exceptions import ErrInfo
 from execsql.db.base import Database
+from execsql.importers.base import refuse_existing_table
 import execsql.state as _state
 from execsql.types import dbt_firebird
 
@@ -26,7 +27,6 @@ def importtable(
     tablename: str,
     filename: str,
     is_new: Any,
-    skip_header_line: bool = True,
     quotechar: str | None = None,
     delimchar: str | None = None,
     encoding: str | None = None,
@@ -49,6 +49,8 @@ def importtable(
             quotechar = None
         inf.lineformat(delimchar, quotechar, None)
     if is_new in (1, 2):
+        if is_new == 1:
+            refuse_existing_table(db, schemaname, tablename)
         inf.evaluate_column_types()
         sql = inf.create_table(db.type, schemaname, tablename)
         if is_new == 2:

execsql/manifest.py

@@ -32,12 +32,16 @@ from execsql import __version__
 
 __all__ = ["RunManifest", "check_writable", "current", "start"]
 
-_current: RunManifest | None = None
-
 
 def current() -> RunManifest | None:
-    """The active manifest recorder, or ``None`` when ``--manifest`` was not given."""
-    return _current
+    """The active run's manifest recorder, or ``None`` when ``--manifest`` was not given.
+
+    Held on the run's :class:`~execsql.state.RuntimeContext`, so a library
+    ``execsql.run()`` in the same process never records into a CLI manifest.
+    """
+    import execsql.state as _state
+
+    return _state.manifest
 
 
 def check_writable(path: str) -> str | None:
@@ -65,10 +69,12 @@ def start(path: str, script: str | None, variables: list[str]) -> RunManifest:
     If nothing else writes it (``exit_now`` on an error, the end of a run), an
     ``atexit`` fallback does.
     """
-    global _current
-    _current = RunManifest(path, script, variables)
-    atexit.register(_current.finish, None)
-    return _current
+    import execsql.state as _state
+
+    manifest = RunManifest(path, script, variables)
+    _state.manifest = manifest
+    atexit.register(manifest.finish, None)
+    return manifest
 
 
 def _now() -> datetime.datetime:
@@ -137,22 +143,26 @@ class RunManifest:
 
     # -- finishing -------------------------------------------------------------
 
+    def add_error(self, error: Any) -> None:
+        """Record *error* (an :class:`ErrInfo`) in the manifest's ``errors``."""
+        # str(ErrInfo) is its concise message; errmsg() is the multi-line
+        # console block with a timestamp, which a reader of JSON does not want.
+        self.errors.append(
+            {
+                "message": " ".join(str(error).split()),
+                "type": getattr(error, "type", None),
+                "source": getattr(error, "script_file", None),
+                "line": getattr(error, "script_line_no", None),
+                "command": getattr(error, "cmd", None) or getattr(error, "command", None),
+            },
+        )
+
     def finish(self, exit_status: int | None, error: Any = None) -> None:
         """Write the manifest once. Later calls (the atexit fallback) do nothing."""
         if self.written:
             return
         if error is not None:
-            # str(ErrInfo) is its concise message; errmsg() is the multi-line
-            # console block with a timestamp, which a reader of JSON does not want.
-            self.errors.append(
-                {
-                    "message": " ".join(str(error).split()),
-                    "type": getattr(error, "type", None),
-                    "source": getattr(error, "script_file", None),
-                    "line": getattr(error, "script_line_no", None),
-                    "command": getattr(error, "cmd", None) or getattr(error, "command", None),
-                },
-            )
+            self.add_error(error)
         finished = _now()
         data = {
             "execsql_version": __version__,
@@ -172,9 +182,10 @@ class RunManifest:
             "errors": self.errors,
         }
         self.written = True
-        global _current
-        if _current is self:
-            _current = None
+        import execsql.state as _state
+
+        if _state.manifest is self:
+            _state.manifest = None
         atexit.unregister(self.finish)
         try:
             self.path.parent.mkdir(parents=True, exist_ok=True)

execsql/metacommands/conditions.py

@@ -100,12 +100,11 @@ def xf_hasrows(**kwargs: Any) -> bool:
     return bool(nrows > 0)
 
 
-def _row_count(queryname: str, sql_context: str, metacommandline: str) -> int:
+def _row_count(queryname: str, metacommandline: str) -> int:
     """Return the number of rows in *queryname*, raising ErrInfo on failure.
 
     Args:
         queryname: Table or view name to count rows in.
-        sql_context: The SQL string to include in error messages.
         metacommandline: The full metacommand line for error context.
 
     Returns:
@@ -167,7 +166,7 @@ def xf_row_count_gt(**kwargs: Any) -> bool:
     queryname = kwargs["queryname"]
     mcl = kwargs["metacommandline"]
     n = _parse_row_count_n(kwargs["n"], mcl)
-    return _row_count(queryname, f"select count(*) from {queryname};", mcl) > n
+    return _row_count(queryname, mcl) > n
 
 
 def xf_row_count_gte(**kwargs: Any) -> bool:
@@ -183,7 +182,7 @@ def xf_row_count_gte(**kwargs: Any) -> bool:
     queryname = kwargs["queryname"]
     mcl = kwargs["metacommandline"]
     n = _parse_row_count_n(kwargs["n"], mcl)
-    return _row_count(queryname, f"select count(*) from {queryname};", mcl) >= n
+    return _row_count(queryname, mcl) >= n
 
 
 def xf_row_count_eq(**kwargs: Any) -> bool:
@@ -199,7 +198,7 @@ def xf_row_count_eq(**kwargs: Any) -> bool:
     queryname = kwargs["queryname"]
     mcl = kwargs["metacommandline"]
     n = _parse_row_count_n(kwargs["n"], mcl)
-    return _row_count(queryname, f"select count(*) from {queryname};", mcl) == n
+    return _row_count(queryname, mcl) == n
 
 
 def xf_row_count_lt(**kwargs: Any) -> bool:
@@ -215,7 +214,7 @@ def xf_row_count_lt(**kwargs: Any) -> bool:
     queryname = kwargs["queryname"]
     mcl = kwargs["metacommandline"]
     n = _parse_row_count_n(kwargs["n"], mcl)
-    return _row_count(queryname, f"select count(*) from {queryname};", mcl) < n
+    return _row_count(queryname, mcl) < n
 
 
 def xf_sqlerror(**kwargs: Any) -> bool:
@@ -428,7 +427,7 @@ def xf_newer_date(**kwargs: Any) -> bool:
     datestr = unquoted(kwargs["datestr"])
     if not Path(file1).exists():
         raise ErrInfo(type="cmd", other_msg=f"File {file1} does not exist.")
-    dt_value = parse_datetime(datestr)
+    dt_value = parse_datetime(datestr, strict=False)
     if not dt_value:
         raise ErrInfo(type="cmd", other_msg=f"{datestr} can't be interpreted as a date/time.")
     return os.stat(file1).st_mtime > time.mktime(dt_value.timetuple())

execsql/metacommands/data.py

@@ -36,6 +36,7 @@ from execsql.parser import NumericParser
 from execsql.script import current_script_line
 from execsql.utils.crypto import Encrypt
 from execsql.utils.errors import exception_desc, exit_now
+from execsql.utils.fileio import register_secret
 from execsql.utils.gui import GUI_SELECTSUB, GuiSpec, enable_gui
 from execsql.utils.strings import get_subvarset, unquoted
 
@@ -126,7 +127,9 @@ def x_sub_encrypt(**kwargs: Any) -> None:
 def x_sub_decrypt(**kwargs: Any) -> None:
     varname = kwargs["match"]
     subvarset, varname = get_subvarset(varname, kwargs["metacommandline"])
-    subvarset.add_substitution(varname, Encrypt().decrypt(kwargs["crypttext"]))
+    plaintext = Encrypt().decrypt(kwargs["crypttext"])
+    register_secret(plaintext)
+    subvarset.add_substitution(varname, plaintext)
     return None
 
 

execsql/metacommands/debug.py

@@ -52,10 +52,8 @@ def x_debug_commandliststack(**kwargs: Any) -> None:
     ``<main>`` script, ``EXECUTE SCRIPT`` calls, ``INCLUDE``'d files,
     ``IF``/``ELSEIF``/``ELSE`` branches, ``LOOP`` iterations (with iteration
     count), and ``BATCH`` blocks. Each frame shows source file and line.
-
-    The legacy ``commandliststack`` is reported separately as a secondary view
-    because it only records SCRIPT call frames; the unified ``ast_exec_stack``
-    is the authoritative debugger view.
+    The metacommand keeps its upstream name; what it prints is the AST
+    executor's ``ast_exec_stack``.
     """
     stack = getattr(_state, "ast_exec_stack", None) or []
     _state.output.write(f"Execution Stack (depth: {len(stack)}):\n")

execsql/metacommands/io_fileops.py

@@ -8,14 +8,18 @@ Implements ``x_include``, ``x_copy``, ``x_copy_query``, ``x_zip``,
 from __future__ import annotations
 
 import os
+import pickle
+import struct
 import sys
-from itertools import tee
+import tempfile
+from collections.abc import Iterator
 from pathlib import Path
 from shutil import copyfileobj
-from typing import Any, Literal, cast
+from typing import Any, Literal
 
 import execsql.state as _state
 from execsql.exceptions import ErrInfo
+from execsql.importers.base import refuse_existing_table
 from execsql.models import DataTable
 from execsql.script import current_script_line
 from execsql.utils.errors import exception_desc
@@ -23,6 +27,39 @@ from execsql.utils.fileio import filewriter_close
 from execsql.utils.strings import unquoted
 
 
+class _RowSpool:
+    """Pass rows through while writing each to a temporary file, to be read back once more.
+
+    ``COPY ... TO NEW`` needs every row twice, once to describe the new table
+    and once to load it, but runs the source query once.  The rows are kept
+    in memory up to *max_size* bytes and on disk beyond that.  Each row is
+    pickled on its own, so neither pass keeps a reference to earlier rows.
+    """
+
+    _LENGTH = struct.Struct("<Q")
+
+    def __init__(self, rows: Any, max_size: int = 8 * 1024 * 1024) -> None:
+        self._rows = rows
+        self._file = tempfile.SpooledTemporaryFile(max_size=max_size)  # noqa: SIM115 - closed by close()
+
+    def __iter__(self) -> Iterator[Any]:
+        for row in self._rows:
+            data = pickle.dumps(row, protocol=pickle.HIGHEST_PROTOCOL)
+            self._file.write(self._LENGTH.pack(len(data)))
+            self._file.write(data)
+            yield row
+
+    def replay(self) -> Iterator[Any]:
+        """Yield the rows passed through, in order."""
+        self._file.seek(0)
+        while header := self._file.read(self._LENGTH.size):
+            (size,) = self._LENGTH.unpack(header)
+            yield pickle.loads(self._file.read(size))
+
+    def close(self) -> None:
+        self._file.close()
+
+
 def _close_rowsource(rows: Any) -> None:
     close = getattr(rows, "close", None)
     if close:
@@ -63,29 +100,16 @@ def x_copy(**kwargs: Any) -> None:
     db2 = _state.dbs.aliased_as(alias2)
     tbl1 = db1.schema_qualified_table_name(schema1, table1)
     tbl2 = db2.schema_qualified_table_name(schema2, table2)
-    try:
-        if not db1.table_exists(table1, schema1):
-            raise ErrInfo(
-                type="cmd",
-                command_text=kwargs["metacommandline"],
-                other_msg=f"Table {tbl1} does not exist",
-            )
-    except Exception:
-        pass  # Best-effort check; some adapters lack information_schema.
+    # No check that the source exists: the database may fold an unquoted name
+    # (PostgreSQL reads Orders as orders), and the SELECT below names a missing
+    # source in the database's own words.
     if new_tbl2 and new_tbl2 == "new":
-        try:
-            if db2.table_exists(table2, schema2):
-                raise ErrInfo(
-                    type="cmd",
-                    command_text=kwargs["metacommandline"],
-                    other_msg=f"Table {tbl2} already exists",
-                )
-        except Exception:
-            pass  # Best-effort check; some adapters lack information_schema.
+        refuse_existing_table(db2, schema2, table2)
     select_stmt = f"select * from {tbl1};"
 
     get_ts_tablespec = None
     rows_to_close = None
+    spool: _RowSpool | None = None
     rows_for_insert: Any
 
     if new_tbl2:
@@ -96,9 +120,10 @@ def x_copy(**kwargs: Any) -> None:
         except Exception as e:
             raise ErrInfo("db", select_stmt, exception_msg=exception_desc()) from e
         rows_to_close = rows
-        rows = cast(Any, rows)
-        rows_for_schema, rows_for_insert = tee(rows)
-        get_ts_tablespec = DataTable(hdrs, rows_for_schema)
+        # Values come from a database cursor, so a text value stays text.
+        spool = _RowSpool(rows)
+        get_ts_tablespec = DataTable(hdrs, spool, infer_strings=False)
+        rows_for_insert = spool.replay()
         tbl_desc = get_ts_tablespec
         create_tbl = tbl_desc.create_table(db2.type, schema2, table2)
         if new_tbl2 == "replacement":
@@ -129,7 +154,7 @@ def x_copy(**kwargs: Any) -> None:
         nonlocal get_ts_tablespec
         if get_ts_tablespec is None:
             ts_hdrs, ts_rows = db1.select_rowsource(select_stmt)
-            get_ts_tablespec = DataTable(ts_hdrs, ts_rows)
+            get_ts_tablespec = DataTable(ts_hdrs, ts_rows, infer_strings=False)
         return get_ts_tablespec
 
     try:
@@ -138,6 +163,9 @@ def x_copy(**kwargs: Any) -> None:
     except BaseException:
         _close_rowsource(rows_to_close)
         raise
+    finally:
+        if spool is not None:
+            spool.close()
 
 
 def x_copy_query(**kwargs: Any) -> None:
@@ -164,18 +192,11 @@ def x_copy_query(**kwargs: Any) -> None:
     db2 = _state.dbs.aliased_as(alias2)
     tbl2 = db2.schema_qualified_table_name(schema2, table2)
     if new_tbl2 and new_tbl2 == "new":
-        try:
-            if db2.table_exists(table2, schema2):
-                raise ErrInfo(
-                    type="cmd",
-                    command_text=kwargs["metacommandline"],
-                    other_msg=f"Table {tbl2} already exists",
-                )
-        except Exception:
-            pass  # Best-effort check; some adapters lack information_schema.
+        refuse_existing_table(db2, schema2, table2)
 
     get_ts_tablespec = None
     rows_to_close = None
+    spool: _RowSpool | None = None
     rows_for_insert: Any
 
     if new_tbl2:
@@ -186,9 +207,10 @@ def x_copy_query(**kwargs: Any) -> None:
         except Exception as e:
             raise ErrInfo("db", select_stmt, exception_msg=exception_desc()) from e
         rows_to_close = rows
-        rows = cast(Any, rows)
-        rows_for_schema, rows_for_insert = tee(rows)
-        get_ts_tablespec = DataTable(hdrs, rows_for_schema)
+        # Values come from a database cursor, so a text value stays text.
+        spool = _RowSpool(rows)
+        get_ts_tablespec = DataTable(hdrs, spool, infer_strings=False)
+        rows_for_insert = spool.replay()
         tbl_desc = get_ts_tablespec
         create_tbl = tbl_desc.create_table(db2.type, schema2, table2)
         if new_tbl2 == "replacement":
@@ -219,7 +241,7 @@ def x_copy_query(**kwargs: Any) -> None:
         nonlocal get_ts_tablespec
         if get_ts_tablespec is None:
             ts_hdrs, ts_rows = db1.select_rowsource(select_stmt)
-            get_ts_tablespec = DataTable(ts_hdrs, ts_rows)
+            get_ts_tablespec = DataTable(ts_hdrs, ts_rows, infer_strings=False)
         return get_ts_tablespec
 
     try:
@@ -228,6 +250,9 @@ def x_copy_query(**kwargs: Any) -> None:
     except BaseException:
         _close_rowsource(rows_to_close)
         raise
+    finally:
+        if spool is not None:
+            spool.close()
 
 
 def x_zip(**kwargs: Any) -> None:

execsql/metacommands/io_import.py

@@ -74,7 +74,6 @@ def x_import(**kwargs: Any) -> None:
             tablename,
             filename,
             is_new,
-            skip_header_line=True,
             quotechar=quotechar,
             delimchar=delimchar,
             encoding=enc,

execsql/metacommands/prompt.py

@@ -67,6 +67,7 @@ from execsql.utils.gui import (
     pause,
     pause_win,
 )
+from execsql.utils.fileio import register_secret
 from execsql.utils.strings import unquoted
 
 
@@ -144,6 +145,7 @@ def x_prompt_enter(**kwargs: Any) -> None:
         subvarset.add_substitution(sub_var, txtval)
         script_name, lno = current_script_line()
         if as_pw:
+            register_secret(txtval)
             _state.exec_log.log_status_info(f"Password assigned to variable {{{sub_var}}} on line {lno}.")
         else:
             _state.exec_log.log_status_info(f"Variable {{{sub_var}}} set to {{{txtval}}} on line {lno}.")

execsql/metacommands/upsert.py

@@ -4,7 +4,7 @@ Integrates pg-upsert (https://pg-upsert.readthedocs.io/) as an optional
 dependency, providing QA-checked, FK-dependency-ordered upserts from a
 staging schema to a base schema on PostgreSQL.
 
-Requires: ``pip install execsql2[upsert]``
+Requires the ``upsert`` extra (``execsql2[upsert]``).
 """
 
 from __future__ import annotations
@@ -213,7 +213,10 @@ def _require_pg_upsert() -> None:
     except ImportError as exc:
         raise ErrInfo(
             "exception",
-            other_msg=("PG_UPSERT requires the pg-upsert package. Install it with: pip install execsql2[upsert]"),
+            other_msg=(
+                'PG_UPSERT requires the pg-upsert package. Install the upsert extra: uv tool install "execsql2[upsert]"'
+                ' (or pip install "execsql2[upsert]").'
+            ),
         ) from exc
 
 

execsql/models.py

@@ -268,7 +268,6 @@ class DataTable:
 
         self.inputrows = 0  # Total number of rows in the row source.
         self.datarows = 0  # Number of non-empty rows (with data values).
-        self.shortrows = 0  # Number of rows without as many data values as column names.
         self.cols: list = []  # List of Column objects.
         for n in column_names:
             self.cols.append(Column(n, infer_strings=infer_strings))
@@ -281,7 +280,6 @@ class DataTable:
                 self.datarows += 1
                 chkcols = len(self.cols)
                 if dataitems < chkcols:
-                    self.shortrows += 1
                     chkcols = len(datarow)
                 else:
                     if dataitems > chkcols:
@@ -307,6 +305,9 @@ class DataTable:
                             raise DataTableError(errmsg)
                 for i in range(chkcols):
                     self.cols[i].eval_types(datarow[i])
+                # Trailing values left off a short row are imported as NULL.
+                for i in range(chkcols, len(self.cols)):
+                    self.cols[i].eval_types(None)
         for col in self.cols:
             col.column_type()
 

execsql/parser.py

@@ -215,10 +215,17 @@ class CondParser(CondTokens):
     """Recursive-descent parser for boolean conditional expressions."""
 
     # Takes a conditional expression string.
-    def __init__(self, condexpr: str) -> None:
-        """Initialise the parser with the conditional expression string."""
+    def __init__(self, condexpr: str, conditionallist: Any = None) -> None:
+        """Initialise the parser with the conditional expression string.
+
+        *conditionallist* is the table of conditional tests to match against;
+        ``None`` means the current run's ``conditionallist``.  Passing one lets
+        a caller with no run in progress, such as ``execsql lint``, parse
+        (without evaluating) a condition.
+        """
         self.condexpr = condexpr
         self.cond_expr = SourceString(condexpr)
+        self.conditionallist = conditionallist
 
     def match_not(self) -> int | None:
         """Match a NOT operator and return its token type, or None."""
@@ -251,10 +258,12 @@ class CondParser(CondTokens):
             m1 = self.factor()
             return CondAstNode(self.NOT, m1, None)
         # Find the matching metacommand -- get a tuple consisting of (metacommand, groupdict)
-        # conditionallist is a module-level global in the main execsql module
-        import execsql.state as _state
+        conditionallist = self.conditionallist
+        if conditionallist is None:
+            import execsql.state as _state
 
-        matched_metacommand = self.cond_expr.match_metacommand(_state.conditionallist)
+            conditionallist = _state.conditionallist
+        matched_metacommand = self.cond_expr.match_metacommand(conditionallist)
         if matched_metacommand is not None:
             matched_metacommand[1]["metacommandline"] = self.condexpr
             return CondAstNode(self.CONDITIONAL, matched_metacommand, None)