execsql2 2.16.18__py3-none-any.whl → 2.17.2__py3-none-any.whl

execsql/db/base.py

@@ -46,7 +46,26 @@ def _default_dt_cast() -> dict[type, Callable]:
 
 
 class Database(ABC):
-    """Abstract base class for all database connections."""
+    """Abstract base class for every DBMS adapter.
+
+    Concrete adapters in sibling modules (``postgres.py``, ``sqlite.py``,
+    ``duckdb.py``, etc.) subclass ``Database`` and override the two
+    abstract methods (:meth:`open_db`, :meth:`exec_cmd`) plus any
+    introspection or data-handling method whose default ANSI
+    ``information_schema`` implementation does not work for the target
+    DBMS (``schema_exists``, ``table_exists``, ``column_exists``,
+    ``table_columns``, ``view_exists``, ``role_exists``, ``drop_table``,
+    ``populate_table``).
+
+    The base class provides shared implementations of :meth:`execute`,
+    :meth:`select_data`, :meth:`select_rowsource`, :meth:`select_rowdict`,
+    :meth:`commit`, :meth:`rollback`, :meth:`quote_identifier`, and
+    :meth:`paramsubs` that work for any DB-API 2.0 driver.
+
+    Adapter instances are owned by :class:`DatabasePool` (accessed at
+    runtime via ``_state.dbs``); metacommand handlers call
+    ``_state.dbs.current()`` rather than constructing adapters directly.
+    """
 
     _dt_cast: dict[type, Callable] | None = None
 
@@ -125,7 +144,7 @@ class Database(ABC):
     def close(self) -> None:
         """Close the database connection, logging a warning if autocommit is off."""
         if self.conn:
-            if not self.autocommit:
+            if not self.autocommit and _state.exec_log is not None:
                 _state.exec_log.log_status_info(
                     f"Closing {self.name()} when AUTOCOMMIT is OFF; transactions may not have completed.",
                 )
@@ -412,7 +431,14 @@ class Database(ABC):
         return len(rows) > 0
 
     def role_exists(self, rolename: str) -> bool:
-        """Return ``True`` if *rolename* exists; subclasses must override this."""
+        """Return ``True`` if *rolename* exists in this database.
+
+        The default implementation raises :class:`~execsql.exceptions.DatabaseNotImplementedError`;
+        adapters for DBMSes that have a concept of roles (PostgreSQL,
+        SQL Server, etc.) override this to query the appropriate
+        catalog. Calling ``ROLE_EXISTS()`` from a script against a DBMS
+        without role support will surface the raised error.
+        """
         from execsql.exceptions import DatabaseNotImplementedError
 
         raise DatabaseNotImplementedError(self.name(), "role_exists")
@@ -682,9 +708,10 @@ class DatabasePool:
                     type="error",
                     other_msg="You may not reassign the alias of a database that is currently used in a batch.",
                 )
-            _state.exec_log.log_status_info(
-                f"Reassigning database alias '{db_alias}' from {self.pool[db_alias].name()} to {db_obj.name()}.",
-            )
+            if _state.exec_log is not None:
+                _state.exec_log.log_status_info(
+                    f"Reassigning database alias '{db_alias}' from {self.pool[db_alias].name()} to {db_obj.name()}.",
+                )
             self.pool[db_alias].close()
         self.pool[db_alias] = db_obj
         # Refresh static system vars so $DB_NAME, $DB_USER, etc. reflect the new connection.

execsql/db/firebird.py

@@ -191,10 +191,12 @@ class FirebirdDatabase(Database):
 
     def view_exists(self, view_name: str, schema_name: str | None = None) -> bool:
         """Return True if the named view exists in the Firebird database."""
+        # Firebird folds unquoted identifiers to uppercase in the system catalog;
+        # match the case of the table_exists() handling above.
         sql = "select distinct rdb$view_name from rdb$view_relations where rdb$view_name = ?;"
         with self._cursor() as curs:
             try:
-                curs.execute(sql, (view_name,))
+                curs.execute(sql, (view_name.upper(),))
             except ErrInfo:
                 raise
             except Exception as e:

execsql/db/mysql.py

@@ -220,9 +220,10 @@ class MySQLDatabase(Database):
                     import_sql = f"{import_sql} optionally enclosed by '{safe_quote}'"
             import_sql = f"{import_sql} ignore {1 + csv_file_obj.junk_header_lines} lines"
             import_sql = f"{import_sql} ({input_col_list});"
-            _state.exec_log.log_status_info(
-                f"IMPORTing {csv_file_obj.csvfname} using the DBMS' fast file reading routine",
-            )
+            if _state.exec_log is not None:
+                _state.exec_log.log_status_info(
+                    f"IMPORTing {csv_file_obj.csvfname} using the DBMS' fast file reading routine",
+                )
             self.execute(import_sql)
         else:
             data_indexes = [csv_file_cols.index(col) for col in import_cols]

execsql/db/oracle.py

@@ -142,11 +142,13 @@ class OracleDatabase(Database):
 
     def table_exists(self, table_name: str, schema_name: str | None = None) -> bool:
         """Return True if the named table exists in the Oracle database."""
-        params = {"tname": table_name}
+        # Oracle folds unquoted identifiers to uppercase; normalise so a lookup
+        # of "mytable" finds the catalog entry for MYTABLE.
+        params = {"tname": table_name.upper()}
         owner_clause = ""
         if schema_name:
             owner_clause = " and owner = :owner"
-            params["owner"] = schema_name
+            params["owner"] = schema_name.upper()
         sql = f"select table_name from sys.all_tables where table_name = :tname{owner_clause}"
         with self._cursor() as curs:
             try:
@@ -171,11 +173,12 @@ class OracleDatabase(Database):
         schema_name: str | None = None,
     ) -> bool:
         """Return True if the named column exists in the given Oracle table."""
-        params = {"tname": table_name, "cname": column_name}
+        # Oracle folds unquoted identifiers to uppercase.
+        params = {"tname": table_name.upper(), "cname": column_name.upper()}
         owner_clause = ""
         if schema_name:
             owner_clause = " and owner = :owner"
-            params["owner"] = schema_name
+            params["owner"] = schema_name.upper()
         sql = f"select column_name from all_tab_columns where table_name=:tname{owner_clause} and column_name=:cname"
         with self._cursor() as curs:
             try:
@@ -195,11 +198,12 @@ class OracleDatabase(Database):
 
     def table_columns(self, table_name: str, schema_name: str | None = None) -> list[str]:
         """Return a list of column names for the given Oracle table."""
-        params = {"tname": table_name}
+        # Oracle folds unquoted identifiers to uppercase.
+        params = {"tname": table_name.upper()}
         owner_clause = ""
         if schema_name:
             owner_clause = " and owner=:owner"
-            params["owner"] = schema_name
+            params["owner"] = schema_name.upper()
         sql = f"select column_name from all_tab_columns where table_name=:tname{owner_clause} order by column_id"
         with self._cursor() as curs:
             try:
@@ -219,11 +223,12 @@ class OracleDatabase(Database):
 
     def view_exists(self, view_name: str, schema_name: str | None = None) -> bool:
         """Return True if the named view exists in the Oracle database."""
-        params = {"vname": view_name}
+        # Oracle folds unquoted identifiers to uppercase.
+        params = {"vname": view_name.upper()}
         owner_clause = ""
         if schema_name:
             owner_clause = " and owner = :owner"
-            params["owner"] = schema_name
+            params["owner"] = schema_name.upper()
         sql = f"select view_name from sys.all_views where view_name = :vname{owner_clause}"
         with self._cursor() as curs:
             try:
@@ -242,13 +247,30 @@ class OracleDatabase(Database):
         return len(rows) > 0
 
     def role_exists(self, rolename: str) -> bool:
-        """Return True if the named role or user exists in the Oracle database."""
+        """Return True if the named role or user exists in the Oracle database.
+
+        ``dba_roles`` is restricted to DBA accounts and would raise
+        ``ORA-00942: table or view does not exist`` for non-DBA users; we
+        try it first and fall back to ``session_roles`` (always readable
+        for the current session) if the catalog isn't accessible.
+        """
+        # Oracle folds unquoted identifiers to uppercase in the catalog.
+        params = {"rname": rolename.upper()}
         with self._cursor() as curs:
-            curs.execute(
-                "select role from dba_roles where role = :rname union "
-                " select username from all_users where username = :rname",
-                {"rname": rolename},
-            )
+            try:
+                curs.execute(
+                    "select role from dba_roles where role = :rname union "
+                    " select username from all_users where username = :rname",
+                    params,
+                )
+            except Exception:
+                # Non-DBA fallback: enumerate session roles + users we can see.
+                self.rollback()
+                curs.execute(
+                    "select role from session_roles where role = :rname union "
+                    " select username from all_users where username = :rname",
+                    params,
+                )
             rows = curs.fetchall()
         return len(rows) > 0
 

execsql/db/postgres.py

@@ -3,9 +3,10 @@ from __future__ import annotations
 """
 PostgreSQL database adapter for execsql.
 
-Implements :class:`PostgresDatabase`, the most feature-complete adapter,
-supporting schema-qualified tables, server-side ``COPY``, ``LISTEN``/
-``NOTIFY``, and ``psycopg2``-level connection options.  Corresponds to
+Implements :class:`PostgresDatabase`. Uses ``psycopg2`` for the
+connection, supports schema-qualified tables, server-side ``COPY`` for
+fast IMPORT, ``CREATE DATABASE`` when ``new_db=True``, ``ROLE_EXISTS``,
+and the ``PG_VACUUM`` metacommand (``vacuum()`` method). Corresponds to
 ``-t p`` on the CLI.
 """
 
@@ -339,9 +340,10 @@ class PostgresDatabase(Database):
                 safe_quote = csv_file_obj.quotechar.replace("'", "''")
                 copy_cmd = copy_cmd + f", quote '{safe_quote}'"
             copy_cmd = copy_cmd + ")"
-            _state.exec_log.log_status_info(
-                f"IMPORTing {csv_file_obj.csvfname} using Postgres' fast file reading routine",
-            )
+            if _state.exec_log is not None:
+                _state.exec_log.log_status_info(
+                    f"IMPORTing {csv_file_obj.csvfname} using Postgres' fast file reading routine",
+                )
             with self._cursor() as curs:
                 try:
                     curs.copy_expert(copy_cmd, rf, _state.conf.import_buffer)

execsql/db/sqlite.py

@@ -82,8 +82,10 @@ class SQLiteDatabase(Database):
 
     def table_exists(self, table_name: str, schema_name: str | None = None) -> bool:
         """Return True if the named table exists in the SQLite database."""
+        # SQLite stores names as-created; match case-insensitively so a lookup
+        # of "mytable" finds the catalog entry for MyTable.
         with self._cursor() as curs:
-            sql = "select name from sqlite_master where type='table' and name=?;"
+            sql = "select name from sqlite_master where type='table' and lower(name)=lower(?);"
             try:
                 curs.execute(sql, (table_name,))
             except ErrInfo:
@@ -130,8 +132,9 @@ class SQLiteDatabase(Database):
 
     def view_exists(self, view_name: str) -> bool:
         """Return True if the named view exists in the SQLite database."""
+        # Match case-insensitively — see table_exists().
         with self._cursor() as curs:
-            sql = "select name from sqlite_master where type='view' and name=?;"
+            sql = "select name from sqlite_master where type='view' and lower(name)=lower(?);"
             try:
                 curs.execute(sql, (view_name,))
             except ErrInfo:

execsql/db/sqlserver.py

@@ -103,13 +103,15 @@ class SqlServerDatabase(Database):
                     try:
                         self.conn = pyodbc.connect(connstr)
                     except Exception:
-                        _state.exec_log.log_status_info(
-                            f"Could not connect using: {re.sub(r'Pwd=[^;]*', 'Pwd=***', connstr)}",
-                        )
+                        if _state.exec_log is not None:
+                            _state.exec_log.log_status_info(
+                                f"Could not connect using: {re.sub(r'Pwd=[^;]*', 'Pwd=***', connstr)}",
+                            )
                     else:
-                        _state.exec_log.log_status_info(
-                            f"Connected using: {re.sub(r'Pwd=[^;]*', 'Pwd=***', connstr)}",
-                        )
+                        if _state.exec_log is not None:
+                            _state.exec_log.log_status_info(
+                                f"Connected using: {re.sub(r'Pwd=[^;]*', 'Pwd=***', connstr)}",
+                            )
                         return True
                 return False
 

execsql/debug/repl.py

@@ -345,12 +345,13 @@ def _print_all_vars(*, include_env: bool = False) -> None:
         _write("  (no substitution variables defined)\n\n")
         return
     items = list(subvars.substitutions)  # list of (name, value) tuples
-    # Include ~local and #param variables from the current stack frame.
-    if _state.commandliststack:
-        frame = _state.commandliststack[-1]
-        items.extend(frame.localvars.substitutions)
-        if frame.paramvals is not None:
-            items.extend(frame.paramvals.substitutions)
+    # Include ~local and #param variables from the current scope frame.
+    localvars = _state.current_localvars()
+    if localvars is not None:
+        items.extend(localvars.substitutions)
+    paramvals = _state.current_paramvals()
+    if paramvals is not None:
+        items.extend(paramvals.substitutions)
     if not items:
         _write("  (no substitution variables defined)\n\n")
         return
@@ -415,12 +416,15 @@ def _print_var(varname: str) -> None:
     value = subvars.varvalue(varname)
     if value is None and len(varname) > 1 and varname[0] in "$&@#~":
         value = subvars.varvalue(varname[1:])
-    # Check stack frame for ~local and #param variables.
-    if value is None and _state.commandliststack:
-        frame = _state.commandliststack[-1]
-        value = frame.localvars.varvalue(varname)
-        if value is None and frame.paramvals is not None:
-            value = frame.paramvals.varvalue(varname)
+    # Check current scope frame for ~local and #param variables.
+    if value is None:
+        localvars = _state.current_localvars()
+        if localvars is not None:
+            value = localvars.varvalue(varname)
+        if value is None:
+            paramvals = _state.current_paramvals()
+            if paramvals is not None:
+                value = paramvals.varvalue(varname)
     if value is None:
         _write(f"  {_c(_CYAN, varname)}: {_c(_DIM, '(undefined)')}\n")
     else:
@@ -428,17 +432,47 @@ def _print_var(varname: str) -> None:
 
 
 def _print_stack() -> None:
-    """Print the current command-list stack (script name, line number, depth)."""
-    stack = _state.commandliststack
+    """Print the unified AST execution stack.
+
+    Shows every nesting construct the executor is currently inside:
+    ``<main>`` script, ``EXECUTE SCRIPT`` calls, ``INCLUDE``'d files,
+    ``IF``/``ELSEIF``/``ELSE`` branches, ``LOOP`` iterations (with iteration
+    count), and ``BATCH`` blocks. Each frame shows source file and line.
+    """
+    stack = _state.ast_exec_stack
     if not stack:
-        _write("  (command list stack is empty)\n\n")
+        _write("  (execution stack is empty)\n\n")
         return
     _write_rule(f" {_c(_BOLD + _YELLOW, 'Stack')} ")
     _write(f"  {_c(_DIM, 'depth:')} {len(stack)}\n")
-    for depth, cmdlist in enumerate(stack):
-        listname = getattr(cmdlist, "listname", "<unknown>")
-        cmdptr = getattr(cmdlist, "cmdptr", 0)
-        _write(f"  [{depth}] {listname}  {_c(_DIM, f'(cursor at index {cmdptr})')}\n")
+    for depth, frame in enumerate(stack):
+        kind_label = frame.kind.upper().replace("LOOP_", "LOOP ")
+        # Build the right-hand description per kind
+        if frame.kind in ("if", "elseif"):
+            desc = f"{kind_label}  {frame.label}"
+        elif frame.kind == "else":
+            desc = kind_label
+        elif frame.kind in ("loop_while", "loop_until"):
+            desc = f"{kind_label}  {frame.label}  {_c(_DIM, f'iter={frame.iteration}')}"
+        elif frame.kind == "script":
+            params = ""
+            if frame.params:
+                params = "(" + ", ".join(f"{k}={v!r}" for k, v in frame.params.items()) + ")"
+            iter_suffix = f"  {_c(_DIM, f'iter={frame.iteration}')}" if frame.iteration else ""
+            desc = f"SCRIPT {frame.label}{params}{iter_suffix}"
+        elif frame.kind == "include":
+            desc = f"INCLUDE {frame.label}"
+        elif frame.kind == "batch":
+            desc = "BATCH"
+        elif frame.kind == "main":
+            desc = frame.label or "<main>"
+        else:
+            desc = f"{kind_label}  {frame.label}"
+        src = ""
+        if frame.source:
+            src_name = frame.source.rsplit("/", 1)[-1].rsplit("\\", 1)[-1]
+            src = _c(_DIM, f"  {src_name}:{frame.line}" if frame.line else f"  {src_name}")
+        _write(f"  [{depth}] {desc}{src}\n")
     _write("\n")
 
 
@@ -510,8 +544,12 @@ def _set_var(varname: str, value: str) -> None:
     if subvars is None:
         _write("  Error: substitution variables are not initialised.\n")
         return
-    if varname.startswith("~") and _state.commandliststack:
-        _state.commandliststack[-1].localvars.add_substitution(varname, value)
+    if varname.startswith("~"):
+        localvars = _state.current_localvars()
+        if localvars is not None:
+            localvars.add_substitution(varname, value)
+        else:
+            subvars.add_substitution(varname, value)
     else:
         subvars.add_substitution(varname, value)
     _write(f"  {_c(_CYAN, varname)} {_c(_DIM, '=')} {value}\n")

execsql/exceptions.py

@@ -1,12 +1,12 @@
 from __future__ import annotations
 
 """
-Custom exception hierarchy for execsql.
+Custom exception hierarchy for execsql (internal use).
 
-All domain-specific exceptions are defined here so that callers can import
-from a single location.  Notable exceptions:
+All domain-specific exceptions are defined here so that internal callers
+can import from a single location. Notable exceptions:
 
-- :class:`ExecSqlError` — common base for all single-message execsql exceptions.
+- :class:`ExecSqlError` — common base for all internal execsql exceptions.
 - :class:`ConfigError` — invalid or missing ``execsql.conf`` values.
 - :class:`ErrInfo` — rich exception carrying type, command text, exception
   message, and script location; used as both a raised exception and an error
@@ -19,6 +19,15 @@ from a single location.  Notable exceptions:
   — spreadsheet I/O failures.
 - :class:`ConsoleUIError` — GUI console errors.
 - :class:`CondParserError` / :class:`NumericParserError` — parser failures.
+
+Note:
+    The ``execsql`` top-level package re-exports a *separate*
+    :class:`execsql.api.ExecSqlError` for library-API consumers. That
+    class is unrelated to this internal hierarchy; it is raised only by
+    :meth:`execsql.api.ScriptResult.raise_on_error`. Library callers
+    using ``from execsql import ExecSqlError`` get the public one;
+    internal modules using ``from execsql.exceptions import ExecSqlError``
+    get the hierarchy base defined here.
 """
 
 __all__ = [
@@ -173,6 +182,8 @@ class ErrInfo(ExecSqlError):
 
 
 class DataTypeError(ExecSqlError):
+    """Raised when a value cannot be cast to or rendered as a given DataType."""
+
     def __init__(self, data_type_name: str, error_msg: str) -> None:
         self.data_type_name = data_type_name or "Unspecified data type"
         self.error_msg = error_msg or "Unspecified error"
@@ -186,6 +197,8 @@ class DataTypeError(ExecSqlError):
 
 
 class DbTypeError(ExecSqlError):
+    """Raised when a DataType has no DBMS-specific mapping for the active database."""
+
     def __init__(self, dbms_id: str, data_type: object, error_msg: str) -> None:
         self.dbms_id = dbms_id
         self.data_type = data_type
@@ -211,6 +224,8 @@ class DataTableError(ExecSqlError):
 
 
 class DatabaseNotImplementedError(ExecSqlError):
+    """Raised when a Database subclass does not implement a required method for the current DBMS."""
+
     def __init__(self, db_name: str, method: str) -> None:
         self.db_name = db_name
         self.method = method

execsql/exporters/base.py

@@ -147,8 +147,9 @@ class WriteSpec:
         if self.repeatable or not self.written:
             self.written = True
             msg = self.msg
-            if _state.commandliststack:
-                msg, _ = _state.commandliststack[-1].localvars.substitute_all(msg)
+            localvars = _state.current_localvars()
+            if localvars is not None:
+                msg, _ = localvars.substitute_all(msg)
             msg, _ = subvars.substitute_all(msg)
             if self.outfile:
                 from execsql.utils.fileio import EncodedFile

execsql/exporters/delimited.py

@@ -8,9 +8,8 @@ Provides:
 - :class:`LineDelimiter` — configurable line-ending constant.
 - :class:`DelimitedWriter` / :class:`CsvWriter` — low-level writers used
   by the export logic.
-- :class:`CsvFile` — full delimited-file reader/writer (≈622 lines in the
-  original monolith) supporting custom delimiters, quoting, encoding, and
-  ZIP output.
+- :class:`CsvFile` — full delimited-file reader/writer supporting custom
+  delimiters, quoting, encoding, and ZIP output.
 - :func:`write_delimited_file` — writes a query result set to a
   CSV/TSV/delimited text file.
 """

execsql/exporters/feather.py

@@ -5,9 +5,9 @@ from execsql.exceptions import ErrInfo
 Apache Feather and HDF5 export for execsql.
 
 Provides :func:`write_query_to_feather` (Apache Arrow Feather v2 format
-via ``pyarrow``) and :func:`write_query_to_hdf5` (HDF5 via ``pandas``
-and ``tables``).  Used by ``EXPORT … FORMAT feather`` and
-``FORMAT hdf5``.  Both packages are optional dependencies.
+via ``polars``) and :func:`write_query_to_hdf5` (HDF5 via the ``tables``
+library). Used by ``EXPORT … FORMAT feather`` and ``FORMAT hdf5``.
+Both back-ends are optional; install via ``execsql2[formats]``.
 """
 
 from typing import Any

execsql/exporters/ods.py

@@ -6,7 +6,7 @@ ODS (OpenDocument Spreadsheet) export for execsql.
 Provides :func:`write_query_to_ods` (single-sheet export),
 :func:`write_queries_to_ods` (multi-sheet export), and :class:`OdsFile`
 (wrapper around ``odfpy`` for writing ``.ods`` files).  Requires the
-``odfpy`` package (``execsql2[ods]``).
+``odfpy`` package (``execsql2[formats]``).
 """
 
 import datetime

execsql/exporters/xls.py

@@ -2,11 +2,19 @@ from __future__ import annotations
 from execsql.types import DT_TimestampTZ
 
 """
-XLS and XLSX spreadsheet export for execsql.
+Spreadsheet file wrappers used by the EXPORT and IMPORT metacommands.
 
-Provides :class:`XlsFile` (writes ``.xls`` via ``xlwt``) and
-:class:`XlsxFile` (writes ``.xlsx`` via ``openpyxl``), both used by the
-EXPORT metacommand.  Requires the ``execsql2[excel]`` extras.
+Despite living in the ``exporters`` package, both classes here are
+mixed-use:
+
+- :class:`XlsFile` — **read-only** wrapper around ``xlrd`` for importing
+  legacy ``.xls`` spreadsheets. (Writing ``.xls`` is not supported; new
+  exports should target ``.xlsx``.)
+- :class:`XlsxFile` — read/write wrapper around ``openpyxl`` for
+  ``.xlsx`` spreadsheets.
+
+Both back-ends are optional dependencies; install via
+``execsql2[formats]``.
 """
 
 import datetime

execsql/exporters/xlsx.py

@@ -5,7 +5,7 @@ XLSX (Excel Open XML) export for execsql.
 
 Provides :func:`write_query_to_xlsx` (single-sheet export) and
 :func:`write_queries_to_xlsx` (multi-sheet export).  Requires the
-``openpyxl`` package (``execsql2[excel]``).
+``openpyxl`` package (``execsql2[formats]``).
 """
 
 import datetime