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

execsql/db/sqlite.py

@@ -18,11 +18,14 @@ from execsql.exceptions import ErrInfo
 from execsql.utils.errors import exception_desc, fatal_error
 import execsql.state as _state
 
+__all__ = ["SQLiteDatabase"]
 
 DEFAULT_CONNECT_TIMEOUT = 30  # seconds
 
 
 class SQLiteDatabase(Database):
+    """SQLite adapter using the Python standard-library sqlite3 module."""
+
     def __init__(self, SQLite_fn: str, timeout: float = DEFAULT_CONNECT_TIMEOUT) -> None:
         try:
             import sqlite3  # noqa: F401
@@ -54,12 +57,12 @@ class SQLiteDatabase(Database):
                 self.conn = sqlite3.connect(self.db_name, timeout=self.timeout)
             except ErrInfo:
                 raise
-            except Exception:
+            except Exception as e:
                 raise ErrInfo(
                     type="exception",
                     exception_msg=exception_desc(),
                     other_msg=f"Can't open SQLite database {self.db_name}",
-                )
+                ) from e
         pragma_cols, pragma_data = self.select_data("pragma encoding;")
         self.encoding = pragma_data[0][0]
 
@@ -82,14 +85,14 @@ class SQLiteDatabase(Database):
             curs.execute(sql, (table_name,))
         except ErrInfo:
             raise
-        except Exception:
+        except Exception as e:
             self.rollback()
             raise ErrInfo(
                 type="db",
                 command_text=sql,
                 exception_msg=exception_desc(),
                 other_msg=f'Failed test for existence of SQLite table "{table_name}";',
-            )
+            ) from e
         rows = curs.fetchall()
         return len(rows) > 0
 
@@ -110,14 +113,14 @@ class SQLiteDatabase(Database):
             curs.execute(sql)
         except ErrInfo:
             raise
-        except Exception:
+        except Exception as e:
             self.rollback()
             raise ErrInfo(
                 type="db",
                 command_text=sql,
                 exception_msg=exception_desc(),
                 other_msg=f"Failed to get column names for table {table_name} of {self.name()}",
-            )
+            ) from e
         return [d[0] for d in curs.description]
 
     def view_exists(self, view_name: str) -> bool:
@@ -127,14 +130,14 @@ class SQLiteDatabase(Database):
             curs.execute(sql, (view_name,))
         except ErrInfo:
             raise
-        except Exception:
+        except Exception as e:
             self.rollback()
             raise ErrInfo(
                 type="db",
                 command_text=sql,
                 exception_msg=exception_desc(),
                 other_msg=f'Failed test for existence of SQLite view "{view_name}";',
-            )
+            ) from e
         rows = curs.fetchall()
         return len(rows) > 0
 
@@ -204,14 +207,14 @@ class SQLiteDatabase(Database):
                         curs.execute(sql, linedata)
                     except ErrInfo:
                         raise
-                    except Exception:
+                    except Exception as e:
                         self.rollback()
                         raise ErrInfo(
                             type="db",
                             command_text=sql,
                             exception_msg=exception_desc(),
                             other_msg=f"Can't load data into table {sq_name} from line {{{line}}}",
-                        )
+                        ) from e
                     total_rows += 1
                     interval = getattr(_state.conf, "import_progress_interval", 0)
                     if _state.exec_log and interval > 0 and total_rows % interval == 0:
@@ -235,5 +238,6 @@ class SQLiteDatabase(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, (sqlite3.Binary(filedata),))

execsql/db/sqlserver.py

@@ -7,6 +7,7 @@ Implements :class:`SqlServerDatabase`, which connects to Microsoft SQL
 Server via ``pyodbc``.  Corresponds to ``-t s`` on the CLI.
 """
 
+import re
 
 from execsql.db.base import Database
 from execsql.exceptions import ErrInfo
@@ -14,8 +15,12 @@ from execsql.utils.errors import fatal_error
 from execsql.utils.auth import clear_stored_password, get_password, password_from_keyring
 import execsql.state as _state
 
+__all__ = ["SqlServerDatabase"]
+
 
 class SqlServerDatabase(Database):
+    """Microsoft SQL Server adapter using pyodbc, trying drivers from newest to oldest."""
+
     def __init__(
         self,
         server_name: str,
@@ -96,9 +101,13 @@ class SqlServerDatabase(Database):
                     try:
                         self.conn = pyodbc.connect(connstr)
                     except Exception:
-                        _state.exec_log.log_status_info(f"Could not connect using: {connstr}")
+                        _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: {connstr}")
+                        _state.exec_log.log_status_info(
+                            f"Connected using: {re.sub(r'Pwd=[^;]*', 'Pwd=***', connstr)}",
+                        )
                         return True
                 return False
 
@@ -141,7 +150,7 @@ class SqlServerDatabase(Database):
 
     def schema_exists(self, schema_name: str) -> bool:
         curs = self.cursor()
-        curs.execute(f"select * from sys.schemas where name = '{schema_name}';")
+        curs.execute("select * from sys.schemas where name = ?;", (schema_name,))
         rows = curs.fetchall()
         curs.close()
         return len(rows) > 0
@@ -149,7 +158,8 @@ class SqlServerDatabase(Database):
     def role_exists(self, rolename: str) -> bool:
         curs = self.cursor()
         curs.execute(
-            f"select name from sys.database_principals where type in ('R', 'S') and name = '{rolename}';",
+            "select name from sys.database_principals where type in ('R', 'S') and name = ?;",
+            (rolename,),
         )
         rows = curs.fetchall()
         curs.close()
@@ -172,5 +182,6 @@ class SqlServerDatabase(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),))

execsql/exceptions.py

@@ -21,6 +21,24 @@ from a single location.  Notable exceptions:
 - :class:`CondParserError` / :class:`NumericParserError` — parser failures.
 """
 
+__all__ = [
+    "ExecSqlError",
+    "ConfigError",
+    "ExecSqlTimeoutError",
+    "ErrInfo",
+    "DataTypeError",
+    "DbTypeError",
+    "ColumnError",
+    "DataTableError",
+    "DatabaseNotImplementedError",
+    "OdsFileError",
+    "XlsFileError",
+    "XlsxFileError",
+    "ConsoleUIError",
+    "CondParserError",
+    "NumericParserError",
+]
+
 
 class ExecSqlError(Exception):
     """Base class for simple single-message execsql exceptions.
@@ -58,7 +76,7 @@ class ExecSqlTimeoutError(ExecSqlError):
         super().__init__(errmsg)
 
 
-class ErrInfo(Exception):
+class ErrInfo(ExecSqlError):
     """Rich exception and error-data carrier for execsql.
 
     ``str(e)`` returns the most informative available message (``other_msg``,
@@ -152,11 +170,11 @@ class ErrInfo(Exception):
         return self.eval_err()
 
 
-class DataTypeError(Exception):
+class DataTypeError(ExecSqlError):
     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"
-        super().__init__(str(self))
+        Exception.__init__(self, str(self))
 
     def __repr__(self) -> str:
         return f"DataTypeError({self.data_type_name!r}, {self.error_msg!r})"
@@ -165,12 +183,12 @@ class DataTypeError(Exception):
         return f"{self.data_type_name}: {self.error_msg}"
 
 
-class DbTypeError(Exception):
+class DbTypeError(ExecSqlError):
     def __init__(self, dbms_id: str, data_type: object, error_msg: str) -> None:
         self.dbms_id = dbms_id
         self.data_type = data_type
         self.error_msg = error_msg or "Unspecified error"
-        super().__init__(str(self))
+        Exception.__init__(self, str(self))
 
     def __repr__(self) -> str:
         return f"DbTypeError({self.dbms_id!r}, {self.data_type!r}, {self.error_msg!r})"
@@ -190,11 +208,11 @@ class DataTableError(ExecSqlError):
     """Raised for DataTable-level errors."""
 
 
-class DatabaseNotImplementedError(Exception):
+class DatabaseNotImplementedError(ExecSqlError):
     def __init__(self, db_name: str, method: str) -> None:
         self.db_name = db_name
         self.method = method
-        super().__init__(str(self))
+        Exception.__init__(self, str(self))
 
     def __repr__(self) -> str:
         return f"DatabaseNotImplementedError({self.db_name!r}, {self.method!r})"

execsql/exporters/base.py

@@ -22,6 +22,8 @@ from execsql.script import current_script_line
 from execsql.utils.errors import file_size_date
 from execsql.utils.gui import ConsoleUIError
 
+__all__ = ["WriteSpec", "ExportRecord", "ExportMetadata"]
+
 
 class ExportRecord:
     """Records the details of a single EXPORT operation for metadata tracking.
@@ -88,15 +90,18 @@ class ExportMetadata:
         self.recordlist: list[ExportRecord] = []
 
     def add(self, exp_record: ExportRecord) -> None:
+        """Append an export record to the collection."""
         self.recordlist.append(exp_record)
 
     def get(self):
+        """Return column headers and all not-yet-exported records, marking them exported."""
         recs = [er.record for er in self.recordlist if not er.exported]
         for er in self.recordlist:
             er.exported = True
         return self.colhdrs, recs
 
     def get_all(self):
+        """Return column headers and every record regardless of prior export state."""
         recs = [er.record for er in self.recordlist]
         for er in self.recordlist:
             er.exported = True
@@ -130,6 +135,7 @@ class WriteSpec:
         self.written = False
 
     def write(self) -> None:
+        """Execute the deferred write, expanding substitution variables first."""
         # Writes the message per the specifications given to '__init__()'.  Substitution
         # variables are processed.
         # Inputs: no inputs.
@@ -143,7 +149,12 @@ class WriteSpec:
             if self.outfile:
                 from execsql.utils.fileio import EncodedFile
 
-                EncodedFile(self.outfile, conf.output_encoding).open("a").write(msg)
+                ef = EncodedFile(self.outfile, conf.output_encoding)
+                fh = ef.open("a")
+                try:
+                    fh.write(msg)
+                finally:
+                    fh.close()
             if (not self.outfile) or self.tee:
                 try:
                     _state.output.write(msg.encode(conf.output_encoding))

execsql/exporters/delimited.py

@@ -29,9 +29,14 @@ from execsql.utils.errors import exception_desc
 from execsql.utils.fileio import filewriter_close
 from execsql.utils.strings import clean_words, fold_words
 
+__all__ = ["LineDelimiter", "CsvFile", "CsvWriter", "DelimitedWriter", "write_delimited_file"]
+
 
 class LineDelimiter:
+    """Encapsulates delimiter, quote character, and escape rules for a single line format."""
+
     def __init__(self, delim: str | None, quote: str | None, escchar: str | None) -> None:
+        """Initialise the line-format constants for a given delimiter/quote pair."""
         self.delimiter = delim
         self.joinchar = delim if delim else ""
         self.quotechar = quote
@@ -44,6 +49,7 @@ class LineDelimiter:
             self.quotedquote = None
 
     def delimited(self, datarow: Any, add_newline: bool = True) -> str:
+        """Format a sequence of values as a single delimited text line."""
         conf = _state.conf
         if self.quotechar:
             d_row = []
@@ -79,22 +85,30 @@ class LineDelimiter:
 
 
 class DelimitedWriter:
+    """Low-level writer that formats data rows as delimited text and sends them to an open file object."""
+
     def __init__(self, outfile: Any, delim: str | None, quote: str | None, escchar: str | None) -> None:
+        """Wrap an open file object with a :class:`LineDelimiter` for row-by-row writing."""
         self.outfile = outfile
         self.line_delimiter = LineDelimiter(delim, quote, escchar)
 
     def write(self, text_str: str) -> None:
+        """Write a raw string directly to the underlying file object."""
         self.outfile.write(text_str)
 
     def writerow(self, datarow: Any) -> None:
+        """Format one data row as delimited text and write it to the file."""
         self.outfile.write(self.line_delimiter.delimited(datarow))
 
     def writerows(self, datarows: Any) -> None:
+        """Write each row in an iterable of data rows to the file."""
         for row in datarows:
             self.writerow(row)
 
 
 class CsvWriter:
+    """Opens a named file (or stdout) and exposes a row-oriented delimited-text writing API."""
+
     def __init__(
         self,
         filename: str,
@@ -113,21 +127,32 @@ class CsvWriter:
         self.dwriter = DelimitedWriter(self.output, delim, quote, escchar)
 
     def write(self, text_str: str) -> None:
+        """Write a raw string to the output file."""
         self.dwriter.write(text_str)
 
     def writerow(self, datarow: Any) -> None:
+        """Format and write a single data row."""
         self.dwriter.writerow(datarow)
 
     def writerows(self, datarows: Any) -> None:
+        """Format and write each row in an iterable."""
         self.dwriter.writerows(datarows)
 
     def close(self) -> None:
+        """Close the underlying output file."""
         self.output.close()
         self.output = None
 
 
 class CsvFile(EncodedFile):
+    """Full delimited-file reader/writer with automatic format diagnosis.
+
+    Supports custom delimiters, quoting, encoding, junk-header skipping,
+    column-type inference, and ZIP output via :class:`CsvWriter`.
+    """
+
     def __init__(self, csvfname: str, file_encoding: str, junk_header_lines: int = 0) -> None:
+        """Open a CSV file path for later reading or writing."""
         super().__init__(csvfname, file_encoding)
         self.csvfname = csvfname
         self.junk_header_lines = junk_header_lines
@@ -143,6 +168,7 @@ class CsvFile(EncodedFile):
         return f"CsvFile({self.csvfname!r}, {self.encoding!r})"
 
     def openclean(self, mode: str) -> Any:
+        """Return an opened file object with the configured number of junk header lines skipped."""
         # Returns an opened file object with junk headers stripped.
         f = self.open(mode)
         for _ in range(self.junk_header_lines):
@@ -150,6 +176,7 @@ class CsvFile(EncodedFile):
         return f
 
     def lineformat(self, delimiter: str | None, quotechar: str | None, escapechar: str | None) -> None:
+        """Explicitly set the delimiter, quote character, and escape character."""
         # Specifies the format of a line.
         self.delimiter = delimiter
         self.quotechar = quotechar
@@ -413,15 +440,21 @@ class CsvFile(EncodedFile):
         )
 
     def evaluate_line_format(self) -> None:
+        """Scan the file to auto-detect the delimiter, quote character, and escape character."""
         # Scans the file to determine the delimiter, quote character, and escapechar.
         if not self.lineformat_set:
-            self.delimiter, self.quotechar, self.escapechar = self.diagnose_delim(self.openclean("rt"))
+            f = self.openclean("rt")
+            try:
+                self.delimiter, self.quotechar, self.escapechar = self.diagnose_delim(f)
+            finally:
+                f.close()
             self.lineformat_set = True
 
     def _record_format_error(self, pos_no: int, errmsg: str) -> None:
         self.parse_errors.append(f"{errmsg} in position {pos_no}")
 
     def read_and_parse_line(self, f: Any) -> list:
+        """Read and parse one line from an open file, returning a list of field values."""
         # Returns a list of line elements, parsed according to the established delimiter and quotechar.
         elements = []
         eat_multiple_delims = self.delimiter == " "
@@ -567,30 +600,34 @@ class CsvFile(EncodedFile):
         return elements
 
     def reader(self) -> Any:
+        """Yield parsed rows from the file as lists of field values."""
         conf = _state.conf
         self.evaluate_line_format()
         f = self.openclean("rt")
         line_no = 0
-        while True:
-            line_no += 1
-            try:
-                elements = self.read_and_parse_line(f)
-            except ErrInfo as e:
-                raise ErrInfo("error", other_msg=f"{e.other} on line {line_no}.") from e
-            except:
-                raise
-            if len(elements) > 0:
-                if conf.del_empty_cols and len(self.blank_cols) > 0:
-                    blanks = copy.copy(self.blank_cols)
-                    while len(blanks) > 0:
-                        b = blanks.pop()
-                        del elements[b]
-                yield elements
-            else:
-                break
-        f.close()
+        try:
+            while True:
+                line_no += 1
+                try:
+                    elements = self.read_and_parse_line(f)
+                except ErrInfo as e:
+                    raise ErrInfo("error", other_msg=f"{e.other} on line {line_no}.") from e
+                except:
+                    raise
+                if len(elements) > 0:
+                    if conf.del_empty_cols and len(self.blank_cols) > 0:
+                        blanks = copy.copy(self.blank_cols)
+                        while len(blanks) > 0:
+                            b = blanks.pop()
+                            del elements[b]
+                    yield elements
+                else:
+                    break
+        finally:
+            f.close()
 
     def writer(self, append: bool = False) -> CsvWriter:
+        """Return a :class:`CsvWriter` configured with this file's format settings."""
         return CsvWriter(self.filename, self.encoding, self.delimiter, self.quotechar, self.escapechar, append)
 
     def _colhdrs(self, inf: Any) -> list[str]:
@@ -600,12 +637,12 @@ class CsvFile(EncodedFile):
         except ErrInfo as e:
             e.other = f"Can't read column header line from {self.filename}.  {e.other or ''}"
             raise
-        except Exception:
+        except Exception as e:
             raise ErrInfo(
                 type="exception",
                 exception_msg=exception_desc(),
                 other_msg=f"Can't read column header line from {self.filename}",
-            )
+            ) from e
         if any(x is None or len(x) == 0 for x in colnames):
             if conf.del_empty_cols:
                 self.blank_cols = [
@@ -634,17 +671,20 @@ class CsvFile(EncodedFile):
         return colnames
 
     def column_headers(self) -> list[str]:
+        """Return the first row of the file as a list of column header strings."""
         if not self.lineformat_set:
             self.evaluate_line_format()
         inf = self.reader()
         return self._colhdrs(inf)
 
     def data_table_def(self) -> Any:
+        """Return a :class:`DataTable` describing the file's columns and types."""
         if self.table_data is None:
             self.evaluate_column_types()
         return self.table_data
 
     def evaluate_column_types(self) -> None:
+        """Scan the file and populate ``table_data`` with inferred column types."""
         if not self.lineformat_set:
             self.evaluate_line_format()
         inf = self.reader()
@@ -652,6 +692,7 @@ class CsvFile(EncodedFile):
         self.table_data = DataTable(colnames, inf)
 
     def create_table(self, database_type: Any, schemaname: str | None, tablename: str, pretty: bool = False) -> str:
+        """Generate a CREATE TABLE SQL statement for this file's inferred schema."""
         return self.table_data.create_table(database_type, schemaname, tablename, pretty)
 
 
@@ -664,6 +705,7 @@ def write_delimited_file(
     append: bool = False,
     zipfile: str | None = None,
 ) -> None:
+    """Write a query result set to a CSV, TSV, or other delimited text file."""
     delim = None
     quote = None
     escchar = None
@@ -700,18 +742,21 @@ def write_delimited_file(
         filewriter_close(outfile)
         ofile = EncodedFile(outfile, file_encoding).open(mode=fmode)
         fdesc = outfile
-    if not (filefmt.lower() == "plain" or (append and zipfile is None)):
-        datarow = line_delimiter.delimited(column_headers)
-        ofile.write(datarow)
-    for rec in rowsource:
-        try:
-            datarow = line_delimiter.delimited(rec)
+    try:
+        if not (filefmt.lower() == "plain" or (append and zipfile is None)):
+            datarow = line_delimiter.delimited(column_headers)
             ofile.write(datarow)
-        except ErrInfo:
-            raise
-        except Exception:
-            raise ErrInfo(
-                "exception",
-                exception_msg=exception_desc(),
-                other_msg=f"Can't write output to file {fdesc}.",
-            )
+        for rec in rowsource:
+            try:
+                datarow = line_delimiter.delimited(rec)
+                ofile.write(datarow)
+            except ErrInfo:
+                raise
+            except Exception as e:
+                raise ErrInfo(
+                    "exception",
+                    exception_msg=exception_desc(),
+                    other_msg=f"Can't write output to file {fdesc}.",
+                ) from e
+    finally:
+        ofile.close()

execsql/exporters/duckdb.py

@@ -15,6 +15,8 @@ from typing import Any
 from execsql.exceptions import ErrInfo
 from execsql.types import dbt_duckdb
 
+__all__ = ["export_duckdb", "write_query_to_duckdb"]
+
 
 def export_duckdb(
     outfile: str,
@@ -23,6 +25,7 @@ def export_duckdb(
     append: bool,
     tablename: str,
 ) -> None:
+    """Write pre-fetched rows to a named table in a DuckDB database file."""
     try:
         import duckdb
     except Exception:
@@ -79,12 +82,13 @@ def write_query_to_duckdb(
     append: bool,
     tablename: str,
 ) -> None:
+    """Execute a SELECT and write the result set to a named table in a DuckDB database."""
     from execsql.utils.errors import exception_desc
 
     try:
         hdrs, rows = db.select_rowsource(select_stmt)
     except ErrInfo:
         raise
-    except Exception:
-        raise ErrInfo("db", select_stmt, exception_msg=exception_desc())
+    except Exception as e:
+        raise ErrInfo("db", select_stmt, exception_msg=exception_desc()) from e
     export_duckdb(outfile, hdrs, rows, append, tablename)

execsql/exporters/feather.py

@@ -18,16 +18,19 @@ from execsql.types import DT_Boolean, DT_Date, DT_Timestamp, DT_TimestampTZ
 from execsql.utils.errors import exception_desc
 from execsql.utils.fileio import filewriter_close
 
+__all__ = ["write_query_to_feather", "write_query_to_hdf5"]
+
 
 def write_query_to_feather(outfile: str, headers: list[str], rows: Any) -> None:
+    """Write a row source as an Apache Arrow Feather v2 file using polars."""
     try:
         import polars as pl
-    except ImportError:
+    except ImportError as e:
         raise ErrInfo(
             "exception",
             exception_msg=exception_desc(),
             other_msg="The polars Python package must be installed to export data to the feather format.",
-        )
+        ) from e
     rows_list = list(rows)
     if rows_list:
         df = pl.DataFrame(rows_list, schema=headers, orient="row")
@@ -45,20 +48,21 @@ def write_query_to_hdf5(
     append: bool = False,
     desc: str | None = None,
 ) -> None:
+    """Execute a SELECT and write the result set to an HDF5 file using the tables library."""
     try:
         import tables
-    except ImportError:
+    except ImportError as e:
         raise ErrInfo(
             "exception",
             exception_msg=exception_desc(),
             other_msg="The tables Python library must be installed to export data to the HDF5 format.",
-        )
+        ) from e
     try:
         hdrs, rows = db.select_rowsource(select_stmt)
     except ErrInfo:
         raise
-    except Exception:
-        raise ErrInfo("db", select_stmt, exception_msg=exception_desc())
+    except Exception as e:
+        raise ErrInfo("db", select_stmt, exception_msg=exception_desc()) from e
 
     def h5type(datatype, size):
         if datatype in (_state.DT_Varchar, _state.DT_Text):