execsql2 2.21.1__py3-none-any.whl → 2.22.0__py3-none-any.whl

execsql/api.py

@@ -35,7 +35,7 @@ import io
 import os
 import time
 from pathlib import Path
-from typing import Any
+from typing import Any, cast
 
 from execsql.cli.dsn import _parse_connection_string
 from execsql.config import ConfigData, StatObj, WriteHooks
@@ -170,6 +170,7 @@ class _LibraryConfig:
         self.log_datavars = False
         self.show_progress = False
         self.max_log_size_mb = 0
+        self.system_cmd_timeout = 0.0
 
         # Data handling
         self.boolean_int = True
@@ -334,6 +335,8 @@ def run(
     halt_on_error: bool = True,
     new_db: bool = False,
     allow_system_cmd: bool = True,
+    allow_rm_file: bool = True,
+    allow_serve: bool = True,
 ) -> ScriptResult:
     """Execute a SQL script and return the result.
 
@@ -359,6 +362,13 @@ def run(
             disabled and will raise an error if encountered. Matches the
             ``--no-system-cmd`` CLI flag and the ``allow_system_cmd``
             config option.
+        allow_rm_file: If ``False``, the RM_FILE metacommand is disabled
+            and will raise an error if encountered. Matches the
+            ``--no-rm-file`` CLI flag and the ``allow_rm_file`` config
+            option.
+        allow_serve: If ``False``, the SERVE metacommand is disabled and
+            will raise an error if encountered. Matches the ``--no-serve``
+            CLI flag and the ``allow_serve`` config option.
 
     Returns:
         A :class:`ScriptResult` with execution outcome, timing, errors,
@@ -391,6 +401,7 @@ def run(
         if script is not None:
             tree = parse_script(str(script), encoding=encoding)
         else:
+            assert sql is not None
             tree = parse_string(sql, source_name="<inline>")
     except ErrInfo as exc:
         return ScriptResult(
@@ -408,6 +419,7 @@ def run(
 
     # Configuration
     conf_overrides: dict[str, Any] = {"script_encoding": encoding}
+    conf: Any
     if config_file is not None:
         # Load a real ConfigData with the explicit config file
         from execsql.script.variables import SubVarSet
@@ -457,6 +469,8 @@ def run(
     ctx.status = StatObj()
     ctx.status.halt_on_err = halt_on_error
     conf.allow_system_cmd = allow_system_cmd
+    conf.allow_rm_file = allow_rm_file
+    conf.allow_serve = allow_serve
     ctx.conf = conf
 
     # Capture output to a buffer (suppress stdout/stderr)
@@ -465,7 +479,7 @@ def run(
     ctx.output = WriteHooks(stdout_buf.write, stderr_buf.write)
 
     # No log file for library use
-    ctx.exec_log = _NoOpLogger()
+    ctx.exec_log = cast(Any, _NoOpLogger())
 
     with active_context(ctx):
         # Initialize singletons (CounterVars, Timer, DatabasePool, BatchLevels, etc.)
@@ -482,6 +496,8 @@ def run(
         else:
             db = connection
 
+        assert db is not None
+        assert ctx.dbs is not None
         ctx.dbs.add("initial", db)
         ctx.subvars.add_substitution("$CURRENT_DBMS", db.type.dbms_id)
         ctx.subvars.add_substitution("$CURRENT_DATABASE", db.name())
@@ -530,6 +546,7 @@ def run(
         # Close connection if we own it
         if owns_connection:
             try:
+                assert ctx.dbs is not None
                 ctx.dbs.closeall()
             except Exception:
                 pass
@@ -572,7 +589,7 @@ def _last_source(ctx: RuntimeContext) -> str:
     """Get the source file from the last executed command."""
     lc = ctx.last_command
     if lc is not None and hasattr(lc, "source"):
-        return lc.source
+        return cast(str, lc.source)
     return "<unknown>"
 
 
@@ -580,7 +597,7 @@ def _last_line(ctx: RuntimeContext) -> int | None:
     """Get the line number from the last executed command."""
     lc = ctx.last_command
     if lc is not None and hasattr(lc, "line_no"):
-        return lc.line_no
+        return cast(int | None, lc.line_no)
     return None
 
 

execsql/cli/run.py

@@ -7,15 +7,15 @@ and drives the main execution loop.  Separated from argument parsing
 
 from __future__ import annotations
 
-import atexit
-from typing import Any
 import datetime
+import atexit
 import getpass
 import os
 import platform
 import sys
 import traceback
 from pathlib import Path
+from typing import TYPE_CHECKING, Any
 
 from execsql import __version__
 from execsql.cli.dsn import _parse_connection_string
@@ -26,6 +26,9 @@ from execsql.script import SubVarSet, current_script_line, substitute_vars
 from execsql.utils.fileio import FileWriter, Logger, filewriter_end
 from execsql.utils.gui import gui_connect, gui_console_isrunning, gui_console_off, gui_console_on, gui_console_wait_user
 
+if TYPE_CHECKING:
+    from execsql.script.ast import Script
+
 __all__ = ["_connect_initial_db", "_ping_db", "_print_dry_run", "_print_profile", "_run"]
 
 # Lint helper — imported lazily inside _run() to keep start-up cost low, but
@@ -38,7 +41,7 @@ from execsql.cli.lint import _print_lint_results  # noqa: F401 — re-export (us
 # ---------------------------------------------------------------------------
 
 
-def _print_dry_run(tree: object) -> None:
+def _print_dry_run(tree: Script | None) -> None:
     """Print the parsed AST for --dry-run mode.
 
     Walks the AST tree and prints each SQL statement and metacommand with
@@ -304,7 +307,7 @@ def _load_script(
     command: str | None,
     script_name: str | None,
     encoding: str,
-) -> Any:
+) -> Script | None:
     """Parse the SQL script (or inline command) into an AST.
 
     Returns the AST tree, or ``None`` if no script is provided.
@@ -316,6 +319,8 @@ def _load_script(
             command.replace("\\n", "\n").replace("\\t", "\t"),
             "<inline>",
         )
+    if script_name is None:
+        return None
     return parse_script(script_name, encoding=encoding)
 
 
@@ -515,7 +520,7 @@ def _setup_logging(
     }
     logger = Logger(
         script_name or "<inline>",
-        conf.db,
+        conf.db or "",
         conf.server,
         opts_dict,
         conf.user_logfile,
@@ -537,6 +542,7 @@ def _setup_logging(
         for n, repl in enumerate(sub_vars):
             var = f"$ARG_{n + 1}"
             subvars.add_substitution(var, repl)
+            logger.add_redaction_value(repl)
             # `-a` values are positional and opaque (no name to denylist
             # against). High-entropy secrets (sk-live-*, AKIA*, ghp_*,
             # JWTs) pass any substring/value heuristic, so log the
@@ -898,8 +904,9 @@ def _execute_script_textual_console(tree: Any, conf: ConfigData) -> None:
     dialog_queue = _ConsoleDialogQueue()
     _state.gui_manager_queue = dialog_queue
 
+    ctx = _state.get_context()
     app = ConsoleApp(
-        script_runner=lambda: execute(tree),
+        script_runner=lambda: execute(tree, ctx=ctx),
         dialog_queue=dialog_queue,
         wait_on_exit=conf.gui_wait_on_exit,
     )
@@ -945,6 +952,16 @@ def _execute_script_textual_console(tree: Any, conf: ConfigData) -> None:
 # ---------------------------------------------------------------------------
 
 
+def _required_connection_value(value: str | None, description: str) -> str:
+    """Return a required connection value or stop with the standard fatal path."""
+    if value is None:
+        from execsql.utils.errors import fatal_error
+
+        fatal_error(f"Configured database requires {description}, but none is provided.")
+        raise SystemExit(1)
+    return value
+
+
 def _connect_initial_db(conf: ConfigData):
     """Create and return the initial database object based on conf.db_type."""
     from execsql.db.factory import (
@@ -964,6 +981,7 @@ def _connect_initial_db(conf: ConfigData):
             from execsql.utils.errors import fatal_error
 
             fatal_error("Configured to run with MS-Access, but no Access file name is provided.")
+            raise SystemExit(1)
         return db_Access(
             conf.db_file,
             pw_needed=conf.passwd_prompt and conf.access_username is not None,
@@ -972,8 +990,8 @@ def _connect_initial_db(conf: ConfigData):
         )
     elif conf.db_type == "p":
         return db_Postgres(
-            conf.server,
-            conf.db,
+            _required_connection_value(conf.server, "a server name"),
+            _required_connection_value(conf.db, "a database name"),
             user=conf.username,
             pw_needed=conf.passwd_prompt,
             port=conf.port,
@@ -983,8 +1001,8 @@ def _connect_initial_db(conf: ConfigData):
         )
     elif conf.db_type == "s":
         return db_SqlServer(
-            conf.server,
-            conf.db,
+            _required_connection_value(conf.server, "a server name"),
+            _required_connection_value(conf.db, "a database name"),
             user=conf.username,
             pw_needed=conf.passwd_prompt,
             port=conf.port,
@@ -996,11 +1014,12 @@ def _connect_initial_db(conf: ConfigData):
             from execsql.utils.errors import fatal_error
 
             fatal_error("Configured to run with SQLite, but no SQLite file name is provided.")
+            raise SystemExit(1)
         return db_SQLite(conf.db_file, new_db=conf.new_db, encoding=conf.db_encoding)
     elif conf.db_type == "m":
         return db_MySQL(
-            conf.server,
-            conf.db,
+            _required_connection_value(conf.server, "a server name"),
+            _required_connection_value(conf.db, "a database name"),
             user=conf.username,
             pw_needed=conf.passwd_prompt,
             port=conf.port,
@@ -1012,11 +1031,12 @@ def _connect_initial_db(conf: ConfigData):
             from execsql.utils.errors import fatal_error
 
             fatal_error("Configured to run with DuckDB, but no DuckDB file name is provided.")
+            raise SystemExit(1)
         return db_DuckDB(conf.db_file, new_db=conf.new_db, encoding=conf.db_encoding)
     elif conf.db_type == "o":
         return db_Oracle(
-            conf.server,
-            conf.db,
+            _required_connection_value(conf.server, "a server name"),
+            _required_connection_value(conf.db, "a database name"),
             user=conf.username,
             pw_needed=conf.passwd_prompt,
             port=conf.port,
@@ -1025,8 +1045,8 @@ def _connect_initial_db(conf: ConfigData):
         )
     elif conf.db_type == "f":
         return db_Firebird(
-            conf.server,
-            conf.db,
+            _required_connection_value(conf.server, "a server name"),
+            _required_connection_value(conf.db, "a database name"),
             user=conf.username,
             pw_needed=conf.passwd_prompt,
             port=conf.port,
@@ -1035,7 +1055,7 @@ def _connect_initial_db(conf: ConfigData):
         )
     elif conf.db_type == "d":
         return db_Dsn(
-            conf.db,
+            _required_connection_value(conf.db, "a DSN name"),
             user=conf.username,
             pw_needed=conf.passwd_prompt,
             encoding=conf.db_encoding,

execsql/config.py

@@ -17,8 +17,10 @@ Provides three classes:
 
 import os
 import sys
+from collections.abc import Callable
 from configparser import ConfigParser
 from pathlib import Path
+from typing import Protocol
 
 from execsql.exceptions import ConfigError
 from execsql.utils.crypto import Encrypt
@@ -30,6 +32,12 @@ __all__ = [
 ]
 
 
+class _VariablePool(Protocol):
+    def substitute(self, strval: str) -> tuple[str, int]: ...
+    def var_name_ok(self, varname: str) -> bool: ...
+    def add_substitution(self, varname: str, strval: object) -> None: ...
+
+
 class StatObj:
     """Lightweight container for runtime status flags used by the metacommand engine.
 
@@ -315,6 +323,7 @@ class ConfigData:
         self._get_bool(cp, self._CONFIG_SECTION, "log_sql", "log_sql")
         self._get_int(cp, self._CONFIG_SECTION, "max_log_size_mb", "max_log_size_mb")
         self._get_bool(cp, self._CONFIG_SECTION, "allow_system_cmd", "allow_system_cmd")
+        self._get_float(cp, self._CONFIG_SECTION, "system_cmd_timeout", "system_cmd_timeout", min_val=0.0)
         self._get_bool(cp, self._CONFIG_SECTION, "allow_rm_file", "allow_rm_file")
         self._get_bool(cp, self._CONFIG_SECTION, "allow_serve", "allow_serve")
         self._get_str(cp, self._CONFIG_SECTION, "include_root", "include_root")
@@ -344,7 +353,7 @@ class ConfigData:
     def __init__(
         self,
         script_path: str,
-        variable_pool: object,
+        variable_pool: _VariablePool,
         *,
         config_file: str | None = None,
     ) -> None:
@@ -361,22 +370,23 @@ class ConfigData:
                 precedence over system, user, script, and working-directory
                 config files.
         """
-        self.db_type = "l"
-        self.server = None
-        self.port = None
-        self.db = None
-        self.username = None
-        self.access_username = None
+        self.db_type: str | None = "l"
+        self.server: str | None = None
+        self.port: int | None = None
+        self.db: str | None = None
+        self.username: str | None = None
+        self.access_username: str | None = None
+        self.db_password: str | None = None
         self.passwd_prompt = True
         self.use_keyring = True
-        self.db_file = None
+        self.db_file: str | None = None
         self.new_db = False
         self.user_logfile = False
-        self.db_encoding = None
+        self.db_encoding: str | None = None
         self.script_encoding = "utf8"
         self.output_encoding = "utf8"
         self.import_encoding = "utf8"
-        self.enc_err_disposition = None
+        self.enc_err_disposition: str | None = None
         self.import_common_cols_only = False
         self.max_int = 2147483647
         self.boolean_int = True
@@ -396,17 +406,17 @@ class ConfigData:
         self.scan_lines = 100
         self.hdf5_text_len = 1000
         self.write_warnings = False
-        self.write_prefix = None
-        self.write_suffix = None
-        self.gui_level = 0
+        self.write_prefix: str | None = None
+        self.write_suffix: str | None = None
+        self.gui_level: int = 0
         self.gui_framework = "tkinter"
         self.gui_wait_on_exit = False
         self.gui_wait_on_error_halt = False
         self.gui_console_height = 25
         self.gui_console_width = 100
         self.import_buffer = 32 * 1024
-        self.css_file = None
-        self.css_styles = None
+        self.css_file: str | None = None
+        self.css_styles: str | None = None
         self.make_export_dirs = False
         self.outfile_open_timeout = 600
         self.quote_all_text = False
@@ -414,7 +424,7 @@ class ConfigData:
         self.import_progress_interval = 0
         self.show_progress = False
         self.export_row_buffer = 1000
-        self.template_processor = None
+        self.template_processor: str | None = None
         self.tee_write_log = False
         self.log_datavars = True
         self.log_sql = False
@@ -432,6 +442,7 @@ class ConfigData:
         self.export_output_dir: str | None = None
         self.dao_flush_delay_secs = 5.0
         self.allow_system_cmd = True
+        self.system_cmd_timeout = 0.0
         # B05: path-containment controls. ``*_root`` keys, when set, force
         # the corresponding handler to confine resolved paths under the
         # named root and reject anything that escapes via ``..``,
@@ -618,9 +629,9 @@ class WriteHooks:
 
     def __init__(
         self,
-        standard_output_func: object = None,
-        error_output_func: object = None,
-        status_output_func: object = None,
+        standard_output_func: Callable[[str], object] | None = None,
+        error_output_func: Callable[[str], object] | None = None,
+        status_output_func: Callable[[str], object] | None = None,
     ) -> None:
         """Store optional hook callables; ``None`` means use the default stream.
 
@@ -648,16 +659,20 @@ class WriteHooks:
         self.write_func = None
         self.err_func = None
 
-    def redir_stdout(self, standard_output_func: object) -> None:
+    def redir_stdout(self, standard_output_func: Callable[[str], object]) -> None:
         """Replace the standard-output hook with the given callable."""
         self.write_func = standard_output_func
 
-    def redir_stderr(self, error_output_func: object, tee: bool = True) -> None:
+    def redir_stderr(self, error_output_func: Callable[[str], object], tee: bool = True) -> None:
         """Replace the error-output hook and optionally keep tee-to-stderr behaviour."""
         self.err_func = error_output_func
         self.tee_stderr = tee
 
-    def redir(self, standard_output_func: object, error_output_func: object) -> None:
+    def redir(
+        self,
+        standard_output_func: Callable[[str], object],
+        error_output_func: Callable[[str], object],
+    ) -> None:
         """Redirect both stdout and stderr hooks in one call."""
         self.redir_stdout(standard_output_func)
         self.redir_stderr(error_output_func)

execsql/data/execsql.conf.template

@@ -279,6 +279,12 @@
 # Values: Yes or No.  Default: Yes.
 #allow_system_cmd=Yes
 
+# Maximum seconds a foreground SYSTEM_CMD may run before execsql stops it.
+# Set to 0 for no timeout. SYSTEM_CMD ... CONTINUE is detached and is not
+# timeout-managed by this setting.
+# Value: A non-negative number of seconds.  Default: 0.
+#system_cmd_timeout=0
+
 # Whether to allow the RM_FILE metacommand (which deletes a file).
 # Set to No to prevent scripts from deleting files.
 # Also controllable via --no-rm-file CLI flag.

execsql/db/access.py

@@ -12,7 +12,7 @@ import datetime
 import re
 import time
 from pathlib import Path
-from typing import Any
+from typing import Any, cast
 
 from execsql.db.base import Database
 from execsql.exceptions import ErrInfo
@@ -69,7 +69,7 @@ class AccessDatabase(Database):
         # Encoding is only applicable to Jet < 4.0: non-accdb databases.
         self.encoding = encoding or "windows-1252"
         self.encode_commands = True
-        self.dao_conn = None
+        self.dao_conn: Any = None
         self.conn = None  # ODBC connection
         self.paramstr = "?"
         self.dt_cast = dict(self.dt_cast)  # Copy the lazy-initialized default before overriding.
@@ -253,6 +253,7 @@ class AccessDatabase(Database):
             else:
                 self.dao_flush_check()
                 with self._cursor() as curs:
+                    encoded_sql: Any
                     if self.jet4:
                         encoded_sql = str(sql)
                     else:
@@ -398,7 +399,7 @@ class AccessDatabase(Database):
         tablename = self.type.quoted(tablename)
         self.execute(f"drop table {tablename};")
 
-    def as_datetime(self, val: Any) -> datetime.datetime | None:
+    def as_datetime(self, val: Any) -> datetime.datetime | datetime.date | datetime.time | None:
         """Convert a value to a datetime object suitable for Access."""
         from execsql.types import DT_Timestamp, DT_Date, DT_Time, DataTypeError
 
@@ -414,7 +415,7 @@ class AccessDatabase(Database):
                     v = DT_Date().from_data(val)
                 except DataTypeError:
                     # If this generates an exception, let it go up to get caught.
-                    v = DT_Time().from_data(val)
+                    v = cast(datetime.time, DT_Time().from_data(val))
                     n = datetime.datetime.now()
                     v = datetime.datetime(
                         n.year,
@@ -427,7 +428,7 @@ class AccessDatabase(Database):
                     )
             except Exception:
                 raise
-            return v
+            return cast(datetime.datetime, v)
 
     def int_or_bool(self, val: Any) -> int | None:
         """Convert a value to an integer, recognizing Access boolean values."""

execsql/db/base.py

@@ -67,6 +67,19 @@ class Database(ABC):
     ``_state.dbs.current()`` rather than constructing adapters directly.
     """
 
+    type: Any
+    server_name: Any
+    db_name: Any
+    user: Any
+    need_passwd: bool | None
+    password: str | None
+    port: int | None
+    encoding: Any
+    encode_commands: bool
+    paramstr: str
+    conn: Any
+    autocommit: bool
+
     _dt_cast: dict[type, Callable] | None = None
 
     @property
@@ -90,7 +103,7 @@ class Database(ABC):
         encoding: str | None = None,
     ) -> None:
         """Initialize common connection attributes for a database backend."""
-        self.type = None
+        self.type: Any = None
         self.server_name = server_name
         self.db_name = db_name
         self.user = user_name
@@ -697,12 +710,14 @@ class Database(ABC):
                 )
             import_cols = csv_cols
 
+        tablespec_cache: Any = None
+
         def get_ts() -> Any:
-            if not get_ts.tablespec:
-                get_ts.tablespec = csv_file_obj.data_table_def()
-            return get_ts.tablespec
+            nonlocal tablespec_cache
+            if not tablespec_cache:
+                tablespec_cache = csv_file_obj.data_table_def()
+            return tablespec_cache
 
-        get_ts.tablespec = None
         f = csv_file_obj.reader()
         next(f)
         self.populate_table(schema_name, table_name, f, import_cols, get_ts)
@@ -777,14 +792,17 @@ class DatabasePool:
 
     def current(self) -> Database:
         """Return the currently active ``Database`` object."""
+        assert self.current_db is not None
         return self.pool[self.current_db]
 
     def current_alias(self) -> str:
         """Return the alias string for the currently active database."""
+        assert self.current_db is not None
         return self.current_db
 
     def initial(self) -> Database:
         """Return the first ``Database`` that was added to the pool."""
+        assert self.initial_db is not None
         return self.pool[self.initial_db]
 
     def aliased_as(self, db_alias: str) -> Database:

execsql/db/dsn.py

@@ -86,6 +86,8 @@ class DsnDatabase(Database):
             # supplied credentials cannot inject additional attributes.
             parts = [f"DSN={_odbc_quote(self.db_name)}"]
             if self.need_passwd:
+                assert self.user is not None
+                assert self.password is not None
                 parts.append(f"UID={_odbc_quote(self.user)}")
                 parts.append(f"PWD={_odbc_quote(self.password)}")
             connstr = ";".join(parts) + ";"

execsql/db/duckdb.py

@@ -73,7 +73,7 @@ class DuckDBDatabase(Database):
                 self.rollback()
                 raise
 
-    def view_exists(self, view_name: str) -> bool:
+    def view_exists(self, view_name: str, schema_name: str | None = None) -> bool:
         """Return True if the named view exists in the DuckDB database."""
         # DuckDB information_schema has no 'views' table; views are listed in 'tables'
         return self.table_exists(view_name)

execsql/db/mysql.py

@@ -8,7 +8,7 @@ servers via ``pymysql``.  Corresponds to ``-t m`` on the CLI.
 """
 
 import re
-from typing import Any
+from typing import Any, cast
 
 from execsql.db.base import Database
 from execsql.exceptions import ErrInfo
@@ -105,7 +105,7 @@ class MySQLDatabase(Database):
         """
         cached = getattr(self, "_cached_lctn", None)
         if cached is not None:
-            return cached
+            return cast(int, cached)
         try:
             _, rows = self.select_data("SELECT @@lower_case_table_names;")
             value = int(rows[0][0]) if rows else 0
@@ -114,10 +114,8 @@ class MySQLDatabase(Database):
         self._cached_lctn = value
         return value
 
-    def _fold_identifier(self, name: str | None) -> str | None:
+    def _fold_identifier(self, name: str) -> str:
         """Lowercase *name* when the server is case-insensitive (LCTN 1/2)."""
-        if name is None:
-            return None
         return name.lower() if self._lower_case_table_names() in (1, 2) else name
 
     # NB: schema_exists is overridden below to return False unconditionally
@@ -127,7 +125,7 @@ class MySQLDatabase(Database):
     def table_exists(self, table_name: str, schema_name: str | None = None) -> bool:
         return super().table_exists(
             self._fold_identifier(table_name),
-            self._fold_identifier(schema_name),
+            self._fold_identifier(schema_name) if schema_name is not None else None,
         )
 
     def column_exists(
@@ -139,13 +137,13 @@ class MySQLDatabase(Database):
         return super().column_exists(
             self._fold_identifier(table_name),
             self._fold_identifier(column_name),
-            self._fold_identifier(schema_name),
+            self._fold_identifier(schema_name) if schema_name is not None else None,
         )
 
     def view_exists(self, view_name: str, schema_name: str | None = None) -> bool:
         return super().view_exists(
             self._fold_identifier(view_name),
-            self._fold_identifier(schema_name),
+            self._fold_identifier(schema_name) if schema_name is not None else None,
         )
 
     def open_db(self) -> None:

execsql/db/sqlite.py

@@ -130,7 +130,7 @@ class SQLiteDatabase(Database):
                 ) from e
             return [d[0] for d in curs.description]
 
-    def view_exists(self, view_name: str) -> bool:
+    def view_exists(self, view_name: str, schema_name: str | None = None) -> bool:
         """Return True if the named view exists in the SQLite database."""
         # Match case-insensitively — see table_exists().
         with self._cursor() as curs: