execsql2 2.1.2__py3-none-any.whl → 2.4.0__py3-none-any.whl

execsql/script/variables.py

@@ -0,0 +1,281 @@
+from __future__ import annotations
+
+"""Variable containers for execsql script execution.
+
+Classes:
+- :class:`CounterVars` — named auto-incrementing integer counters.
+- :class:`SubVarSet` — global ``!!$VAR!!`` substitution-variable store.
+- :class:`LocalSubVarSet` — per-script ``~``-prefixed local variable overlay.
+- :class:`ScriptArgSubVarSet` — per-script ``#``-prefixed argument overlay.
+"""
+
+import os
+import re
+from typing import Any
+
+from execsql.exceptions import ErrInfo
+
+
+# ---------------------------------------------------------------------------
+# CounterVars
+# ---------------------------------------------------------------------------
+
+
+class CounterVars:
+    """Named auto-incrementing integer counters referenced as ``!!$COUNTER_N!!``."""
+
+    # A dictionary of dynamically created named counter variables.
+    _COUNTER_RX = re.compile(r"!!\$(COUNTER_\d+)!!", re.I)
+
+    def __init__(self) -> None:
+        self.counters: dict[str, int] = {}
+
+    def _ctrid(self, ctr_no: int) -> str:
+        return f"counter_{ctr_no}"
+
+    def set_counter(self, ctr_no: int, ctr_val: int) -> None:
+        self.counters[self._ctrid(ctr_no)] = ctr_val
+
+    def remove_counter(self, ctr_no: int) -> None:
+        ctr_id = self._ctrid(ctr_no)
+        if ctr_id in self.counters:
+            del self.counters[ctr_id]
+
+    def remove_all_counters(self) -> None:
+        self.counters = {}
+
+    def substitute(self, command_str: str) -> tuple:
+        # Substitutes any counter variable references with the counter value and
+        # returns the modified command string and a flag indicating replacements.
+        m = self._COUNTER_RX.search(command_str, re.I)
+        if m:
+            ctr_id = m.group(1).lower()
+            if ctr_id not in self.counters:
+                self.counters[ctr_id] = 0
+            new_count = self.counters[ctr_id] + 1
+            self.counters[ctr_id] = new_count
+            return command_str.replace("!!$" + m.group(1) + "!!", str(new_count)), True
+        return command_str, False
+
+    def substitute_all(self, any_text: str) -> tuple:
+        subbed = True
+        any_subbed = False
+        while subbed:
+            any_text, subbed = self.substitute(any_text)
+            if subbed:
+                any_subbed = True
+        return any_text, any_subbed
+
+
+# ---------------------------------------------------------------------------
+# SubVarSet / LocalSubVarSet / ScriptArgSubVarSet
+# ---------------------------------------------------------------------------
+
+
+class SubVarSet:
+    """Pool of ``!!$VAR!!``-style substitution variables.
+
+    Variable names are stored in lowercase.  Supports ``$``, ``&``, and ``@``
+    prefixes by default.  Use :meth:`add_substitution` / :meth:`remove_substitution`
+    to manage entries, and :meth:`substitute_all` to expand a string.
+    """
+
+    # A pool of substitution variables.  Each variable consists of a name and
+    # a (string) value.  All variable names are stored as lowercase text.
+    # Internally uses a dict for O(1) lookups; the ``substitutions`` property
+    # exposes the data as a list of ``(name, value)`` tuples for backward
+    # compatibility with external code.
+    def __init__(self) -> None:
+        self._subs_dict: dict[str, Any] = {}
+        self._compiled_patterns: dict[str, tuple] = {}
+        self.prefix_list: list[str] = ["$", "&", "@"]
+        # Don't construct/compile on init because deepcopy() can't handle compiled regexes.
+        self.var_rx = None
+
+    @property
+    def substitutions(self) -> list[tuple]:
+        """Backward-compatible view of substitutions as a list of (name, value) tuples."""
+        return list(self._subs_dict.items())
+
+    @substitutions.setter
+    def substitutions(self, value: Any) -> None:
+        """Accept a list of (name, value) tuples or a dict and populate the internal dict."""
+        if isinstance(value, dict):
+            self._subs_dict = dict(value)
+        else:
+            self._subs_dict = dict(value)
+        self._rebuild_all_patterns()
+
+    def _compile_patterns_for(self, varname: str) -> tuple:
+        """Compile and return the three regex patterns (plain, single-quoted, double-quoted) for *varname*."""
+        match_escaped = "\\" + varname if varname[0] == "$" else varname
+        pat = re.compile(f"!!{match_escaped}!!", re.I)
+        patq = re.compile(f"!'!{match_escaped}!'!", re.I)
+        patdq = re.compile(f'!"!{match_escaped}!"!', re.I)
+        return (pat, patq, patdq)
+
+    def _rebuild_all_patterns(self) -> None:
+        """Rebuild compiled patterns for every variable currently stored."""
+        self._compiled_patterns = {}
+        for varname in self._subs_dict:
+            self._compiled_patterns[varname] = self._compile_patterns_for(varname)
+
+    def compile_var_rx(self) -> None:
+        """Compile the variable-name validation regex from the current prefix list."""
+        self.var_rx_str = r"^[" + "".join(self.prefix_list) + r"]?\w+$"
+        self.var_rx = re.compile(self.var_rx_str, re.I)
+
+    def var_name_ok(self, varname: str) -> bool:
+        if self.var_rx is None:
+            self.compile_var_rx()
+        return self.var_rx.match(varname) is not None
+
+    def check_var_name(self, varname: str) -> None:
+        if not self.var_name_ok(varname.lower()):
+            raise ErrInfo("error", other_msg=f"Invalid variable name ({varname}) in this context.")
+
+    def remove_substitution(self, template_str: str) -> None:
+        """Remove the variable named *template_str* from the substitution pool."""
+        self.check_var_name(template_str)
+        old_sub = template_str.lower()
+        self._subs_dict.pop(old_sub, None)
+        self._compiled_patterns.pop(old_sub, None)
+
+    def add_substitution(self, varname: str, repl_str: Any) -> None:
+        """Add or overwrite a substitution variable, compiling its match patterns."""
+        self.check_var_name(varname)
+        varname = varname.lower()
+        self._subs_dict[varname] = repl_str
+        self._compiled_patterns[varname] = self._compile_patterns_for(varname)
+
+    def append_substitution(self, varname: str, repl_str: str) -> None:
+        self.check_var_name(varname)
+        varname = varname.lower()
+        if varname in self._subs_dict:
+            self.add_substitution(varname, f"{self._subs_dict[varname]}\n{repl_str}")
+        else:
+            self.add_substitution(varname, repl_str)
+
+    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())
+
+    def increment_by(self, varname: str, numeric_increment: Any) -> None:
+        self.check_var_name(varname)
+        varvalue = self.varvalue(varname)
+        if varvalue is None:
+            varvalue = "0"
+            self.add_substitution(varname, varvalue)
+        # Import as_numeric lazily to avoid circular dependency
+        from execsql.utils.numeric import as_numeric
+
+        numvalue = as_numeric(varvalue)
+        numinc = as_numeric(numeric_increment)
+        if numvalue is None or numinc is None:
+            newval = f"{varvalue}+{numeric_increment}"
+        else:
+            newval = str(numvalue + numinc)
+        self.add_substitution(varname, newval)
+
+    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
+
+    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 = dict(self._subs_dict)
+            newsubs._compiled_patterns = dict(self._compiled_patterns)
+            newsubs.prefix_list = list(set(self.prefix_list + other_subvars.prefix_list))
+            newsubs.compile_var_rx()
+            for varname, value in other_subvars._subs_dict.items():
+                newsubs.add_substitution(varname, value)
+            return newsubs
+        return self
+
+    # Combined regex matching any variable token in one pass.
+    # Group 1: quote marker — empty for plain !!var!!, ' for !'!var!'!, " for !"!var!"!
+    # Group 2: variable name (with optional prefix character)
+    _TOKEN_RX = re.compile(
+        r"!(?P<q>['\"]?)!(?P<varname>[$&@~#]?\w+)!(?P=q)!",
+        re.I,
+    )
+
+    def substitute(self, command_str: str) -> tuple:
+        """Replace the first matching variable token in *command_str*.
+
+        Uses a single combined regex to find any ``!!var!!``, ``!'!var!'!``, or
+        ``!"!var!"!`` token in one pass, then looks up the variable name in the
+        dict.  This is O(1) per call instead of O(V) where V is the number of
+        defined variables.
+
+        Returns ``(modified_string, True)`` if a substitution was made, or
+        ``(original_string, False)`` if no variable pattern matched.
+        """
+        if not isinstance(command_str, str):
+            return command_str, False
+        m = self._TOKEN_RX.search(command_str)
+        while m:
+            varname = m.group("varname").lower()
+            if varname in self._subs_dict:
+                sub = self._subs_dict[varname]
+                if sub is None:
+                    sub = ""
+                sub = str(sub)
+                if os.name != "posix":
+                    sub = sub.replace("\\", "\\\\")
+                quote = m.group("q")
+                if quote == "'":
+                    sub = sub.replace("'", "''")
+                elif quote == '"':
+                    sub = '"' + sub + '"'
+                return command_str[: m.start()] + sub + command_str[m.end() :], True
+            # Token found but variable not defined — skip it and keep searching.
+            m = self._TOKEN_RX.search(command_str, m.end())
+        return command_str, False
+
+    def substitute_all(self, any_text: str) -> tuple:
+        """Repeatedly apply :meth:`substitute` until no more substitutions remain.
+
+        Returns ``(fully_expanded_string, any_substitution_made)``.
+        """
+        subbed = True
+        any_subbed = False
+        while subbed:
+            any_text, subbed = self.substitute(any_text)
+            if subbed:
+                any_subbed = True
+        return any_text, any_subbed
+
+
+class LocalSubVarSet(SubVarSet):
+    """Substitution-variable pool restricted to ``~``-prefixed local variables."""
+
+    # A pool of local substitution variables.
+    # Only '~' is allowed as a prefix and MUST be present.
+    def __init__(self) -> None:
+        SubVarSet.__init__(self)
+        self.prefix_list = ["~"]
+
+    def compile_var_rx(self) -> None:
+        # Prefix is required, not optional.
+        self.var_rx_str = r"^[" + "".join(self.prefix_list) + r"]\w+$"
+        self.var_rx = re.compile(self.var_rx_str, re.I)
+
+
+class ScriptArgSubVarSet(SubVarSet):
+    """Substitution-variable pool restricted to ``#``-prefixed script arguments."""
+
+    # A pool of script argument names.
+    # Only '#' is allowed as a prefix and MUST be present.
+    def __init__(self) -> None:
+        SubVarSet.__init__(self)
+        self.prefix_list = ["#"]
+
+    def compile_var_rx(self) -> None:
+        # Prefix is required, not optional.
+        self.var_rx_str = r"^[" + "".join(self.prefix_list) + r"]\w+$"
+        self.var_rx = re.compile(self.var_rx_str, re.I)

execsql/types.py

@@ -39,6 +39,35 @@ from decimal import Decimal
 from execsql.exceptions import DataTypeError, DbTypeError
 from execsql.utils.numeric import leading_zero_num
 
+__all__ = [
+    "DataType",
+    "Tz",
+    "DT_TimestampTZ",
+    "DT_Timestamp",
+    "DT_Date",
+    "DT_Time",
+    "DT_Time_Oracle",
+    "DT_Boolean",
+    "DT_Integer",
+    "DT_Long",
+    "DT_Float",
+    "DT_Decimal",
+    "DT_Character",
+    "DT_Varchar",
+    "DT_Text",
+    "DT_Binary",
+    "DbType",
+    "dbt_postgres",
+    "dbt_sqlite",
+    "dbt_duckdb",
+    "dbt_sqlserver",
+    "dbt_access",
+    "dbt_dsn",
+    "dbt_mysql",
+    "dbt_firebird",
+    "dbt_oracle",
+]
+
 
 class DataType:
     data_type_name = None
@@ -88,8 +117,8 @@ class DataType:
             return data
         try:
             i = self.data_type(data)
-        except Exception:
-            raise DataTypeError(self.data_type_name, self._CONV_ERR % data)
+        except Exception as e:
+            raise DataTypeError(self.data_type_name, self._CONV_ERR % data) from e
         return i
 
 
@@ -354,8 +383,8 @@ class DT_Integer(DataType):
             raise DataTypeError(self.data_type_name, self._CONV_ERR % data)
         try:
             i = int(data)
-        except Exception:
-            raise DataTypeError(self.data_type_name, self._CONV_ERR % data)
+        except Exception as e:
+            raise DataTypeError(self.data_type_name, self._CONV_ERR % data) from e
         if leading_zero_num(data):
             raise DataTypeError(self.data_type_name, self._CONV_ERR % data)
         return i
@@ -390,8 +419,8 @@ class DT_Long(DataType):
             raise DataTypeError(self.data_type_name, self._CONV_ERR % data)
         try:
             i = int(data)
-        except Exception:
-            raise DataTypeError(self.data_type_name, self._CONV_ERR % data)
+        except Exception as e:
+            raise DataTypeError(self.data_type_name, self._CONV_ERR % data) from e
         return i
 
 
@@ -428,8 +457,8 @@ class DT_Float(DataType):
             raise DataTypeError(self.data_type_name, self._CONV_ERR % data)
         try:
             i = float(data)
-        except Exception:
-            raise DataTypeError(self.data_type_name, self._CONV_ERR % data)
+        except Exception as e:
+            raise DataTypeError(self.data_type_name, self._CONV_ERR % data) from e
         return i
 
 
@@ -464,8 +493,8 @@ class DT_Decimal(DataType):
                 raise DataTypeError(self.data_type_name, self._CONV_ERR % data)
             try:
                 dec = Decimal(data)
-            except Exception:
-                raise DataTypeError(self.data_type_name, self._CONV_ERR % data)
+            except Exception as e:
+                raise DataTypeError(self.data_type_name, self._CONV_ERR % data) from e
             self.set_scale_prec(dec)
             return dec
         raise DataTypeError(self.data_type_name, self._CONV_ERR % data)
@@ -493,8 +522,8 @@ class DT_Character(DataType):
         if not isinstance(data, str):
             try:
                 data = data_type(data)
-            except ValueError:
-                raise DataTypeError(self.data_type_name, self._CONV_ERR % data)
+            except ValueError as e:
+                raise DataTypeError(self.data_type_name, self._CONV_ERR % data) from e
             if len(data) > 255:
                 raise DataTypeError(self.data_type_name, self._CONV_ERR % data)
         return data
@@ -521,8 +550,8 @@ class DT_Varchar(DataType):
         if isinstance(data, str):
             try:
                 data = data_type(data)
-            except ValueError:
-                raise DataTypeError(self.data_type_name, self._CONV_ERR % data)
+            except ValueError as e:
+                raise DataTypeError(self.data_type_name, self._CONV_ERR % data) from e
             if len(data) > 255:
                 raise DataTypeError(self.data_type_name, self._CONV_ERR % data)
         return data
@@ -546,8 +575,8 @@ class DT_Text(DataType):
         if not isinstance(data, str):
             try:
                 data = data_type(data)
-            except ValueError:
-                raise DataTypeError(self.data_type_name, self._CONV_ERR % data)
+            except ValueError as e:
+                raise DataTypeError(self.data_type_name, self._CONV_ERR % data) from e
         return data
 
 
@@ -605,12 +634,12 @@ class DbType:
         # A convenience function to simplify access to data type names.
         try:
             return self.dialect[data_type][0]
-        except Exception:
+        except Exception as e:
             raise DbTypeError(
                 self.dbms_id,
                 data_type,
                 f"{self.dbms_id} DBMS type has no specification for data type {data_type.data_type_name}",
-            )
+            ) from e
 
     def quoted(self, dbms_object: str) -> str:
         if re.search(r"\W", dbms_object):
@@ -638,12 +667,12 @@ class DbType:
         data_type = self.spec_type(data_type)
         try:
             dts = self.dialect[data_type]
-        except Exception:
+        except Exception as e:
             raise DbTypeError(
                 self.dbms_id,
                 data_type,
                 f"{self.dbms_id} DBMS type has no specification for data type {data_type.data_type_name}",
-            )
+            ) from e
         if max_len and max_len > 0 and dts[1]:
             spec = f"{self.quoted(column_name)} {dts[0]}({max_len})"
         elif data_type.precspec and precision and scale:

execsql/utils/auth.py

@@ -29,6 +29,8 @@ import getpass
 
 import execsql.state as _state
 
+__all__ = ["get_password", "clear_stored_password", "password_from_keyring"]
+
 # Tracks whether the most recent get_password() call returned a keyring-stored value.
 _last_from_keyring: bool = False
 

execsql/utils/crypto.py

@@ -21,9 +21,13 @@ that use XOR against a fixed key table followed by base64 encoding.
 The monolith (line 2301) called this "SIMPLE ENCRYPTION".
 """
 
+import base64
+import itertools
 import random
 import uuid
 
+__all__ = ["Encrypt"]
+
 
 class Encrypt:
     """Reversible XOR-based obfuscation for configuration file passwords.
@@ -55,12 +59,6 @@ class Encrypt:
     def __repr__(self) -> str:
         return "Encrypt()"
 
-    def __init__(self) -> None:
-        global itertools
-        global base64
-        import itertools
-        import base64
-
     def xor(self, text: str, enckey: str) -> str:
         return "".join(chr(ord(t) ^ ord(k)) for t, k in zip(text, itertools.cycle(enckey)))
 

execsql/utils/datetime.py

@@ -16,6 +16,7 @@ import datetime
 import re
 from typing import Any
 
+__all__ = ["parse_datetime", "parse_datetimetz"]
 
 dt_fmts = collections.deque(
     (

execsql/utils/errors.py

@@ -25,6 +25,17 @@ from typing import Any
 import execsql.state as _state
 from execsql.exceptions import ErrInfo
 
+__all__ = [
+    "exception_info",
+    "exception_desc",
+    "exit_now",
+    "fatal_error",
+    "write_warning",
+    "file_size_date",
+    "chainfuncs",
+    "as_none",
+]
+
 
 def exception_info() -> tuple:
     # Returns the exception type, value, source file name, source line number, and source line text.

execsql/utils/fileio.py

@@ -37,6 +37,24 @@ from typing import Any
 
 from execsql.exceptions import ErrInfo
 
+__all__ = [
+    "make_export_dirs",
+    "check_dir",
+    "FileWriter",
+    "EncodedFile",
+    "Logger",
+    "TempFileMgr",
+    "list_encodings",
+    "filewriter_filestatus",
+    "filewriter_write",
+    "filewriter_open_as_new",
+    "filewriter_close",
+    "filewriter_close_all_after_write",
+    "filewriter_closeall",
+    "filewriter_shutdown",
+    "filewriter_end",
+]
+
 
 def make_export_dirs(outfile: str) -> None:
     if outfile.lower() != "stdout":
@@ -49,8 +67,8 @@ def make_export_dirs(outfile: str) -> None:
             except OSError as e:
                 if e.errno != errno.EEXIST:
                     raise ErrInfo("exception", exception_msg=emsg) from e
-            except Exception:
-                raise ErrInfo("exception", exception_msg=emsg)
+            except Exception as e:
+                raise ErrInfo("exception", exception_msg=emsg) from e
 
 
 def check_dir(filename: str) -> None:
@@ -265,14 +283,11 @@ class FileWriter(multiprocessing.Process):
         # is a command and the second is a tuple of arguments for the function indicated
         # by that command.
         while self.active:
-            command = None
-            argtuple = None
             try:
-                command, argtuple = self.input_queue.get_nowait()
+                command, argtuple = self.input_queue.get(timeout=0.1)
             except queue.Empty:
-                pass
-            if command is not None:
-                self.execvec[command](*argtuple)
+                continue
+            self.execvec[command](*argtuple)
 
 
 # Subprocess objects for asynchronous writing to text files.
@@ -539,6 +554,16 @@ class Logger:
         wmsg = f"status\t{self.run_id}\t{self.seq_no}\t{self._ts()}\twarning\t{msg or ''}\n"
         self.writelog(wmsg)
 
+    def log_sql_query(self, sql: str, db_name: str, line_no: int | None = None) -> None:
+        """Log an executed SQL statement for audit purposes."""
+        cleaned = sql.replace("\n", " ").replace("\t", " ")
+        if len(cleaned) > 2000:
+            cleaned = cleaned[:2000] + "..."
+        self.seq_no += 1
+        lno = line_no if line_no is not None else 0
+        wmsg = f"sql\t{self.run_id}\t{self.seq_no}\t{self._ts()}\t{db_name}\t{lno}\t{cleaned}\n"
+        self.writelog(wmsg)
+
     def log_user_msg(self, msg: str | None) -> None:
         msg = None if not msg else msg.replace("\n", "")
         if msg != "":

execsql/utils/gui.py

@@ -21,6 +21,52 @@ from __future__ import annotations
 import sys
 from typing import Any
 
+__all__ = [
+    # Constants
+    "GUI_HALT",
+    "GUI_MSG",
+    "GUI_PAUSE",
+    "GUI_DISPLAY",
+    "GUI_ENTRY",
+    "GUI_COMPARE",
+    "GUI_SELECTROWS",
+    "GUI_SELECTSUB",
+    "GUI_ACTION",
+    "GUI_MAP",
+    "GUI_OPENFILE",
+    "GUI_SAVEFILE",
+    "GUI_DIRECTORY",
+    "QUERY_CONSOLE",
+    "GUI_CREDENTIALS",
+    "GUI_CONNECT",
+    # Data-carrier classes
+    "GuiSpec",
+    "ConsoleUIError",
+    "ActionSpec",
+    "EntrySpec",
+    # Console lifecycle
+    "gui_console_isrunning",
+    "enable_gui",
+    "gui_console_on",
+    "gui_console_off",
+    "gui_console_hide",
+    "gui_console_show",
+    "gui_console_progress",
+    "gui_console_save",
+    "gui_console_status",
+    "gui_console_wait_user",
+    "gui_console_width",
+    "gui_console_height",
+    # Database connection GUI
+    "gui_connect",
+    "gui_credentials",
+    # Interactive prompts
+    "get_yn",
+    "get_yn_win",
+    "pause",
+    "pause_win",
+]
+
 # ---------------------------------------------------------------------------
 # GUI command constants — used to identify request types in the GUI queue.
 # ---------------------------------------------------------------------------

execsql/utils/mail.py

@@ -11,11 +11,18 @@ metacommand and the halt/cancel email-notification hooks.
 """
 
 import re
+import smtplib
+from email import encoders
+from email.mime.base import MIMEBase
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
 from pathlib import Path
 
 import execsql.state as _state
 from execsql.exceptions import ErrInfo
 
+__all__ = ["MailSpec", "Mailer"]
+
 
 class Mailer:
     def __repr__(self) -> str:
@@ -26,17 +33,6 @@ class Mailer:
             self.smtpconn.quit()
 
     def __init__(self) -> None:
-        global smtplib
-        global MIMEMultipart
-        global MIMEText
-        global MIMEBase
-        global encoders
-        import smtplib
-        from email.mime.multipart import MIMEMultipart
-        from email.mime.text import MIMEText
-        from email.mime.base import MIMEBase
-        from email import encoders
-
         conf = _state.conf
         if conf.smtp_host is None:
             raise ErrInfo(type="error", other_msg="Can't send email; the email host is not configured.")
@@ -69,12 +65,6 @@ class Mailer:
         content_filename: str | None = None,
         attach_filename: str | None = None,
     ) -> None:
-        global smtplib
-        global MIMEMultipart
-        global MIMEText
-        global MIMEBase
-        global encoders
-
         conf = _state.conf
         if conf.email_format == "html":
             msg = MIMEMultipart("alternative")

execsql/utils/numeric.py

@@ -15,6 +15,8 @@ Provides:
 import re
 from typing import Any
 
+__all__ = ["as_numeric", "leading_zero_num"]
+
 
 def leading_zero_num(dataval: Any) -> bool:
     # Returns True if the data value is potentially a number but has a leading zero