execsql2 2.2.1__py3-none-any.whl → 2.4.1__py3-none-any.whl

execsql/db/base.py

@@ -14,8 +14,10 @@ open :class:`Database` instances and tracks which connection is currently
 active.  It is the canonical ``_state.dbs`` object.
 """
 
+import contextlib
 import datetime
 import re
+from abc import ABC, abstractmethod
 from decimal import Decimal
 from typing import Any
 from collections.abc import Callable, Generator, Iterator
@@ -24,6 +26,8 @@ from execsql.exceptions import ErrInfo
 from execsql.utils.errors import exception_desc
 import execsql.state as _state
 
+__all__ = ["Database", "DatabasePool"]
+
 
 def _default_dt_cast() -> dict[type, Callable]:
     """Build the default type-cast mapping used by all database backends."""
@@ -41,13 +45,14 @@ def _default_dt_cast() -> dict[type, Callable]:
     }
 
 
-class Database:
+class Database(ABC):
     """Abstract base class for all database connections."""
 
     _dt_cast: dict[type, Callable] | None = None
 
     @property
     def dt_cast(self) -> dict[type, Callable]:
+        """Return the type-cast mapping, initialising it lazily on first access."""
         if self._dt_cast is None:
             self._dt_cast = _default_dt_cast()
         return self._dt_cast
@@ -85,22 +90,38 @@ class Database:
         )
 
     def name(self) -> str:
+        """Return a human-readable description of this connection (DBMS + server/file)."""
         if self.server_name:
             return f"{self.type.dbms_id}(server {self.server_name}; database {self.db_name})"
         else:
             return f"{self.type.dbms_id}(file {self.db_name})"
 
+    @abstractmethod
     def open_db(self) -> None:
-        from execsql.exceptions import DatabaseNotImplementedError
-
-        raise DatabaseNotImplementedError(self.name(), "open_db")
+        """Open the underlying database connection."""
+        ...
 
     def cursor(self):
+        """Return a new cursor, opening the connection first if it has not been opened yet."""
         if self.conn is None:
             self.open_db()
         return self.conn.cursor()
 
+    @contextlib.contextmanager
+    def _cursor(self):
+        """Context manager that yields a cursor and closes it on exit.
+
+        Works with any DB-API 2.0 cursor regardless of whether the driver
+        natively supports the context manager protocol.
+        """
+        curs = self.cursor()
+        try:
+            yield curs
+        finally:
+            curs.close()
+
     def close(self) -> None:
+        """Close the database connection, logging a warning if autocommit is off."""
         if self.conn:
             if not self.autocommit:
                 _state.exec_log.log_status_info(
@@ -115,24 +136,26 @@ class Database:
         return '"' + identifier.replace('"', '""') + '"'
 
     def paramsubs(self, paramcount: int) -> str:
+        """Return a comma-separated string of *paramcount* parameter placeholders."""
         return ",".join((self.paramstr,) * paramcount)
 
     def execute(self, sql: Any, paramlist: list | None = None) -> None:
-        # A shortcut to self.cursor().execute() that handles encoding.
-        # Whether or not encoding is needed depends on the DBMS.
+        """Execute *sql* (optionally with *paramlist*), updating ``$LAST_ROWCOUNT``.
+
+        Rolls back the current transaction and re-raises on any driver error.
+        """
         if type(sql) in (tuple, list):
             sql = " ".join(sql)
         try:
-            curs = self.cursor()
-            if paramlist is None:
-                curs.execute(sql)
-            else:
-                curs.execute(sql, paramlist)
-            try:
-                # DuckDB does not support the 'rowcount' attribute.
-                _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)
-            except Exception:
-                pass  # Non-critical: some drivers lack rowcount support.
+            with self._cursor() as curs:
+                if paramlist is None:
+                    curs.execute(sql)
+                else:
+                    curs.execute(sql, paramlist)
+                try:
+                    _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)
+                except Exception:
+                    pass  # Non-critical: some drivers lack rowcount support.
         except Exception:
             try:
                 self.rollback()
@@ -140,22 +163,26 @@ class Database:
                 pass  # Rollback is best-effort after a failed execute.
             raise
 
+    @abstractmethod
     def exec_cmd(self, querycommand: str) -> None:
-        from execsql.exceptions import DatabaseNotImplementedError
-
-        raise DatabaseNotImplementedError(self.name(), "exec_cmd")
+        """Execute a stored procedure or function by name."""
+        ...
 
     def autocommit_on(self) -> None:
+        """Enable autocommit mode so each statement is committed immediately."""
         self.autocommit = True
 
     def autocommit_off(self) -> None:
+        """Disable autocommit mode, grouping subsequent statements into a transaction."""
         self.autocommit = False
 
     def commit(self) -> None:
+        """Commit the current transaction if autocommit is enabled."""
         if self.conn and self.autocommit:
             self.conn.commit()
 
     def rollback(self) -> None:
+        """Roll back the current transaction; swallows errors (best-effort)."""
         if self.conn:
             try:
                 self.conn.rollback()
@@ -163,6 +190,7 @@ class Database:
                 pass  # Best-effort; connection may already be closed.
 
     def schema_qualified_table_name(self, schema_name: str | None, table_name: str) -> str:
+        """Return the quoted, optionally schema-qualified form of *table_name*."""
         table_name = self.type.quoted(table_name)
         if schema_name:
             schema_name = self.type.quoted(schema_name)
@@ -170,21 +198,22 @@ class Database:
         return table_name
 
     def select_data(self, sql: str) -> tuple[list[str], list]:
-        # Returns the results of the sql select statement.
-        curs = self.cursor()
-        try:
-            curs.execute(sql)
-        except Exception:
-            self.rollback()
-            raise
-        try:
-            _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)
-        except Exception:
-            pass  # Non-critical: some drivers lack rowcount support.
-        rows = curs.fetchall()
-        return [d[0] for d in curs.description], rows
+        """Execute *sql* and return ``(column_names, rows)`` with all rows fetched into memory."""
+        with self._cursor() as curs:
+            try:
+                curs.execute(sql)
+            except Exception:
+                self.rollback()
+                raise
+            try:
+                _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)
+            except Exception:
+                pass  # Non-critical: some drivers lack rowcount support.
+            rows = curs.fetchall()
+            return [d[0] for d in curs.description], rows
 
     def select_rowsource(self, sql: str) -> tuple[list[str], Generator]:
+        """Execute *sql* and return ``(column_names, row_generator)`` for streaming large result sets."""
         # Return 1) a list of column names, and 2) an iterable that yields rows.
         curs = self.cursor()
         try:
@@ -219,6 +248,7 @@ class Database:
         return [d[0] for d in curs.description], decode_row()
 
     def select_rowdict(self, sql: str) -> tuple[list[str], Iterator]:
+        """Execute *sql* and return ``(column_names, row_iterator)`` where each row is a ``dict``."""
         # Return an iterable that yields dictionaries of row data
         curs = self.cursor()
         try:
@@ -246,35 +276,35 @@ class Database:
         return hdrs, iter(dict_row, None)
 
     def schema_exists(self, schema_name: str) -> bool:
-        curs = self.cursor()
-        sql = f"SELECT schema_name FROM information_schema.schemata WHERE schema_name = {self.paramstr};"
-        curs.execute(sql, (schema_name,))
-        rows = curs.fetchall()
-        curs.close()
+        """Return ``True`` if *schema_name* exists in this database."""
+        with self._cursor() as curs:
+            sql = f"SELECT schema_name FROM information_schema.schemata WHERE schema_name = {self.paramstr};"
+            curs.execute(sql, (schema_name,))
+            rows = curs.fetchall()
         return len(rows) > 0
 
     def table_exists(self, table_name: str, schema_name: str | None = None) -> bool:
-        curs = self.cursor()
-        params: list = [table_name]
-        schema_clause = ""
-        if schema_name:
-            schema_clause = f" and table_schema={self.paramstr}"
-            params.append(schema_name)
-        sql = f"select table_name from information_schema.tables where table_name = {self.paramstr}{schema_clause};"
-        try:
-            curs.execute(sql, params)
-        except ErrInfo:
-            raise
-        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 ``True`` if *table_name* (optionally in *schema_name*) exists."""
+        with self._cursor() as curs:
+            params: list = [table_name]
+            schema_clause = ""
+            if schema_name:
+                schema_clause = f" and table_schema={self.paramstr}"
+                params.append(schema_name)
+            sql = f"select table_name from information_schema.tables where table_name = {self.paramstr}{schema_clause};"
+            try:
+                curs.execute(sql, params)
+            except ErrInfo:
+                raise
+            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()
         return len(rows) > 0
 
     def column_exists(
@@ -283,92 +313,94 @@ class Database:
         column_name: str,
         schema_name: str | None = None,
     ) -> bool:
-        curs = self.cursor()
-        params: list = [table_name]
-        schema_clause = ""
-        if schema_name:
-            schema_clause = f" and table_schema={self.paramstr}"
-            params.append(schema_name)
-        params.append(column_name)
-        sql = (
-            f"select column_name from information_schema.columns "
-            f"where table_name={self.paramstr}{schema_clause} "
-            f"and column_name={self.paramstr};"
-        )
-        try:
-            curs.execute(sql, params)
-        except ErrInfo:
-            raise
-        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 ``True`` if *column_name* exists in *table_name* (optionally in *schema_name*)."""
+        with self._cursor() as curs:
+            params: list = [table_name]
+            schema_clause = ""
+            if schema_name:
+                schema_clause = f" and table_schema={self.paramstr}"
+                params.append(schema_name)
+            params.append(column_name)
+            sql = (
+                f"select column_name from information_schema.columns "
+                f"where table_name={self.paramstr}{schema_clause} "
+                f"and column_name={self.paramstr};"
+            )
+            try:
+                curs.execute(sql, params)
+            except ErrInfo:
+                raise
+            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()
         return len(rows) > 0
 
     def table_columns(self, table_name: str, schema_name: str | None = None) -> list[str]:
-        curs = self.cursor()
-        params: list = [table_name]
-        schema_clause = ""
-        if schema_name:
-            schema_clause = f" and table_schema={self.paramstr}"
-            params.append(schema_name)
-        sql = (
-            f"select column_name from information_schema.columns "
-            f"where table_name={self.paramstr}{schema_clause} "
-            f"order by ordinal_position;"
-        )
-        try:
-            curs.execute(sql, params)
-        except ErrInfo:
-            raise
-        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 the ordered list of column names for *table_name*."""
+        with self._cursor() as curs:
+            params: list = [table_name]
+            schema_clause = ""
+            if schema_name:
+                schema_clause = f" and table_schema={self.paramstr}"
+                params.append(schema_name)
+            sql = (
+                f"select column_name from information_schema.columns "
+                f"where table_name={self.paramstr}{schema_clause} "
+                f"order by ordinal_position;"
+            )
+            try:
+                curs.execute(sql, params)
+            except ErrInfo:
+                raise
+            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()
         return [row[0] for row in rows]
 
     def view_exists(self, view_name: str, schema_name: str | None = None) -> bool:
-        curs = self.cursor()
-        params: list = [view_name]
-        schema_clause = ""
-        if schema_name:
-            schema_clause = f" and table_schema={self.paramstr}"
-            params.append(schema_name)
-        sql = f"select table_name from information_schema.views where table_name = {self.paramstr}{schema_clause};"
-        try:
-            curs.execute(sql, params)
-        except ErrInfo:
-            raise
-        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 ``True`` if *view_name* (optionally in *schema_name*) exists."""
+        with self._cursor() as curs:
+            params: list = [view_name]
+            schema_clause = ""
+            if schema_name:
+                schema_clause = f" and table_schema={self.paramstr}"
+                params.append(schema_name)
+            sql = f"select table_name from information_schema.views where table_name = {self.paramstr}{schema_clause};"
+            try:
+                curs.execute(sql, params)
+            except ErrInfo:
+                raise
+            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()
         return len(rows) > 0
 
     def role_exists(self, rolename: str) -> bool:
+        """Return ``True`` if *rolename* exists; subclasses must override this."""
         from execsql.exceptions import DatabaseNotImplementedError
 
         raise DatabaseNotImplementedError(self.name(), "role_exists")
 
     def drop_table(self, tablename: str) -> None:
+        """Drop *tablename* if it exists; *tablename* must already be schema-qualified and quoted."""
         # The 'tablename' argument should be schema-qualified and quoted as necessary.
         self.execute(f"drop table if exists {tablename} cascade;")
         self.commit()
@@ -381,6 +413,11 @@ class Database:
         column_list: list[str],
         tablespec_src: Callable,
     ) -> None:
+        """Bulk-insert rows from *rowsource* into *table_name* using the columns in *column_list*.
+
+        *rowsource* must be a generator yielding lists of values in column order.
+        *tablespec_src* is a zero-argument callable that returns the table's type specification.
+        """
         # The rowsource argument must be a generator yielding a list of values for the columns of the table.
         # The column_list argument must an iterable containing column names.  This may be a subset of
         # the names of columns in the rowsource.
@@ -542,6 +579,7 @@ class Database:
         csv_file_obj: Any,
         skipheader: bool,
     ) -> None:
+        """Import a CSV/tabular file into *table_name*; column names must be compatible."""
         # Import a text (CSV) file containing tabular data to a table.  Columns must be compatible.
         if not self.table_exists(table_name, schema_name):
             raise ErrInfo(
@@ -584,12 +622,14 @@ class Database:
         column_name: str,
         file_name: str,
     ) -> None:
+        """Insert the raw binary content of *file_name* as a single row into *column_name* of *table_name*."""
         with open(file_name, "rb") as f:
             filedata = f.read()
         sq_name = self.schema_qualified_table_name(schema_name, table_name)
         quoted_col = self.quote_identifier(column_name)
         sql = f"insert into {sq_name} ({quoted_col}) values ({self.paramsubs(1)});"
-        self.cursor().execute(sql, (filedata,))
+        with self._cursor() as curs:
+            curs.execute(sql, (filedata,))
 
 
 class DatabasePool:
@@ -606,6 +646,7 @@ class DatabasePool:
         return "DatabasePool()"
 
     def add(self, db_alias: str, db_obj: Database) -> None:
+        """Register *db_obj* under *db_alias*, setting it as initial/current if this is the first connection."""
         db_alias = db_alias.lower()
         if db_alias == "initial" and len(self.pool) > 0:
             raise ErrInfo(
@@ -629,25 +670,27 @@ class DatabasePool:
         self.pool[db_alias] = db_obj
 
     def aliases(self) -> list[str]:
-        # Return a list of the currently defined aliases
+        """Return a list of all currently registered database aliases."""
         return list(self.pool)
 
     def current(self) -> Database:
-        # Return the current db object.
+        """Return the currently active ``Database`` object."""
         return self.pool[self.current_db]
 
     def current_alias(self) -> str:
-        # Return the alias of the current db object.
+        """Return the alias string for the currently active database."""
         return self.current_db
 
     def initial(self) -> Database:
+        """Return the first ``Database`` that was added to the pool."""
         return self.pool[self.initial_db]
 
     def aliased_as(self, db_alias: str) -> Database:
+        """Return the ``Database`` registered under *db_alias*."""
         return self.pool[db_alias]
 
     def make_current(self, db_alias: str) -> None:
-        # Change the current database in use.
+        """Set the active database to *db_alias*; raises ``ErrInfo`` if the alias is unknown."""
         db_alias = db_alias.lower()
         if db_alias not in self.pool:
             raise ErrInfo(
@@ -657,6 +700,7 @@ class DatabasePool:
         self.current_db = db_alias
 
     def disconnect(self, alias: str) -> None:
+        """Close and remove the connection registered under *alias* from the pool."""
         if alias == self.current_db or (alias == "initial" and "initial" in self.pool):
             raise ErrInfo(
                 type="error",
@@ -667,6 +711,7 @@ class DatabasePool:
             del self.pool[alias]
 
     def closeall(self) -> None:
+        """Roll back and close every connection in the pool, then reset the pool to empty."""
         for alias, db in self.pool.items():
             nm = db.name()
             try:

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

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

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
 
@@ -78,8 +93,10 @@ def db_SqlServer(
     pw_needed: bool = True,
     port: int | None = None,
     encoding: str | None = None,
+    password: str | None = None,
 ) -> SqlServerDatabase:
-    return SqlServerDatabase(server_name, database_name, user, pw_needed, port, encoding)
+    """Open a Microsoft SQL Server connection via pyodbc."""
+    return SqlServerDatabase(server_name, database_name, user, pw_needed, port, encoding, password=password)
 
 
 def db_MySQL(
@@ -89,8 +106,10 @@ def db_MySQL(
     pw_needed: bool = True,
     port: int | None = None,
     encoding: str | None = None,
+    password: str | None = None,
 ) -> MySQLDatabase:
-    return MySQLDatabase(server_name, database_name, user, pw_needed, port, encoding)
+    """Open a MySQL or MariaDB connection via pymysql."""
+    return MySQLDatabase(server_name, database_name, user, pw_needed, port, encoding, password=password)
 
 
 def db_DuckDB(
@@ -98,6 +117,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
 
@@ -118,8 +138,10 @@ def db_Oracle(
     pw_needed: bool = True,
     port: int | None = None,
     encoding: str | None = None,
+    password: str | None = None,
 ) -> OracleDatabase:
-    return OracleDatabase(server_name, database_name, user, pw_needed, port, encoding)
+    """Open an Oracle database connection via cx_Oracle (python-oracledb)."""
+    return OracleDatabase(server_name, database_name, user, pw_needed, port, encoding, password=password)
 
 
 def db_Firebird(
@@ -129,8 +151,10 @@ def db_Firebird(
     pw_needed: bool = True,
     port: int | None = None,
     encoding: str | None = None,
+    password: str | None = None,
 ) -> FirebirdDatabase:
-    return FirebirdDatabase(server_name, database_name, user, pw_needed, port, encoding)
+    """Open a Firebird database connection via the firebird-driver package."""
+    return FirebirdDatabase(server_name, database_name, user, pw_needed, port, encoding, password=password)
 
 
 def db_Dsn(
@@ -138,5 +162,7 @@ def db_Dsn(
     user: str | None = None,
     pw_needed: bool = True,
     encoding: str | None = None,
+    password: str | None = None,
 ) -> DsnDatabase:
-    return DsnDatabase(dsn_name=dsn_name, user_name=user, need_passwd=pw_needed, encoding=encoding)
+    """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, password=password)

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,