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

execsql/db/dsn.py

@@ -15,8 +15,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__ = ["DsnDatabase"]
+
 
 class DsnDatabase(Database):
+    """Generic ODBC adapter that connects to any data source registered as an ODBC DSN via pyodbc."""
+
     # There's no telling what is actually connected to a DSN, so this uses
     # generic Database methods almost exclusively.  Only 'exec_cmd()' is
     # overridden, and that uses the method for SQL Server because the DAO
@@ -79,23 +83,23 @@ class DsnDatabase(Database):
         def _try_connect():
             try:
                 _dsn_connect()
-            except Exception:
+            except Exception as e:
                 excdesc = exception_desc()
                 if "Optional feature not implemented" in excdesc:
                     try:
                         _dsn_connect(autocommit=True)
-                    except Exception:
+                    except Exception as e:
                         raise ErrInfo(
                             type="exception",
                             exception_msg=exception_desc(),
                             other_msg=f"Can't open DSN database {self.db_name} using ODBC",
-                        )
+                        ) from e
                 else:
                     raise ErrInfo(
                         type="exception",
                         exception_msg=excdesc,
                         other_msg=f"Can't open DSN database {self.db_name} using ODBC",
-                    )
+                    ) from e
 
         try:
             _try_connect()
@@ -136,5 +140,6 @@ class DsnDatabase(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/db/duckdb.py

@@ -15,8 +15,12 @@ from execsql.exceptions import ErrInfo
 from execsql.utils.errors import exception_desc, fatal_error
 import execsql.state as _state
 
+__all__ = ["DuckDBDatabase"]
+
 
 class DuckDBDatabase(Database):
+    """DuckDB in-process analytics adapter using the duckdb package."""
+
     def __init__(self, DuckDB_fn: str) -> None:
         try:
             import duckdb  # noqa: F401
@@ -48,12 +52,12 @@ class DuckDBDatabase(Database):
                 self.conn = duckdb.connect(self.db_name, read_only=False)
             except ErrInfo:
                 raise
-            except Exception:
+            except Exception as e:
                 raise ErrInfo(
                     type="exception",
                     exception_msg=exception_desc(),
                     other_msg=f"Can't open DuckDB database {self.db_name}",
-                )
+                ) from e
 
     def exec_cmd(self, querycommand: str) -> None:
         # DuckDB does not support stored functions, so the querycommand

execsql/db/factory.py

@@ -25,6 +25,18 @@ from execsql.db.duckdb import DuckDBDatabase
 from execsql.db.mysql import MySQLDatabase
 from execsql.db.firebird import FirebirdDatabase
 
+__all__ = [
+    "db_Access",
+    "db_Dsn",
+    "db_DuckDB",
+    "db_Firebird",
+    "db_MySQL",
+    "db_Oracle",
+    "db_Postgres",
+    "db_SQLite",
+    "db_SqlServer",
+]
+
 
 def db_Access(
     Access_fn: str,
@@ -32,6 +44,7 @@ def db_Access(
     user: str | None = None,
     encoding: str | None = None,
 ) -> AccessDatabase:
+    """Open an MS Access database file (.mdb or .accdb) via DAO/ODBC."""
     if not Path(Access_fn).exists():
         raise ErrInfo(
             type="error",
@@ -50,6 +63,7 @@ def db_Postgres(
     new_db: bool = False,
     password: str | None = None,
 ) -> PostgresDatabase:
+    """Open a new PostgreSQL connection via psycopg2."""
     return PostgresDatabase(server_name, database_name, user, pw_needed, port, new_db=new_db, password=password)
 
 
@@ -58,6 +72,7 @@ def db_SQLite(
     new_db: bool = False,
     encoding: str | None = None,
 ) -> SQLiteDatabase:
+    """Open a SQLite database file via the standard-library sqlite3 module."""
     if new_db:
         from execsql.utils.fileio import check_dir
 
@@ -79,6 +94,7 @@ def db_SqlServer(
     port: int | None = None,
     encoding: str | None = None,
 ) -> SqlServerDatabase:
+    """Open a Microsoft SQL Server connection via pyodbc."""
     return SqlServerDatabase(server_name, database_name, user, pw_needed, port, encoding)
 
 
@@ -90,6 +106,7 @@ def db_MySQL(
     port: int | None = None,
     encoding: str | None = None,
 ) -> MySQLDatabase:
+    """Open a MySQL or MariaDB connection via pymysql."""
     return MySQLDatabase(server_name, database_name, user, pw_needed, port, encoding)
 
 
@@ -98,6 +115,7 @@ def db_DuckDB(
     new_db: bool = False,
     encoding: str | None = None,
 ) -> DuckDBDatabase:
+    """Open a DuckDB in-process analytics database file via the duckdb package."""
     if new_db:
         from execsql.utils.fileio import check_dir
 
@@ -119,6 +137,7 @@ def db_Oracle(
     port: int | None = None,
     encoding: str | None = None,
 ) -> OracleDatabase:
+    """Open an Oracle database connection via cx_Oracle (python-oracledb)."""
     return OracleDatabase(server_name, database_name, user, pw_needed, port, encoding)
 
 
@@ -130,6 +149,7 @@ def db_Firebird(
     port: int | None = None,
     encoding: str | None = None,
 ) -> FirebirdDatabase:
+    """Open a Firebird database connection via the firebird-driver package."""
     return FirebirdDatabase(server_name, database_name, user, pw_needed, port, encoding)
 
 
@@ -139,4 +159,5 @@ def db_Dsn(
     pw_needed: bool = True,
     encoding: str | None = None,
 ) -> DsnDatabase:
+    """Open a connection to any ODBC data source registered under *dsn_name*."""
     return DsnDatabase(dsn_name=dsn_name, user_name=user, need_passwd=pw_needed, encoding=encoding)

execsql/db/firebird.py

@@ -14,8 +14,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__ = ["FirebirdDatabase"]
+
 
 class FirebirdDatabase(Database):
+    """Firebird adapter using the firebird-driver (fdb) package."""
+
     def __init__(
         self,
         server_name: str,
@@ -30,7 +34,7 @@ class FirebirdDatabase(Database):
             import fdb as firebird_lib  # noqa: F401
         except Exception:
             fatal_error(
-                "The fdb module is required to connect to MySQL.   See https://pypi.python.org/pypi/fdb/",
+                "The fdb module is required to connect to Firebird.   See https://pypi.python.org/pypi/fdb/",
             )
         from execsql.types import dbt_firebird
 
@@ -104,9 +108,9 @@ class FirebirdDatabase(Database):
                 raise
             except ErrInfo:
                 raise
-            except Exception:
+            except Exception as e:
                 msg = f"Failed to open Firebird database {self.db_name} on {self.server_name}"
-                raise ErrInfo(type="exception", exception_msg=exception_desc(), other_msg=msg)
+                raise ErrInfo(type="exception", exception_msg=exception_desc(), other_msg=msg) from e
 
     def exec_cmd(self, querycommand: str) -> None:
         # The querycommand must be a stored function (/procedure)
@@ -122,15 +126,15 @@ class FirebirdDatabase(Database):
     def table_exists(self, table_name: str, schema_name: str | None = None) -> bool:
         curs = self.cursor()
         sql = (
-            f"SELECT RDB$RELATION_NAME FROM RDB$RELATIONS "
-            f"WHERE RDB$SYSTEM_FLAG=0 AND RDB$VIEW_BLR IS NULL "
-            f"AND RDB$RELATION_NAME='{table_name.upper()}';"
+            "SELECT RDB$RELATION_NAME FROM RDB$RELATIONS "
+            "WHERE RDB$SYSTEM_FLAG=0 AND RDB$VIEW_BLR IS NULL "
+            "AND RDB$RELATION_NAME=?;"
         )
         try:
-            curs.execute(sql)
+            curs.execute(sql, (table_name.upper(),))
         except ErrInfo:
             raise
-        except Exception:
+        except Exception as e:
             try:
                 self.rollback()
             except Exception:
@@ -140,7 +144,7 @@ class FirebirdDatabase(Database):
                 command_text=sql,
                 exception_msg=exception_desc(),
                 other_msg=f"Failed test for existence of Firebird table {table_name}",
-            )
+            ) from e
         rows = curs.fetchall()
         self.conn.commit()
         curs.close()
@@ -153,7 +157,9 @@ class FirebirdDatabase(Database):
         schema_name: str | None = None,
     ) -> bool:
         curs = self.cursor()
-        sql = f"select first 1 {column_name} from {table_name};"
+        quoted_col = self.quote_identifier(column_name)
+        quoted_tbl = self.quote_identifier(table_name)
+        sql = f"select first 1 {quoted_col} from {quoted_tbl};"
         try:
             curs.execute(sql)
         except Exception:
@@ -162,36 +168,37 @@ class FirebirdDatabase(Database):
 
     def table_columns(self, table_name: str, schema_name: str | None = None) -> list[str]:
         curs = self.cursor()
-        sql = f"select first 1 * from {table_name};"
+        quoted_tbl = self.quote_identifier(table_name)
+        sql = f"select first 1 * from {quoted_tbl};"
         try:
             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, schema_name: str | None = None) -> bool:
         curs = self.cursor()
-        sql = f"select distinct rdb$view_name from rdb$view_relations where rdb$view_name = '{view_name}';"
+        sql = "select distinct rdb$view_name from rdb$view_relations where rdb$view_name = ?;"
         try:
-            curs.execute(sql)
+            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 Firebird view {view_name}",
-            )
+            ) from e
         rows = curs.fetchall()
         curs.close()
         return len(rows) > 0
@@ -202,8 +209,9 @@ class FirebirdDatabase(Database):
     def role_exists(self, rolename: str) -> bool:
         curs = self.cursor()
         curs.execute(
-            f"SELECT DISTINCT USER FROM RDB$USER_PRIVILEGES WHERE USER = '{rolename}' union "
-            f" SELECT DISTINCT RDB$ROLE_NAME FROM RDB$ROLES WHERE RDB$ROLE_NAME = '{rolename}';",
+            "SELECT DISTINCT USER FROM RDB$USER_PRIVILEGES WHERE USER = ? union "
+            " SELECT DISTINCT RDB$ROLE_NAME FROM RDB$ROLES WHERE RDB$ROLE_NAME = ?;",
+            (rolename, rolename),
         )
         rows = curs.fetchall()
         curs.close()

execsql/db/mysql.py

@@ -16,8 +16,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__ = ["MySQLDatabase"]
+
 
 class MySQLDatabase(Database):
+    """MySQL and MariaDB adapter using the pymysql package."""
+
     def __init__(
         self,
         server_name: str,
@@ -109,9 +113,9 @@ class MySQLDatabase(Database):
                 raise
             except ErrInfo:
                 raise
-            except Exception:
+            except Exception as e:
                 msg = f"Failed to open MySQL database {self.db_name} on {self.server_name}"
-                raise ErrInfo(type="exception", exception_msg=exception_desc(), other_msg=msg)
+                raise ErrInfo(type="exception", exception_msg=exception_desc(), other_msg=msg) from e
 
     def exec_cmd(self, querycommand: str) -> None:
         # The querycommand must be a stored function (/procedure)
@@ -130,9 +134,10 @@ class MySQLDatabase(Database):
     def role_exists(self, rolename: str) -> bool:
         curs = self.cursor()
         curs.execute(
-            f"select distinct user as role from mysql.user where user = '{rolename}'"
-            f" union select distinct role_name as role from information_schema.applicable_roles"
-            f" where role_name = '{rolename}'",
+            "select distinct user as role from mysql.user where user = %s"
+            " union select distinct role_name as role from information_schema.applicable_roles"
+            " where role_name = %s",
+            (rolename, rolename),
         )
         rows = curs.fetchall()
         curs.close()
@@ -274,14 +279,14 @@ class MySQLDatabase(Database):
                         curs.executemany(sql_template, b)
                     except ErrInfo:
                         raise
-                    except Exception:
+                    except Exception as e:
                         self.rollback()
                         raise ErrInfo(
                             type="db",
                             command_text=sql_template,
                             exception_msg=exception_desc(),
                             other_msg=f"Import from file into table {sq_name}, line {{{line}}}",
-                        )
+                        ) from e
                     total_rows += len(b)
                     interval = _state.conf.import_progress_interval
                     if _state.exec_log and interval > 0 and total_rows % interval == 0:

execsql/db/oracle.py

@@ -16,15 +16,19 @@ 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__ = ["OracleDatabase"]
+
 
 class OracleDatabase(Database):
+    """Oracle adapter using the cx_Oracle (python-oracledb) driver."""
+
     def __init__(
         self,
         server_name: str,
         db_name: str,
         user_name: str | None,
         need_passwd: bool = False,
-        port: int | None = 5432,
+        port: int | None = 1521,
         encoding: str | None = "UTF8",
         password: str | None = None,
     ) -> None:
@@ -95,9 +99,9 @@ class OracleDatabase(Database):
                 raise
             except ErrInfo:
                 raise
-            except Exception:
+            except Exception as e:
                 msg = f"Failed to open Oracle database {self.db_name} on {self.server_name}"
-                raise ErrInfo(type="exception", exception_msg=exception_desc(), other_msg=msg)
+                raise ErrInfo(type="exception", exception_msg=exception_desc(), other_msg=msg) from e
 
     def execute(self, sql: Any, paramlist: list | None = None) -> None:
         # Strip any semicolon off the end and pass to the parent method.
@@ -141,14 +145,14 @@ class OracleDatabase(Database):
             curs.execute(sql, params)
         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 table {table_name} in {self.name()}",
-            )
+            ) from e
         rows = curs.fetchall()
         curs.close()
         return len(rows) > 0
@@ -170,14 +174,14 @@ class OracleDatabase(Database):
             curs.execute(sql, params)
         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 column {column_name} in table {table_name} of {self.name()}",
-            )
+            ) from e
         rows = curs.fetchall()
         curs.close()
         return len(rows) > 0
@@ -194,14 +198,14 @@ class OracleDatabase(Database):
             curs.execute(sql, params)
         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
         rows = curs.fetchall()
         curs.close()
         return [row[0] for row in rows]
@@ -218,14 +222,14 @@ class OracleDatabase(Database):
             curs.execute(sql, params)
         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 view {view_name} in {self.name()}",
-            )
+            ) from e
         rows = curs.fetchall()
         curs.close()
         return len(rows) > 0

execsql/db/postgres.py

@@ -19,11 +19,14 @@ from execsql.utils.auth import clear_stored_password, get_password, password_fro
 from execsql.utils.strings import encodings_match
 import execsql.state as _state
 
+__all__ = ["PostgresDatabase"]
 
 DEFAULT_CONNECT_TIMEOUT = 30  # seconds
 
 
 class PostgresDatabase(Database):
+    """PostgreSQL adapter using psycopg2, with schema support, server-side COPY, and keyring auth."""
+
     def __init__(
         self,
         server_name: str,
@@ -87,18 +90,20 @@ class PostgresDatabase(Database):
                         port=db.port,
                         connect_timeout=db.connect_timeout,
                     )
-            except Exception:
+            except Exception as e:
                 msg = (
                     f"Failed to open PostgreSQL database {self.db_name} on {self.server_name}; "
                     "check server and database name, and validity of credentials"
                 )
-                raise ErrInfo(type="exception", exception_msg=exception_desc(), other_msg=msg)
+                raise ErrInfo(type="exception", exception_msg=exception_desc(), other_msg=msg) from e
 
         def create_db(db: PostgresDatabase) -> None:
             conn = db_conn(db, "postgres")
             conn.autocommit = True
             curs = conn.cursor()
-            curs.execute(f"create database {db.db_name} encoding '{db.encoding}';")
+            quoted_name = db.quote_identifier(db.db_name)
+            quoted_enc = db.quote_identifier(db.encoding)
+            curs.execute(f"create database {quoted_name} encoding {quoted_enc};")
             conn.close()
 
         if self.conn is None:
@@ -133,9 +138,9 @@ class PostgresDatabase(Database):
                 raise
             except ErrInfo:
                 raise
-            except Exception:
+            except Exception as e:
                 msg = f"Failed to open PostgreSQL database {self.db_name} on {self.server_name}"
-                raise ErrInfo(type="exception", exception_msg=exception_desc(), other_msg=msg)
+                raise ErrInfo(type="exception", exception_msg=exception_desc(), other_msg=msg) from e
             # (Re)set the encoding to match the database.
             self.encoding = self.conn.encoding
 
@@ -177,14 +182,14 @@ class PostgresDatabase(Database):
             curs.execute(sql, params)
         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 table {table_name} in {self.name()}",
-            )
+            ) from e
         rows = curs.fetchall()
         curs.close()
         return len(rows) > 0
@@ -209,14 +214,14 @@ class PostgresDatabase(Database):
             curs.execute(sql, params)
         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 view {view_name} in {self.name()}",
-            )
+            ) from e
         rows = curs.fetchall()
         curs.close()
         return len(rows) > 0
@@ -304,9 +309,18 @@ class PostgresDatabase(Database):
             # ASCII unit separator, which, if it had been used for its intended purpose,
             # should have been identified as the delimiter, so presumably it has not been used.
             delim = csv_file_obj.delimiter if csv_file_obj.delimiter else chr(31)
-            copy_cmd = f"copy {sq_name} ({input_col_list}) from stdin with (format csv, null '', delimiter '{delim}'"
+            if len(delim) != 1:
+                raise ErrInfo(
+                    type="error",
+                    other_msg=f"Invalid delimiter for COPY: expected single character, got {len(delim)} characters",
+                )
+            safe_delim = delim.replace("'", "''")
+            copy_cmd = (
+                f"copy {sq_name} ({input_col_list}) from stdin with (format csv, null '', delimiter '{safe_delim}'"
+            )
             if csv_file_obj.quotechar:
-                copy_cmd = copy_cmd + f", quote '{csv_file_obj.quotechar}'"
+                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",
@@ -315,13 +329,13 @@ class PostgresDatabase(Database):
                 curs.copy_expert(copy_cmd, rf, _state.conf.import_buffer)
             except ErrInfo:
                 raise
-            except Exception:
+            except Exception as e:
                 self.rollback()
                 raise ErrInfo(
                     type="exception",
                     exception_msg=exception_desc(),
                     other_msg=f"Can't import from file to table {sq_name}",
-                )
+                ) from e
         else:
             data_indexes = [csv_file_cols_q.index(col) for col in import_cols]
             paramspec = ",".join(["%s"] * len(import_cols))
@@ -398,14 +412,14 @@ class PostgresDatabase(Database):
                         curs.executemany(sql_template, b)
                     except ErrInfo:
                         raise
-                    except Exception:
+                    except Exception as e:
                         self.rollback()
                         raise ErrInfo(
                             type="db",
                             command_text=sql_template,
                             exception_msg=exception_desc(),
                             other_msg=f"Can't load data into table {sq_name} of {self.name()} from line {{{line}}}",
-                        )
+                        ) from e
                     total_rows += len(b)
                     interval = _state.conf.import_progress_interval
                     if _state.exec_log and interval > 0 and total_rows % interval == 0:
@@ -431,5 +445,6 @@ class PostgresDatabase(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, (psycopg2.Binary(filedata),))