execsql2 2.12.2__tar.gz → 2.12.3__tar.gz

{execsql2-2.12.2 → execsql2-2.12.3}/CHANGELOG.md

@@ -13,6 +13,17 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.12.3] - 2026-04-02
+
+### Changed
+
+- Performance: split `set_system_vars()` into static (once per script + on CONNECT/CHDIR) and dynamic (per statement) — eliminates ~14 redundant `add_substitution` calls and 2 `Path.resolve()` filesystem syscalls per statement.
+- Performance: `$RANDOM` and `$UUID` are now lazy — computed only when actually referenced in a statement, not generated unconditionally for every statement.
+- Performance: `LineDelimiter.delimited()` caches `quote_all_text` at construction time instead of reading `_state.conf` via module proxy on every row during export.
+- Performance: CSV/TSV import uses Python's `csv` module as a fast path for standard delimited formats (comma, tab, semicolon, pipe) with doubled-quote escaping. Falls back to the character-at-a-time parser for non-standard formats (space-delimiter collapsing, escape characters).
+
+______________________________________________________________________
+
 ## [2.12.2] - 2026-04-02
 
 ### Added

{execsql2-2.12.2 → execsql2-2.12.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.12.2
+Version: 2.12.3
 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.12.2 → execsql2-2.12.3}/docs/about/divergence.md

@@ -163,6 +163,12 @@ All 33 mutable runtime globals in `state.py` have been consolidated into a `Runt
 
 - **Cycle detection** — `substitute_vars()` raises an error after 100 iterations to prevent infinite loops when variables reference each other cyclically. Upstream had no protection.
 - **O(1) substitution** — Variable substitution uses a single combined regex and dict lookup instead of O(V) per-variable regex passes. Behavior is identical; performance is improved.
+- **Lazy `$RANDOM`/`$UUID`** — These system variables are now computed on first access rather than generated unconditionally for every statement. Behavior is identical when referenced; scripts that never reference them skip the computation entirely.
+- **Static/dynamic system var split** — System substitution variables are split into static (set once per script and refreshed on CONNECT/CHDIR) and dynamic (refreshed per statement). Eliminates redundant `Path.resolve()` syscalls and database pool lookups per statement.
+
+### CSV Import
+
+- **Fast-path CSV reader** — Standard delimited imports (comma, tab, semicolon, pipe with doubled-quote escaping) now use Python's `csv` module. Non-standard formats (space-delimiter collapsing, escape characters) fall back to the original character-at-a-time parser.
 
 ### Database Adapters
 

{execsql2-2.12.2 → execsql2-2.12.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execsql2"
-version = "2.12.2"
+version = "2.12.3"
 description = "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."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE.txt" }
@@ -159,7 +159,7 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.bumpversion]
-current_version = "2.12.2"
+current_version = "2.12.3"
 commit = true
 commit_args = "--no-verify"
 tag = true

{execsql2-2.12.2 → execsql2-2.12.3}/src/execsql/db/base.py

@@ -686,6 +686,13 @@ class DatabasePool:
             )
             self.pool[db_alias].close()
         self.pool[db_alias] = db_obj
+        # Refresh static system vars so $DB_NAME, $DB_USER, etc. reflect the new connection.
+        try:
+            from execsql.script.engine import set_static_system_vars
+
+            set_static_system_vars()
+        except Exception:
+            pass  # Engine not yet initialized (early startup).
 
     def aliases(self) -> list[str]:
         """Return a list of all currently registered database aliases."""

{execsql2-2.12.2 → execsql2-2.12.3}/src/execsql/exporters/delimited.py

@@ -40,6 +40,7 @@ class LineDelimiter:
         self.delimiter = delim
         self.joinchar = delim if delim else ""
         self.quotechar = quote
+        self.quote_all_text = _state.conf.quote_all_text if _state.conf else False
         if quote:
             if escchar:
                 self.quotedquote = escchar + quote
@@ -50,13 +51,12 @@ class LineDelimiter:
 
     def delimited(self, datarow: Any, add_newline: bool = True) -> str:
         """Format a sequence of values as a single delimited text line."""
-        conf = _state.conf
         if self.quotechar:
             d_row = []
             for e in datarow:
                 if isinstance(e, str):
                     if (
-                        conf.quote_all_text
+                        self.quote_all_text
                         or (self.quotechar in e)
                         or (self.delimiter is not None and self.delimiter in e)
                         or ("\n" in e)
@@ -609,10 +609,52 @@ class CsvFile(EncodedFile):
             raise ErrInfo("error", other_msg=", ".join(self.parse_errors))
         return elements
 
+    def _can_use_fast_csv_reader(self) -> bool:
+        """Return True if the detected format is compatible with Python's csv module."""
+        # The csv module handles comma/tab delimiters with doubled-quote escaping.
+        # It cannot handle: space-delimiter collapsing, escape chars, or no delimiter.
+        if self.delimiter is None or self.delimiter == " ":
+            return False
+        return self.escapechar is None
+
     def reader(self) -> Any:
         """Yield parsed rows from the file as lists of field values."""
         conf = _state.conf
         self.evaluate_line_format()
+        if self._can_use_fast_csv_reader():
+            yield from self._fast_reader(conf)
+        else:
+            yield from self._slow_reader(conf)
+
+    def _fast_reader(self, conf: Any) -> Any:
+        """Read using Python's csv module (fast path for standard delimited formats)."""
+        import csv
+
+        f = self.openclean("rt")
+        try:
+            csv_reader = csv.reader(
+                f,
+                delimiter=self.delimiter,
+                quotechar=self.quotechar,
+                doublequote=True,
+                strict=False,
+            )
+            for elements in csv_reader:
+                if len(elements) == 0:
+                    break
+                # Normalize empty strings to None for parity with the slow reader.
+                elements = [e if e != "" else None for e in elements]
+                if conf.del_empty_cols and len(self.blank_cols) > 0:
+                    blanks = copy.copy(self.blank_cols)
+                    while len(blanks) > 0:
+                        b = blanks.pop()
+                        del elements[b]
+                yield elements
+        finally:
+            f.close()
+
+    def _slow_reader(self, conf: Any) -> Any:
+        """Read using the character-at-a-time state machine (fallback for non-standard formats)."""
         f = self.openclean("rt")
         line_no = 0
         try:

{execsql2-2.12.2 → execsql2-2.12.3}/src/execsql/metacommands/io_fileops.py

@@ -241,6 +241,10 @@ def x_cd(**kwargs: Any) -> None:
     os.chdir(new_dir)
     script, lno = current_script_line()
     _state.exec_log.log_status_info(f"Current directory changed to {new_dir} at line {lno} of {script}")
+    if _state.subvars is not None:
+        from execsql.script.engine import set_static_system_vars
+
+        set_static_system_vars()
     return None
 
 

{execsql2-2.12.2 → execsql2-2.12.3}/src/execsql/script/__init__.py

@@ -63,6 +63,8 @@ from execsql.script.engine import (
     read_sqlfile,
     read_sqlstring,
     runscripts,
+    set_dynamic_system_vars,
+    set_static_system_vars,
     set_system_vars,
     substitute_vars,
 )
@@ -86,6 +88,8 @@ __all__ = [
     "CommandListUntilLoop",
     "ScriptFile",
     "ScriptExecSpec",
+    "set_dynamic_system_vars",
+    "set_static_system_vars",
     "set_system_vars",
     "substitute_vars",
     "runscripts",

{execsql2-2.12.2 → execsql2-2.12.3}/src/execsql/script/engine.py

@@ -704,9 +704,45 @@ class ScriptExecSpec:
 # ---------------------------------------------------------------------------
 
 
-def set_system_vars() -> None:
-    """Refresh all built-in system substitution variables (``$CURRENT_TIME``, ``$DB_NAME``, etc.)."""
-    # (Re)define the system substitution variables that are not script-specific.
+def set_static_system_vars() -> None:
+    """Set system substitution variables that only change on CONNECT or CHDIR.
+
+    Called once before the execution loop.  These values are expensive to compute
+    (filesystem syscalls, database pool lookups) but rarely change — only on
+    ``CONNECT``, ``USE``, or ``CHDIR`` metacommands.  The ``runscripts()`` loop
+    calls this once up front; metacommand handlers that change the connection or
+    working directory should call it again afterward.
+    """
+    import random
+
+    cwd = str(Path(".").resolve())
+    _state.subvars.add_substitution("$CURRENT_DIR", cwd)
+    _state.subvars.add_substitution("$CURRENT_PATH", cwd + os.sep)
+    _state.subvars.add_substitution("$CURRENT_ALIAS", _state.dbs.current_alias())
+    db = _state.dbs.current()
+    _state.subvars.add_substitution("$DB_USER", db.user if db.user else "")
+    _state.subvars.add_substitution(
+        "$DB_SERVER",
+        db.server_name if db.server_name else "",
+    )
+    _state.subvars.add_substitution("$DB_NAME", db.db_name)
+    _state.subvars.add_substitution("$DB_NEED_PWD", "TRUE" if db.need_passwd else "FALSE")
+    _state.subvars.add_substitution("$VERSION1", str(_state.primary_vno))
+    _state.subvars.add_substitution("$VERSION2", str(_state.secondary_vno))
+    _state.subvars.add_substitution("$VERSION3", str(_state.tertiary_vno))
+    # Register lazy providers for $RANDOM and $UUID — computed only when referenced.
+    _state.subvars.register_lazy("$random", lambda: str(random.random()))
+    _state.subvars.register_lazy("$uuid", lambda: str(uuid.uuid4()))
+
+
+def set_dynamic_system_vars() -> None:
+    """Refresh system substitution variables that change every statement.
+
+    Called once per statement in the execution loop.  Includes cheap boolean-to-string
+    conversions for halt states and autocommit (which can change on any CONFIG or
+    AUTOCOMMIT metacommand) plus ``$TIMER`` and lazy-variable cache reset.
+    """
+    # Halt/config state vars — cheap to set, can change on any CONFIG metacommand.
     _state.subvars.add_substitution("$CANCEL_HALT_STATE", "ON" if _state.status.cancel_halt else "OFF")
     _state.subvars.add_substitution("$ERROR_HALT_STATE", "ON" if _state.status.halt_on_err else "OFF")
     _state.subvars.add_substitution(
@@ -718,27 +754,22 @@ def set_system_vars() -> None:
         "ON" if _state.conf.gui_wait_on_error_halt else "OFF",
     )
     _state.subvars.add_substitution("$CONSOLE_WAIT_WHEN_DONE_STATE", "ON" if _state.conf.gui_wait_on_exit else "OFF")
-    # $CURRENT_TIME is set per-statement in run_and_increment() for accuracy.
-    _state.subvars.add_substitution("$CURRENT_DIR", str(Path(".").resolve()))
-    _state.subvars.add_substitution("$CURRENT_PATH", str(Path(".").resolve()) + os.sep)
-    _state.subvars.add_substitution("$CURRENT_ALIAS", _state.dbs.current_alias())
     db = _state.dbs.current()
     _state.subvars.add_substitution("$AUTOCOMMIT_STATE", "ON" if db.autocommit else "OFF")
+    # $CURRENT_TIME is set per-statement in run_and_increment() for accuracy.
     _state.subvars.add_substitution("$TIMER", str(datetime.timedelta(seconds=_state.timer.elapsed())))
-    _state.subvars.add_substitution("$DB_USER", db.user if db.user else "")
-    _state.subvars.add_substitution(
-        "$DB_SERVER",
-        db.server_name if db.server_name else "",
-    )
-    _state.subvars.add_substitution("$DB_NAME", db.db_name)
-    _state.subvars.add_substitution("$DB_NEED_PWD", "TRUE" if db.need_passwd else "FALSE")
-    import random
+    _state.subvars.clear_lazy_cache()
 
-    _state.subvars.add_substitution("$RANDOM", str(random.random()))
-    _state.subvars.add_substitution("$UUID", str(uuid.uuid4()))
-    _state.subvars.add_substitution("$VERSION1", str(_state.primary_vno))
-    _state.subvars.add_substitution("$VERSION2", str(_state.secondary_vno))
-    _state.subvars.add_substitution("$VERSION3", str(_state.tertiary_vno))
+
+def set_system_vars() -> None:
+    """Refresh all built-in system substitution variables.
+
+    Convenience wrapper that calls both :func:`set_static_system_vars` and
+    :func:`set_dynamic_system_vars`.  Retained for backward compatibility with
+    tests and any external callers.
+    """
+    set_static_system_vars()
+    set_dynamic_system_vars()
 
 
 _MAX_SUBSTITUTION_DEPTH = 100
@@ -779,11 +810,12 @@ def substitute_vars(command_str: str, localvars: SubVarSet | None = None) -> str
 
 def runscripts() -> None:
     """Drive execution until the command-list stack is empty."""
-    # Repeatedly run the next statement from the script at the top of the
-    # command list stack until there are no more statements.
+    # Set static vars once before the loop; they are refreshed by metacommand
+    # handlers (CONNECT, CONFIG, AUTOCOMMIT, CHDIR) when state changes.
+    set_static_system_vars()
     while len(_state.commandliststack) > 0:
         current_cmds = _state.commandliststack[-1]
-        set_system_vars()
+        set_dynamic_system_vars()
         try:
             current_cmds.run_next()
         except StopIteration:

{execsql2-2.12.2 → execsql2-2.12.3}/src/execsql/script/variables.py

@@ -89,6 +89,7 @@ class SubVarSet:
     # compatibility with external code.
     def __init__(self) -> None:
         self._subs_dict: dict[str, Any] = {}
+        self._lazy_providers: dict[str, Any] = {}
         self.prefix_list: list[str] = ["$", "&", "@"]
         # Don't construct/compile on init because deepcopy() can't handle compiled regexes.
         self.var_rx = None
@@ -120,6 +121,30 @@ class SubVarSet:
         if not self.var_name_ok(varname.lower()):
             raise ErrInfo("error", other_msg=f"Invalid variable name ({varname}) in this context.")
 
+    def register_lazy(self, varname: str, provider: Any) -> None:
+        """Register a lazy variable whose value is computed on first access per cycle.
+
+        The *provider* callable is invoked only when the variable is actually
+        referenced (via :meth:`substitute`, :meth:`varvalue`, etc.).  The result
+        is cached in ``_subs_dict`` until :meth:`clear_lazy_cache` is called.
+        """
+        self.check_var_name(varname)
+        self._lazy_providers[varname.lower()] = provider
+
+    def clear_lazy_cache(self) -> None:
+        """Remove materialized lazy values so they regenerate on next access."""
+        for key in self._lazy_providers:
+            self._subs_dict.pop(key, None)
+
+    def _materialize_lazy(self, varname: str) -> str | None:
+        """If *varname* has a lazy provider, invoke it, cache the result, and return it."""
+        provider = self._lazy_providers.get(varname)
+        if provider is not None:
+            value = str(provider())
+            self._subs_dict[varname] = value
+            return value
+        return None
+
     def remove_substitution(self, template_str: str) -> None:
         """Remove the variable named *template_str* from the substitution pool."""
         self.check_var_name(template_str)
@@ -143,7 +168,11 @@ class SubVarSet:
     def varvalue(self, varname: str) -> str | None:
         """Return the value of *varname*, or ``None`` if it is not defined."""
         self.check_var_name(varname)
-        return self._subs_dict.get(varname.lower())
+        key = varname.lower()
+        val = self._subs_dict.get(key)
+        if val is None and key in self._lazy_providers:
+            return self._materialize_lazy(key)
+        return val
 
     def increment_by(self, varname: str, numeric_increment: Any) -> None:
         self.check_var_name(varname)
@@ -165,13 +194,15 @@ class SubVarSet:
     def sub_exists(self, template_str: str) -> bool:
         """Return True if the variable named *template_str* is defined."""
         self.check_var_name(template_str)
-        return template_str.lower() in self._subs_dict
+        key = template_str.lower()
+        return key in self._subs_dict or key in self._lazy_providers
 
     def merge(self, other_subvars: SubVarSet | None) -> SubVarSet:
         """Return a new SubVarSet with this object's variables merged with other_subvars."""
         if other_subvars is not None:
             newsubs = SubVarSet()
             newsubs._subs_dict = {**self._subs_dict, **other_subvars._subs_dict}
+            newsubs._lazy_providers = {**self._lazy_providers, **other_subvars._lazy_providers}
             newsubs.prefix_list = list(set(self.prefix_list + other_subvars.prefix_list))
             newsubs.compile_var_rx()
             return newsubs
@@ -201,6 +232,8 @@ class SubVarSet:
         m = self._TOKEN_RX.search(command_str)
         while m:
             varname = m.group("varname").lower()
+            if varname not in self._subs_dict and varname in self._lazy_providers:
+                self._materialize_lazy(varname)
             if varname in self._subs_dict:
                 sub = self._subs_dict[varname]
                 if sub is None:

{execsql2-2.12.2 → execsql2-2.12.3}/tests/exporters/test_delimited.py

@@ -616,12 +616,13 @@ class TestCsvFile:
         assert any("Alice" in str(r) for r in data_rows)
 
     def test_reader_reraises_errinfo_with_line_number(self, tmp_path):
-        # Line 609: reader() wraps ErrInfo with line number context
+        # Tests the slow reader path error handling (line number annotation).
+        # Use an escape char to force the slow reader path.
         p = tmp_path / "bad.csv"
         # Write a CSV that will parse, but mock read_and_parse_line to raise ErrInfo
         p.write_text("id,name\n1,Alice\n", encoding="utf-8")
         cf = CsvFile(str(p), "utf-8")
-        cf.lineformat(",", '"', None)
+        cf.lineformat(",", '"', "\\")
         with (
             patch.object(cf, "read_and_parse_line", side_effect=ErrInfo("error", other_msg="parse fail")),
             pytest.raises(ErrInfo) as exc_info,
@@ -899,7 +900,15 @@ class TestCsvLine:
 
 
 class TestReadAndParseLine:
-    """Tests for read_and_parse_line() via full CsvFile.reader() pipeline."""
+    """Tests for read_and_parse_line() via full CsvFile.reader() pipeline.
+
+    Forces the slow (character-at-a-time) reader by patching _can_use_fast_csv_reader
+    so that these tests exercise the state machine, not Python's csv module.
+    """
+
+    @pytest.fixture(autouse=True)
+    def _force_slow_reader(self, monkeypatch):
+        monkeypatch.setattr(CsvFile, "_can_use_fast_csv_reader", lambda self: False)
 
     def _make_csvfile_from_content(self, content, tmp_path, delim=",", quote='"', escape=None):
         p = tmp_path / "test.csv"

{execsql2-2.12.2 → execsql2-2.12.3}/uv.lock

@@ -657,7 +657,7 @@ wheels = [
 
 [[package]]
 name = "execsql2"
-version = "2.12.2"
+version = "2.12.3"
 source = { editable = "." }
 dependencies = [
     { name = "rich" },