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

execsql/config.py

@@ -23,12 +23,25 @@ from pathlib import Path
 from execsql.exceptions import ConfigError
 from execsql.utils.crypto import Encrypt
 
+__all__ = [
+    "StatObj",
+    "ConfigData",
+    "WriteHooks",
+]
+
 
 class StatObj:
+    """Lightweight container for runtime status flags used by the metacommand engine.
+
+    Tracks error conditions, halt-on-error policy, dialog cancellation state,
+    and the current batch nesting level.
+    """
+
     # A generic object to maintain status indicators.  These status
     # indicators are primarily those used in the metacommand
     # environment rather than for the program as a whole.
     def __init__(self) -> None:
+        """Initialise all status flags to their default (non-error) values."""
         self.halt_on_err = True
         self.sql_error = False
         self.halt_on_metacommand_err = True
@@ -42,6 +55,13 @@ class StatObj:
 
 
 class ConfigData:
+    """Reads and merges ``execsql.conf`` INI files, exposing all options as attributes.
+
+    Searches system, user, script-directory, and working-directory locations
+    (in that order) and applies each file's settings cumulatively so that
+    later files override earlier ones.
+    """
+
     config_file_name = "execsql.conf"
     _CONNECT_SECTION = "connect"
     _ENCODING_SECTION = "encoding"
@@ -55,6 +75,15 @@ class ConfigData:
     _INCLUDE_OPT_SECTION = "include_optional"
 
     def __init__(self, script_path: str, variable_pool: object) -> None:
+        """Load and merge all discoverable execsql.conf files for the given script path.
+
+        Args:
+            script_path: Directory of the running script; used to locate a
+                script-adjacent ``execsql.conf``.
+            variable_pool: Substitution-variable registry used to expand
+                ``config_file`` path values and to populate ``[variables]``
+                sections.
+        """
         self.db_type = "a"
         self.server = None
         self.port = None
@@ -106,10 +135,12 @@ class ConfigData:
         self.quote_all_text = False
         self.import_row_buffer = 1000
         self.import_progress_interval = 0
+        self.show_progress = False
         self.export_row_buffer = 1000
         self.template_processor = None
         self.tee_write_log = False
         self.log_datavars = True
+        self.log_sql = False
         self.max_log_size_mb = 0
         self.smtp_host = None
         self.smtp_port = None
@@ -143,7 +174,7 @@ class ConfigData:
                 cp.read(configfile)
                 if cp.has_option(self._CONNECT_SECTION, "db_type"):
                     t = cp.get(self._CONNECT_SECTION, "db_type").lower()
-                    if len(t) != 1 or t not in ("a", "l", "p", "f", "m", "o", "s", "d"):
+                    if len(t) != 1 or t not in ("a", "d", "f", "k", "l", "m", "o", "p", "s"):
                         raise ConfigError(f"Invalid database type: {t}")
                     self.db_type = t
                 if cp.has_option(self._CONNECT_SECTION, "server"):
@@ -291,6 +322,11 @@ class ConfigData:
                         self.import_progress_interval = cp.getint(self._INPUT_SECTION, "import_progress_interval")
                     except Exception as e:
                         raise ConfigError("Invalid argument for import_progress_interval.") from e
+                if cp.has_option(self._INPUT_SECTION, "show_progress"):
+                    try:
+                        self.show_progress = cp.getboolean(self._INPUT_SECTION, "show_progress")
+                    except Exception as e:
+                        raise ConfigError("Invalid argument for show_progress.") from e
                 if cp.has_option(self._INPUT_SECTION, "access_use_numeric"):
                     try:
                         self.access_use_numeric = cp.getboolean(self._INPUT_SECTION, "access_use_numeric")
@@ -466,6 +502,11 @@ class ConfigData:
                         self.log_datavars = cp.getboolean(self._CONFIG_SECTION, "log_datavars")
                     except Exception as e:
                         raise ConfigError("Invalid argument to log_datavars setting.") from e
+                if cp.has_option(self._CONFIG_SECTION, "log_sql"):
+                    try:
+                        self.log_sql = cp.getboolean(self._CONFIG_SECTION, "log_sql")
+                    except Exception as e:
+                        raise ConfigError("Invalid argument to log_sql setting.") from e
                 if cp.has_option(self._CONFIG_SECTION, "max_log_size_mb"):
                     try:
                         self.max_log_size_mb = cp.getint(self._CONFIG_SECTION, "max_log_size_mb")
@@ -535,6 +576,12 @@ class ConfigData:
 
 
 class WriteHooks:
+    """Thin wrapper around stdout/stderr that supports GUI or test-harness redirection.
+
+    Each output hook is a callable that accepts a single string.  When a hook
+    is ``None`` the default ``sys.stdout`` or ``sys.stderr`` is used.
+    """
+
     def __repr__(self) -> str:
         return f"WriteHooks({self.write_func!r}, {self.err_func!r}, {self.status_func!r})"
 
@@ -544,6 +591,16 @@ class WriteHooks:
         error_output_func: object = None,
         status_output_func: object = None,
     ) -> None:
+        """Store optional hook callables; ``None`` means use the default stream.
+
+        Args:
+            standard_output_func: Callable to receive standard-output text, or
+                ``None`` to use ``sys.stdout``.
+            error_output_func: Callable to receive error-output text, or
+                ``None`` to use ``sys.stderr``.
+            status_output_func: Callable to receive status-line text, or
+                ``None`` to suppress.
+        """
         # Arguments should be functions that take a single string and
         # write it to the desired destination.  Both stdout and stderr can be hooked.
         # If a hook function is not specified, the default of stdout or stderr will
@@ -555,22 +612,27 @@ class WriteHooks:
         self.tee_stderr = True
 
     def reset(self) -> None:
+        """Reset both output hooks to ``None``, restoring stdout/stderr behaviour."""
         # Resets output to stdout and stderr.
         self.write_func = None
         self.err_func = None
 
     def redir_stdout(self, standard_output_func: 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:
+        """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:
+        """Redirect both stdout and stderr hooks in one call."""
         self.redir_stdout(standard_output_func)
         self.redir_stderr(error_output_func)
 
     def write(self, strval: str) -> None:
+        """Write a string to the standard-output hook, or to sys.stdout if unset."""
         if self.write_func:
             self.write_func(strval)
         else:
@@ -578,6 +640,7 @@ class WriteHooks:
             sys.stdout.flush()
 
     def write_err(self, strval: str) -> None:
+        """Write an error string to the error-output hook, or to sys.stderr if unset."""
         if strval[-1] != "\n":
             strval += "\n"
         if self.err_func:
@@ -590,5 +653,6 @@ class WriteHooks:
             sys.stderr.flush()
 
     def write_status(self, strval: str) -> None:
+        """Forward a status string to the status hook if one is registered."""
         if self.status_func:
             self.status_func(strval)

execsql/db/access.py

@@ -20,8 +20,12 @@ from execsql.utils.errors import exception_desc, fatal_error
 from execsql.utils.auth import clear_stored_password, get_password, password_from_keyring
 import execsql.state as _state
 
+__all__ = ["AccessDatabase"]
+
 
 class AccessDatabase(Database):
+    """MS Access adapter connecting to .mdb/.accdb files via DAO (win32com) with pyodbc fallback."""
+
     # Regex for the 'create temporary view' SQL extension
     temp_rx = re.compile(
         r"^\s*create(?:\s+or\s+replace)?(\s+temp(?:orary)?)?\s+(?:(view|query))\s+(\w+) as\s+",
@@ -68,7 +72,7 @@ class AccessDatabase(Database):
         self.dao_conn = None
         self.conn = None  # ODBC connection
         self.paramstr = "?"
-        self.dt_cast = dict(Database.dt_cast)
+        self.dt_cast = dict(self.dt_cast)  # Copy the lazy-initialized default before overriding.
         self.dt_cast[datetime.date] = self.as_datetime
         self.dt_cast[datetime.datetime] = self.as_datetime
         self.dt_cast[int] = self.int_or_bool
@@ -103,9 +107,13 @@ class AccessDatabase(Database):
                 try:
                     self.conn = pyodbc.connect(connstr)
                 except Exception:
-                    _state.exec_log.log_status_info(f"Could not connect via ODBC using: {connstr}")
+                    _state.exec_log.log_status_info(
+                        f"Could not connect via ODBC using: {re.sub(r'Pwd=[^;]*', 'Pwd=***', connstr)}",
+                    )
                 else:
-                    _state.exec_log.log_status_info(f"Connected via ODBC using: {connstr}")
+                    _state.exec_log.log_status_info(
+                        f"Connected via ODBC using: {re.sub(r'Pwd=[^;]*', 'Pwd=***', connstr)}",
+                    )
                     self.jet4 = jet4flag
                     return True
             return False
@@ -290,17 +298,17 @@ class AccessDatabase(Database):
         self.dao_flush_check()
         curs = self.cursor()
         try:
-            sql = f"select Name from MSysObjects where Name='{table_name}' And Type In (1,4,6);"
-            curs.execute(sql)
+            sql = "select Name from MSysObjects where Name=? And Type In (1,4,6);"
+            curs.execute(sql, (table_name,))
         except ErrInfo:
             raise
-        except Exception:
+        except Exception as e:
             raise ErrInfo(
                 type="db",
                 command_text=sql,
                 exception_msg=exception_desc(),
                 other_msg=f"Failure on test for existence of Access table {table_name}",
-            )
+            ) from e
         rows = curs.fetchall()
         return len(rows) > 0
 
@@ -312,7 +320,9 @@ class AccessDatabase(Database):
     ) -> bool:
         self.dao_flush_check()
         curs = self.cursor()
-        sql = f"select top 1 {column_name} from {table_name};"
+        quoted_col = self.quote_identifier(column_name)
+        quoted_tbl = self.quote_identifier(table_name)
+        sql = f"select top 1 {quoted_col} from {quoted_tbl};"
         try:
             curs.execute(sql)
         except Exception:
@@ -322,24 +332,25 @@ class AccessDatabase(Database):
     def table_columns(self, table_name: str, schema_name: str | None = None) -> list[str]:
         self.dao_flush_check()
         curs = self.cursor()
-        curs.execute(f"select top 1 * from {table_name};")
+        quoted_tbl = self.quote_identifier(table_name)
+        curs.execute(f"select top 1 * from {quoted_tbl};")
         return [d[0] for d in curs.description]
 
     def view_exists(self, view_name: str, schema_name: str | None = None) -> bool:
         self.dao_flush_check()
         curs = self.cursor()
         try:
-            sql = f"select Name from MSysObjects where Name='{view_name}' And Type = 5;"
-            curs.execute(sql)
+            sql = "select Name from MSysObjects where Name=? And Type = 5;"
+            curs.execute(sql, (view_name,))
         except ErrInfo:
             raise
-        except Exception:
+        except Exception as e:
             raise ErrInfo(
                 type="db",
                 command_text=sql,
                 exception_msg=exception_desc(),
                 other_msg=f"Test for existence of Access view/query {view_name}",
-            )
+            ) from e
         rows = curs.fetchall()
         return len(rows) > 0
 
@@ -356,7 +367,7 @@ class AccessDatabase(Database):
 
         if val is None or (isinstance(val, _state.stringtypes) and len(val) == 0):
             return None
-        if isinstance(val, (datetime.date, datetime.datetime, datetime.time)):
+        if isinstance(val, datetime.date | datetime.datetime | datetime.time):
             return val
         else:
             try:
@@ -414,5 +425,6 @@ class AccessDatabase(Database):
         with open(file_name, "rb") as f:
             filedata = f.read()
         sq_name = self.schema_qualified_table_name(schema_name, table_name)
-        sql = f"insert into {sq_name} ({column_name}) values ({self.paramsubs(1)});"
+        quoted_col = self.quote_identifier(column_name)
+        sql = f"insert into {sq_name} ({quoted_col}) values ({self.paramsubs(1)});"
         self.cursor().execute(sql, (pyodbc.Binary(filedata),))