execsql2 2.4.4__py3-none-any.whl → 2.5.0__py3-none-any.whl

execsql/parser.py

@@ -39,20 +39,26 @@ __all__ = [
 
 
 class SourceString:
+    """Cursor-based scanner over a raw string for token matching."""
+
     def __init__(self, source_string: str) -> None:
+        """Initialise the scanner at position zero of the given string."""
         self.str = source_string
         self.currpos = 0
 
     def eoi(self) -> bool:
+        """Return True if the entire source string has been consumed."""
         # Returns True or False indicating whether or not there is any of
         # the source string left to be consumed.
         return self.currpos >= len(self.str)
 
     def eat_whitespace(self) -> None:
+        """Advance the cursor past any whitespace at the current position."""
         while not self.eoi() and self.str[self.currpos] in [" ", "\t", "\n"]:
             self.currpos += 1
 
     def match_str(self, str: str) -> str | None:
+        """Match a string case-insensitively at the current position and advance."""
         # Tries to match the 'str' argument at the current position in the
         # source string.  Matching is case-insensitive.  If matching succeeds,
         # the matched string is returned and the internal pointer is incremented.
@@ -70,6 +76,7 @@ class SourceString:
                 return None
 
     def match_regex(self, regex: Any) -> dict | None:
+        """Match a compiled regex at the current position and return named groups."""
         # Tries to match the 'regex' argument at the current position in the
         # source string.  If it succeeds, a dictionary of all of the named
         # groups is returned, and the internal pointer is incremented.
@@ -85,6 +92,7 @@ class SourceString:
                 return None
 
     def match_metacommand(self, commandlist: Any) -> tuple | None:
+        """Match a metacommand from the command list at the current position."""
         # Tries to match text at the current position to any metacommand
         # in the specified commandlist.
         # If it succeeds, the return value is a tuple of the MetaCommand object
@@ -102,6 +110,7 @@ class SourceString:
                 return None
 
     def remainder(self) -> str:
+        """Return the unconsumed portion of the source string."""
         return self.str[self.currpos :]
 
 
@@ -109,10 +118,14 @@ class SourceString:
 
 
 class CondTokens:
+    """Integer constants for conditional-expression AST node types."""
+
     AND, OR, NOT, CONDITIONAL = range(4)
 
 
 class NumTokens:
+    """Integer constants for numeric-expression AST node types."""
+
     MUL, DIV, ADD, SUB, NUMBER = range(5)
 
 
@@ -120,7 +133,10 @@ class NumTokens:
 
 
 class CondAstNode(CondTokens):
+    """AST node for boolean expressions supporting AND, OR, NOT, and leaf conditionals."""
+
     def __init__(self, type: int, cond1: Any, cond2: Any) -> None:
+        """Create a conditional AST node with the given operator type and children."""
         # 'type' should be one of the constants AND, OR, NOT, CONDITIONAL.
         # For AND and OR types, 'cond1' and 'cond2' should be a subtree (a CondAstNode)
         # For NOT type, 'cond1' should be a CondAstNode and 'cond2' should be None
@@ -134,6 +150,7 @@ class CondAstNode(CondTokens):
             self.right = None
 
     def eval(self) -> bool:
+        """Evaluate this subtree and return a boolean result."""
         # Evaluates the subtrees and/or conditional value for this node,
         # returning True or False.
         if self.type == self.CONDITIONAL:
@@ -157,7 +174,10 @@ class CondAstNode(CondTokens):
 
 
 class NumericAstNode(NumTokens):
+    """AST node for arithmetic expressions supporting MUL, DIV, ADD, SUB, and NUMBER."""
+
     def __init__(self, type: int, value1: Any, value2: Any) -> None:
+        """Create a numeric AST node with the given operator type and operands."""
         # 'type' should be one of the constants MUL, DIV, ADD, SUB, OR NUMBER.
         # 'value1' and 'value2' should each be either a subtree (a
         # NumericAstNode) or (only 'value1' should be) a number.
@@ -169,6 +189,7 @@ class NumericAstNode(NumTokens):
             self.right = None
 
     def eval(self) -> Any:
+        """Evaluate this subtree and return a numeric result."""
         # Evaluates the subtrees and/or numeric value for this node,
         # returning a numeric value.
         if self.type == self.NUMBER:
@@ -190,12 +211,16 @@ class NumericAstNode(NumTokens):
 
 
 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."""
         self.condexpr = condexpr
         self.cond_expr = SourceString(condexpr)
 
     def match_not(self) -> int | None:
+        """Match a NOT operator and return its token type, or None."""
         # Try to match 'NOT' operator. If not found, return None
         m1 = self.cond_expr.match_str("NOT")
         if m1 is not None:
@@ -203,6 +228,7 @@ class CondParser(CondTokens):
         return None
 
     def match_andop(self) -> int | None:
+        """Match an AND operator and return its token type, or None."""
         # Try to match 'AND' operator. If not found, return None
         m1 = self.cond_expr.match_str("AND")
         if m1 is not None:
@@ -210,6 +236,7 @@ class CondParser(CondTokens):
         return None
 
     def match_orop(self) -> int | None:
+        """Match an OR operator and return its token type, or None."""
         # Try to match 'OR' operator. If not found, return None
         m1 = self.cond_expr.match_str("OR")
         if m1 is not None:
@@ -217,6 +244,7 @@ class CondParser(CondTokens):
         return None
 
     def factor(self) -> Any:
+        """Parse a factor: NOT, a parenthesised expression, or a metacommand leaf."""
         m1 = self.match_not()
         if m1 is not None:
             m1 = self.factor()
@@ -244,6 +272,7 @@ class CondParser(CondTokens):
                 )
 
     def term(self) -> Any:
+        """Parse a term: a factor optionally followed by AND and another term."""
         m1 = self.factor()
         andop = self.match_andop()
         if andop is not None:
@@ -253,6 +282,7 @@ class CondParser(CondTokens):
             return m1
 
     def expression(self) -> Any:
+        """Parse an expression: a term optionally followed by OR and another expression."""
         e1 = self.term()
         orop = self.match_orop()
         if orop is not None:
@@ -262,6 +292,7 @@ class CondParser(CondTokens):
             return e1
 
     def parse(self) -> Any:
+        """Parse the entire conditional expression and return the AST root."""
         exp = self.expression()
         if not self.cond_expr.eoi():
             raise CondParserError(
@@ -274,13 +305,17 @@ class CondParser(CondTokens):
 
 
 class NumericParser(NumTokens):
+    """Recursive-descent parser for arithmetic numeric expressions."""
+
     # Takes a numeric expression string
     def __init__(self, numexpr: str) -> None:
+        """Initialise the parser with the numeric expression string."""
         self.num_expr = SourceString(numexpr)
         self.rxint = re.compile(r"(?P<int_num>[+-]?[0-9]+)")
         self.rxfloat = re.compile(r"(?P<float_num>[+-]?(?:(?:[0-9]*\.[0-9]+)|(?:[0-9]+\.[0-9]*)))")
 
     def match_number(self) -> Any | None:
+        """Match a float or integer literal and return its numeric value, or None."""
         # Try to match a number in the source string.
         # Return it if matched, return None if unmatched.
         m1 = self.num_expr.match_regex(self.rxfloat)
@@ -293,6 +328,7 @@ class NumericParser(NumTokens):
         return None
 
     def match_mulop(self) -> int | None:
+        """Match a multiplication or division operator and return its token type, or None."""
         # Try to match a multiplication or division operator in the source string.
         # if found, return the matching operator type.  If not found, return None.
         m1 = self.num_expr.match_str("*")
@@ -305,6 +341,7 @@ class NumericParser(NumTokens):
         return None
 
     def match_addop(self) -> int | None:
+        """Match an addition or subtraction operator and return its token type, or None."""
         # Try to match an addition or subtraction operator in the source string.
         # if found, return the matching operator type.  If not found, return None.
         m1 = self.num_expr.match_str("+")
@@ -317,6 +354,7 @@ class NumericParser(NumTokens):
         return None
 
     def factor(self) -> Any:
+        """Parse a numeric factor: a number literal or a parenthesised expression."""
         # Parses a factor out of the source string and returns the
         # AST node that is created.
         m1 = self.match_number()
@@ -338,6 +376,7 @@ class NumericParser(NumTokens):
                 )
 
     def term(self) -> Any:
+        """Parse a term: a factor optionally followed by MUL/DIV and another term."""
         # Parses a term out of the source string and returns the
         # AST node that is created.
         m1 = self.factor()
@@ -349,6 +388,7 @@ class NumericParser(NumTokens):
             return m1
 
     def expression(self) -> Any:
+        """Parse an expression: a term optionally followed by ADD/SUB and another expression."""
         # Parses an expression out of the source string and returns the
         # AST node that is created.
         e1 = self.term()
@@ -362,6 +402,7 @@ class NumericParser(NumTokens):
             return e1
 
     def parse(self) -> Any:
+        """Parse the entire numeric expression and return the AST root."""
         exp = self.expression()
         if not self.num_expr.eoi():
             raise NumericParserError(

execsql/script/control.py

@@ -12,6 +12,8 @@ from typing import Any
 
 from execsql.exceptions import ErrInfo
 
+__all__ = ["BatchLevels", "IfItem", "IfLevels"]
+
 
 # ---------------------------------------------------------------------------
 # BatchLevels

execsql/script/engine.py

@@ -40,6 +40,25 @@ from execsql.script.variables import LocalSubVarSet, ScriptArgSubVarSet, SubVarS
 from execsql.utils.errors import exception_desc
 from execsql.utils.fileio import EncodedFile
 
+__all__ = [
+    "MetaCommand",
+    "MetaCommandList",
+    "SqlStmt",
+    "MetacommandStmt",
+    "ScriptCmd",
+    "CommandList",
+    "CommandListWhileLoop",
+    "CommandListUntilLoop",
+    "ScriptFile",
+    "ScriptExecSpec",
+    "set_system_vars",
+    "substitute_vars",
+    "runscripts",
+    "current_script_line",
+    "read_sqlfile",
+    "read_sqlstring",
+]
+
 
 # ---------------------------------------------------------------------------
 # MetaCommand / MetaCommandList

execsql/script/variables.py

@@ -15,6 +15,8 @@ from typing import Any
 
 from execsql.exceptions import ErrInfo
 
+__all__ = ["CounterVars", "SubVarSet", "LocalSubVarSet", "ScriptArgSubVarSet"]
+
 
 # ---------------------------------------------------------------------------
 # CounterVars
@@ -184,15 +186,17 @@ class SubVarSet:
         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."""
+        """Return a new SubVarSet with this object's variables merged with other_subvars.
+
+        Copies dictionaries and pre-compiled patterns directly instead of
+        re-adding variables one at a time, avoiding O(V) regex recompilation.
+        """
         if other_subvars is not None:
             newsubs = SubVarSet()
-            newsubs._subs_dict = dict(self._subs_dict)
-            newsubs._compiled_patterns = dict(self._compiled_patterns)
+            newsubs._subs_dict = {**self._subs_dict, **other_subvars._subs_dict}
+            newsubs._compiled_patterns = {**self._compiled_patterns, **other_subvars._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
 

execsql/state.py

@@ -55,6 +55,58 @@ if TYPE_CHECKING:
     from execsql.utils.mail import MailSpec
     from execsql.utils.timer import Timer
 
+__all__ = [
+    # Configuration / encoding
+    "conf",
+    "logfile_encoding",
+    # Runtime state
+    "last_command",
+    "upass",
+    "varlike",
+    "err_halt_writespec",
+    "err_halt_email",
+    "err_halt_exec",
+    "cancel_halt_writespec",
+    "cancel_halt_mailspec",
+    "cancel_halt_exec",
+    "commandliststack",
+    "savedscripts",
+    "loopcommandstack",
+    "compiling_loop",
+    "endloop_rx",
+    "loop_rx",
+    "loop_nest_level",
+    "cmds_run",
+    "defer_rx",
+    "stringtypes",
+    "exec_log",
+    "subvars",
+    "status",
+    # Lazy singletons
+    "if_stack",
+    "counters",
+    "timer",
+    "output",
+    "dbs",
+    "tempfiles",
+    "export_metadata",
+    "metacommandlist",
+    "conditionallist",
+    "filewriter",
+    "gui_console",
+    "gui_manager_queue",
+    "gui_manager_thread",
+    # Version
+    "primary_vno",
+    "secondary_vno",
+    "tertiary_vno",
+    # Functions
+    "xcmd_test",
+    "endloop",
+    "reset",
+    "initialize",
+]
+
 # ---------------------------------------------------------------------------
 # Configuration / encoding
 # ---------------------------------------------------------------------------

execsql/types.py

@@ -70,6 +70,8 @@ __all__ = [
 
 
 class DataType:
+    """Abstract base class for all data-type matchers used during column inference."""
+
     data_type_name = None
     data_type = None
     lenspec = False  # Is a length specification required for a (SQL) declaration of this data type?
@@ -83,9 +85,11 @@ class DataType:
         return f"DataType({self.data_type_name!r}, {self.data_type!r})"
 
     def is_null(self, data: object) -> bool:
+        """Return True if the data value is None."""
         return data is None
 
     def matches(self, data: object) -> bool:
+        """Return True if the non-null data value could be of this data type."""
         # Returns T/F indicating whether the given data value could be of this data type.
         # The data value should be non-null.
         if self.is_null(data):
@@ -93,6 +97,7 @@ class DataType:
         return self._is_match(data)
 
     def from_data(self, data: object) -> object:
+        """Coerce the data value to this type or raise DataTypeError."""
         # Returns the data value coerced to this type, or raises a DataTypeError exception.
         # The data value should be non-null.
         if self.is_null(data):
@@ -123,16 +128,22 @@ class DataType:
 
 
 class Tz(datetime.tzinfo):
+    """Fixed-offset timezone implementation for timestamp-with-timezone parsing."""
+
     def __init__(self, sign: int, hr: int, min: int) -> None:
+        """Store the UTC offset as sign, hours, and minutes."""
         self.sign = sign
         self.hr = hr
         self.min = min
 
     def utcoffset(self, dt: object) -> datetime.timedelta:
+        """Return the UTC offset as a timedelta."""
         return self.sign * datetime.timedelta(hours=self.hr, minutes=self.min)
 
 
 class DT_TimestampTZ(DataType):
+    """Timezone-aware timestamp data type."""
+
     data_type_name = "timestamptz"
     data_type = datetime.datetime
     # There is no distinct Python type corresponding to a timestamptz, so the data_type
@@ -166,6 +177,8 @@ class DT_TimestampTZ(DataType):
 
 
 class DT_Timestamp(DataType):
+    """Naive timestamp (datetime without timezone) data type."""
+
     data_type_name = "timestamp"
     data_type = datetime.datetime
 
@@ -207,10 +220,13 @@ date_fmts = collections.deque(
 
 
 class DT_Date(DataType):
+    """Calendar date data type with multiple format recognition."""
+
     data_type_name = "date"
     data_type = datetime.date
 
     def __init__(self) -> None:
+        """Initialise the date format deque for adaptive format matching."""
         self._date_fmts = collections.deque(date_fmts)
 
     def __repr__(self) -> str:
@@ -239,6 +255,8 @@ class DT_Date(DataType):
 
 
 class DT_Time(DataType):
+    """Time-of-day data type with multiple format recognition."""
+
     data_type_name = "time"
     data_type = datetime.time
     time_fmts = (
@@ -288,6 +306,8 @@ class DT_Time_Oracle(DT_Time):
 
 
 class DT_Boolean(DataType):
+    """Boolean data type recognising word and integer true/false forms."""
+
     data_type_name = "boolean"
     data_type = bool
 
@@ -295,6 +315,7 @@ class DT_Boolean(DataType):
         return "DT_Boolean()"
 
     def set_bool_matches(self) -> None:
+        """Populate the true/false match tuples from the current configuration."""
         import execsql.state as _state
 
         conf = _state.conf
@@ -342,6 +363,8 @@ class DT_Boolean(DataType):
 
 
 class DT_Integer(DataType):
+    """Small integer data type bounded by the configured max_int."""
+
     data_type_name = "integer"
     data_type = int
 
@@ -391,6 +414,8 @@ class DT_Integer(DataType):
 
 
 class DT_Long(DataType):
+    """Large integer (bigint) data type using Python int."""
+
     data_type_name = "long"
     data_type = int  # In Python 3, long is just int
 
@@ -425,6 +450,8 @@ class DT_Long(DataType):
 
 
 class DT_Float(DataType):
+    """IEEE double-precision floating-point data type."""
+
     data_type_name = "float"
     data_type = float
 
@@ -463,6 +490,8 @@ class DT_Float(DataType):
 
 
 class DT_Decimal(DataType):
+    """Exact decimal data type tracking precision and scale."""
+
     data_type_name = "decimal"
     data_type = Decimal
     precspec = True
@@ -471,6 +500,7 @@ class DT_Decimal(DataType):
         return "DT_Decimal()"
 
     def set_scale_prec(self, dec: Decimal) -> None:
+        """Compute and store the precision and scale from a Decimal value."""
         # 'dec' should be Decimal.
         x = dec.as_tuple()
         digits = len(x.digits)
@@ -501,6 +531,8 @@ class DT_Decimal(DataType):
 
 
 class DT_Character(DataType):
+    """Fixed-length string data type (up to 255 characters)."""
+
     data_type_name = "character"
     lenspec = True
 
@@ -530,6 +562,8 @@ class DT_Character(DataType):
 
 
 class DT_Varchar(DataType):
+    """Variable-length string data type (up to 255 characters)."""
+
     data_type_name = "varchar"
     lenspec = True
     varlen = True
@@ -558,6 +592,8 @@ class DT_Varchar(DataType):
 
 
 class DT_Text(DataType):
+    """Unbounded text string data type."""
+
     data_type_name = "character"
 
     def __repr__(self) -> str:
@@ -581,6 +617,8 @@ class DT_Text(DataType):
 
 
 class DT_Binary(DataType):
+    """Binary byte-array data type."""
+
     data_type_name = "binary"
     data_type = bytearray
 
@@ -589,7 +627,10 @@ class DT_Binary(DataType):
 
 
 class DbType:
+    """Map Python DataType subclasses to DBMS-specific SQL type names."""
+
     def __init__(self, DBMS_id: str, db_obj_quotes: str = '""') -> None:
+        """Initialise a DBMS dialect with its identifier and quoting characters."""
         # The DBMS_id is the name by which this DBMS is identified.
         # db_obj_quotechars is a string of two characters that are the opening and closing quotes
         # for identifiers (schema, table, and column names) that need to be quoted.
@@ -621,6 +662,7 @@ class DbType:
         precision: object = None,
         scale: object = None,
     ) -> None:
+        """Register a DBMS-specific SQL type name for a DataType class."""
         # data_type is a DataType class object.
         # dbms_name is the DBMS-specific name for this data type.
         # length_required indicates whether length information is required.
@@ -631,6 +673,7 @@ class DbType:
         self.dialect[data_type] = (dbms_name, length_required, casting_name, conv_mod_fn, precision, scale)
 
     def datatype_name(self, data_type: object) -> str:
+        """Return the DBMS-specific SQL type name for the given DataType class."""
         # A convenience function to simplify access to data type names.
         try:
             return self.dialect[data_type][0]
@@ -642,6 +685,7 @@ class DbType:
             ) from e
 
     def quoted(self, dbms_object: str) -> str:
+        """Quote a database identifier if it contains non-word characters."""
         if re.search(r"\W", dbms_object):
             if self.quotechars[0] == self.quotechars[1] and self.quotechars[0] in dbms_object:
                 dbms_object = dbms_object.replace(self.quotechars[0], self.quotechars[0] + self.quotechars[0])
@@ -649,6 +693,7 @@ class DbType:
         return dbms_object
 
     def spec_type(self, data_type: object) -> object:
+        """Return the translated data type, or the original if no translation exists."""
         # Returns a translated data type or the original if there is no translation.
         if data_type in self.dt_xlate:
             return self.dt_xlate[data_type]
@@ -663,6 +708,7 @@ class DbType:
         precision: object = None,
         scale: object = None,
     ) -> str:
+        """Return a column specification string suitable for a CREATE TABLE statement."""
         # Returns a column specification as it would be used in a CREATE TABLE statement.
         data_type = self.spec_type(data_type)
         try:

{execsql2-2.4.4.dist-info → execsql2-2.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.4.4
+Version: 2.5.0
 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: Repository, https://github.com/geocoug/execsql
 Project-URL: Issues, https://github.com/geocoug/execsql/issues
@@ -107,7 +107,7 @@ Description-Content-Type: text/markdown
 
 > [!NOTE]
 > **This is a maintained fork of [execsql](https://execsql.readthedocs.io/).**
-> The original monolith has been fully refactored into a modular package with 2,000+ tests.
+> The original monolith has been fully refactored into a modular package.
 > The CLI and configuration are backwards-compatible with upstream v1.130.1.
 > Report issues at [github.com/geocoug/execsql/issues](https://github.com/geocoug/execsql/issues).
 
@@ -215,8 +215,12 @@ execsql script.sql                          # read connection from config file
 | `-m`                                | List metacommands and exit                                      |
 | `-n`                                | Create a new SQLite or PostgreSQL database if it does not exist |
 | `-v {0,1,2,3}`                      | GUI level (0=none, 1=password, 2=selection, 3=full)             |
-| `--gui-framework {tkinter,textual}` | GUI framework for interactive prompts                           |
 | `-w`                                | Skip password prompt when a username is supplied                |
+| `--dsn URL`                         | Connection string (e.g. `postgresql://user:pass@host/db`)       |
+| `--dry-run`                         | Parse the script and report commands without executing          |
+| `--progress`                        | Show a progress bar for long-running IMPORT operations          |
+| `--dump-keywords`                   | Print metacommand keywords as JSON and exit                     |
+| `--gui-framework {tkinter,textual}` | GUI framework for interactive prompts                           |
 
 Run `execsql --help` for the full option list, or `execsql -m` to list all metacommands.
 
@@ -283,7 +287,30 @@ execsql-format --in-place scripts/
 execsql-format --check scripts/
 ```
 
-See the [formatter documentation](https://execsql2.readthedocs.io/en/latest/formatter/) for all options.
+`execsql-format` is also available as a [pre-commit](https://pre-commit.com/) hook:
+
+```yaml
+repos:
+  - repo: https://github.com/geocoug/execsql
+    rev: v2.4.4
+    hooks:
+      - id: execsql-format
+        args: [--in-place]
+```
+
+See the [formatter documentation](https://execsql2.readthedocs.io/en/latest/guides/formatter/) for all options.
+
+# VS Code Syntax Highlighting
+
+A VS Code extension for execsql syntax highlighting is included in [`extras/vscode-execsql`](extras/vscode-execsql). It injects a TextMate grammar into `.sql` files, adding highlighting for `-- !x!` metacommand markers, keywords (control flow, block, action, directive), variable substitutions (`!!var!!`, `!{var}!`), built-in functions, export formats, and config options — all layered on top of standard SQL highlighting.
+
+To install, symlink the extension folder into your VS Code extensions directory:
+
+```sh
+ln -s /path/to/execsql/extras/vscode-execsql ~/.vscode/extensions/execsql-syntax
+```
+
+See the [extension README](extras/vscode-execsql/README.md) for Windows instructions, color customization, and troubleshooting.
 
 # Templates