execsql2 2.2.1__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

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":

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

execsql/utils/regex.py

@@ -14,6 +14,15 @@ dispatch regexes at module load time:
 
 import os
 
+__all__ = [
+    "ins_rxs",
+    "ins_quoted_rx",
+    "ins_schema_rxs",
+    "ins_table_rxs",
+    "ins_table_list_rxs",
+    "ins_fn_rxs",
+]
+
 
 def ins_rxs(rx_list: tuple, fragment1: object, fragment2: object) -> tuple:
     # Returns a tuple of all strings consisting of elements of the 'rx_list' tuple

execsql/utils/strings.py

@@ -23,6 +23,22 @@ identifiers:
 
 import re
 
+__all__ = [
+    "clean_word",
+    "clean_words",
+    "trim_word",
+    "trim_words",
+    "fold_word",
+    "fold_words",
+    "dedup_words",
+    "is_doublequoted",
+    "unquoted",
+    "unquoted2",
+    "encodings_match",
+    "wo_quotes",
+    "get_subvarset",
+]
+
 
 def clean_word(word: str) -> str:
     # Trim leading and trailing spaces and replaces all non-alphanumeric characters with an underscore.

execsql/utils/timer.py

@@ -17,6 +17,8 @@ import time
 
 from execsql.exceptions import ExecSqlTimeoutError
 
+__all__ = ["Timer", "TimerHandler"]
+
 
 class TimerHandler:
     def __init__(self, maxtime: float) -> None:

execsql2-2.4.0.data/data/execsql2_extras/README.md

@@ -0,0 +1,65 @@
+# Templates for execsql
+
+Several types of templates are provided that may be useful in conjunction with execsql. These are:
+
+- **execsql.conf** — An annotated version of the configuration file that includes all configuration settings and notes on their usage.
+
+- **script_template.sql** — A framework for SQL scripts that make use of several execsql features. It includes sections for custom configuration settings, custom logfile creation, and reporting of unexpected script exits (through user cancellation or errors).
+
+- **config_settings.sqlite** and **example_config_prompt.sql** — A SQLite database containing specifications for all settings configurable with the CONFIG metacommand, in the form used by the PROMPT ENTRY_FORM metacommand, and a SQL script illustrating how this database can be used to prompt the user for some or all of the configuration settings. *execsql* version 1.63.0 or later is needed to use this script.
+
+## Functional Scripts for execsql
+
+These script files provide useful functionality that should be accessed by including these scripts in other SQL scripts and then calling the sub-scripts that they contain.
+
+### Upsert Scripts
+
+These scripts perform automated upsert operations on any tables of any database in a DBMS that supports the standard *information_schema* views. Currently that includes:
+
+- **PostgreSQL:** `pg_upsert.sql`
+- **MySQL/MariaDB:** `md_upsert.sql`
+- **SQL Server:** `ss_upsert.sql`
+
+These scripts perform the upsert operation by using standard SQL UPDATE and INSERT statements rather than DBMS-specific implementations of the SQL MERGE statement.
+
+Features of these upsert scripts include:
+
+- They can be applied to any table in any database without modification.
+- They can be applied to multiple tables simultaneously, and will perform the upsert operations in top-down order to maintain referential integrity among tables.
+- Prior to performing the upsert operation, they check for null values in the columns of each staging table that must be non-null in the corresponding base table.
+- Prior to performing the upsert operation, they check for duplicate primary key values in the staging tables.
+- Prior to performing the upsert operation, they check foreign keys against both base tables and any other appropriate staging tables.
+- They will not attempt to perform the upsert operation on any table if there are any violations of the non-null checks, primary key checks, or foreign key checks.
+- They produce a table that either a) summarizes the number of rows that violated each type of non-null and foreign-key check, or b) summarizes the number of rows updated and the number of rows inserted for each table.
+- Optionally, they will display all the changes to be made in a GUI interface, prompting the user to approve each update and insert operation.
+- Optionally, they will record all operations carried out in a custom log file; this log may include the SQL statements executed and the data values that were added or changed.
+- If an execsql console is active, they will use the console's status bar and progress bar to indicate the activity underway.
+
+Complete documentation is available at [Read The Docs (execsql-upsert)](https://execsql-upsert.readthedocs.io/en/latest/).
+
+### Table Comparison Scripts
+
+These scripts generate SQL that can be used to identify differences in the content of two tables with equivalent structure. These are specifically intended to be base and staging tables. Running the SQL provided by these scripts will provide different summaries of the types of changes that would be made to the base tables by upserting the staging tables.
+
+These scripts work with any tables of any database in a DBMS that supports the standard *information_schema* views. Currently that includes:
+
+- **PostgreSQL:** `pg_compare.sql`
+- **MySQL/MariaDB:** `md_compare.sql`
+- **SQL Server:** `ss_compare.sql`
+
+Complete documentation is available at [Read The Docs (execsql-compare)](https://execsql-compare.readthedocs.io/en/latest/).
+
+### Glossary Creation Scripts
+
+These scripts create a glossary of column names or other terms that can be exported to accompany a data summary. These scripts work with any tables of any database in a DBMS that supports the standard *information_schema* views. Currently that includes:
+
+- **PostgreSQL:** `pg_glossary.sql`
+- **MySQL/MariaDB:** `md_glossary.sql`
+- **SQL Server:** `ss_glossary.sql`
+
+Complete documentation is available at [Read The Docs (execsql-glossary)](https://execsql-compare.readthedocs.io/en/latest/).
+
+## Roadmap
+
+- [ ] Integrate documentation for [execsql-compare](https://execsql-compare.readthedocs.io/en/latest/) into the main execsql2 documentation site.
+- [ ] Integrate documentation for [execsql-upsert](https://execsql-upsert.readthedocs.io/en/latest/) into the main execsql2 documentation site.

{execsql2-2.2.1.data → execsql2-2.4.0.data}/data/execsql2_extras/execsql.conf

@@ -2,7 +2,7 @@
 #
 # PURPOSE
 #	Configuration file for execsql.py
-#	See http://execsql.osdn.io/configuration.html
+#	See https://execsql2.readthedocs.io/en/latest/configuration/
 #
 # AUTHORS
 #