execsql2 2.4.5__py3-none-any.whl → 2.6.0__py3-none-any.whl

execsql/db/sqlite.py

@@ -50,6 +50,7 @@ class SQLiteDatabase(Database):
         return f"SQLiteDatabase({self.db_name!r})"
 
     def open_db(self) -> None:
+        """Open a connection to the SQLite database file."""
         import sqlite3
 
         if self.conn is None:
@@ -67,18 +68,20 @@ class SQLiteDatabase(Database):
         self.encoding = pragma_data[0][0]
 
     def exec_cmd(self, querycommand: str) -> None:
+        """Execute a query command as a view selection, since SQLite lacks stored procedures."""
         # SQLite does not support stored functions or views, so the querycommand
         # is treated as (and therefore must be) a view.
-        curs = self.cursor()
-        cmd = f"select * from {querycommand};"
-        try:
-            curs.execute(cmd.encode(self.encoding))
-            _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)
-        except Exception:
-            self.rollback()
-            raise
+        with self._cursor() as curs:
+            cmd = f"select * from {querycommand};"
+            try:
+                curs.execute(cmd.encode(self.encoding))
+                _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)
+            except Exception:
+                self.rollback()
+                raise
 
     def table_exists(self, table_name: str, schema_name: str | None = None) -> bool:
+        """Return True if the named table exists in the SQLite database."""
         curs = self.cursor()
         sql = "select name from sqlite_master where type='table' and name=?;"
         try:
@@ -102,10 +105,12 @@ class SQLiteDatabase(Database):
         column_name: str,
         schema_name: str | None = None,
     ) -> bool:
+        """Return True if the named column exists in the given SQLite table."""
         cols = self.table_columns(table_name, schema_name)
         return column_name in cols
 
     def table_columns(self, table_name: str, schema_name: str | None = None) -> list[str]:
+        """Return a list of column names for the given SQLite table."""
         curs = self.cursor()
         quoted_tbl = self.quote_identifier(table_name)
         sql = f"select * from {quoted_tbl} where 1=0;"
@@ -124,6 +129,7 @@ class SQLiteDatabase(Database):
         return [d[0] for d in curs.description]
 
     def view_exists(self, view_name: str) -> bool:
+        """Return True if the named view exists in the SQLite database."""
         curs = self.cursor()
         sql = "select name from sqlite_master where type='view' and name=?;"
         try:
@@ -142,9 +148,11 @@ class SQLiteDatabase(Database):
         return len(rows) > 0
 
     def schema_exists(self, schema_name: str) -> bool:
+        """Return False; SQLite does not support schemas."""
         return False
 
     def drop_table(self, tablename: str) -> None:
+        """Drop the named table from the SQLite database if it exists."""
         tablename = self.type.quoted(tablename)
         self.execute(f"drop table if exists {tablename};")
 
@@ -156,6 +164,7 @@ class SQLiteDatabase(Database):
         column_list: list[str],
         tablespec_src: Any,
     ) -> None:
+        """Populate a SQLite table from a row source generator."""
         # 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 in the same order as produced by the rowsource.
         sq_name = self.schema_qualified_table_name(None, table_name)
@@ -233,6 +242,7 @@ class SQLiteDatabase(Database):
         column_name: str,
         file_name: str,
     ) -> None:
+        """Import an entire binary file into a single column of a table."""
         import sqlite3
 
         with open(file_name, "rb") as f:

execsql/db/sqlserver.py

@@ -58,6 +58,7 @@ class SqlServerDatabase(Database):
         )
 
     def open_db(self) -> None:
+        """Open a connection to the SQL Server database via pyodbc."""
         import pyodbc
 
         if self.conn is None:
@@ -138,17 +139,19 @@ class SqlServerDatabase(Database):
             self.conn.commit()
 
     def exec_cmd(self, querycommand: str) -> None:
+        """Execute a stored procedure by name."""
         # The querycommand must be a stored procedure
-        curs = self.cursor()
-        cmd = f"execute {querycommand};"
-        try:
-            curs.execute(cmd.encode(self.encoding))
-            _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)
-        except Exception:
-            self.rollback()
-            raise
+        with self._cursor() as curs:
+            cmd = f"execute {querycommand};"
+            try:
+                curs.execute(cmd.encode(self.encoding))
+                _state.subvars.add_substitution("$LAST_ROWCOUNT", curs.rowcount)
+            except Exception:
+                self.rollback()
+                raise
 
     def schema_exists(self, schema_name: str) -> bool:
+        """Return True if the named schema exists in the SQL Server database."""
         curs = self.cursor()
         curs.execute("select * from sys.schemas where name = ?;", (schema_name,))
         rows = curs.fetchall()
@@ -156,6 +159,7 @@ class SqlServerDatabase(Database):
         return len(rows) > 0
 
     def role_exists(self, rolename: str) -> bool:
+        """Return True if the named role or principal exists in the SQL Server database."""
         curs = self.cursor()
         curs.execute(
             "select name from sys.database_principals where type in ('R', 'S') and name = ?;",
@@ -166,6 +170,7 @@ class SqlServerDatabase(Database):
         return len(rows) > 0
 
     def drop_table(self, tablename: str) -> None:
+        """Drop the named table from the SQL Server database."""
         # SQL Server and Firebird will throw an error if there are foreign keys to the table.
         tablename = self.type.quoted(tablename)
         self.execute(f"drop table {tablename};")
@@ -177,6 +182,7 @@ class SqlServerDatabase(Database):
         column_name: str,
         file_name: str,
     ) -> None:
+        """Import an entire binary file into a single column of a table."""
         import pyodbc
 
         with open(file_name, "rb") as f:

execsql/exporters/__init__.py

@@ -10,5 +10,10 @@ importing directly from here.
 
 Sub-modules: ``base``, ``delimited``, ``json``, ``xml``, ``html``,
 ``latex``, ``ods``, ``xls``, ``zip``, ``raw``, ``pretty``, ``values``,
-``templates``, ``feather``, ``parquet``, ``duckdb``, ``sqlite``.
+``templates``, ``feather``, ``parquet``, ``duckdb``, ``sqlite``,
+``protocol``.
 """
+
+from execsql.exporters.protocol import QueryExporter, RowsetExporter
+
+__all__ = ["QueryExporter", "RowsetExporter"]

execsql/exporters/base.py

@@ -39,6 +39,7 @@ class ExportRecord:
         zipfile: str | None = None,
         description: str | None = None,
     ) -> None:
+        """Record export details for the given query name and output file."""
         self.exported = False
         # Record is a list of: table_or_query_name, filename, zipfilename, file_path, user_description, script_name,
         # script_path, script_line_no, script_datetime, database_name, database_server, user_name.
@@ -87,6 +88,7 @@ class ExportMetadata:
     ]
 
     def __init__(self) -> None:
+        """Initialise an empty record collection."""
         self.recordlist: list[ExportRecord] = []
 
     def add(self, exp_record: ExportRecord) -> None:

execsql/exporters/delimited.py

@@ -118,6 +118,7 @@ class CsvWriter:
         escchar: str | None,
         append: bool = False,
     ) -> None:
+        """Open a file and prepare a delimited writer with the given format settings."""
         mode = "wt" if not append else "at"
         if filename.lower() == "stdout":
             self.output = sys.stdout
@@ -184,9 +185,12 @@ class CsvFile(EncodedFile):
         self.lineformat_set = True
 
     class CsvLine:
+        """Represent a single CSV line for delimiter diagnosis and parsing."""
+
         escchar = "\\"
 
         def __init__(self, line_text: str) -> None:
+            """Store the raw line text and prepare delimiter-count storage."""
             self.text = line_text
             self.delim_counts = {}
             self.item_errors = []  # A list of error messages.
@@ -202,6 +206,7 @@ class CsvFile(EncodedFile):
             )
 
         def count_delim(self, delim: str) -> None:
+            """Count occurrences of the given delimiter in the line text."""
             # If the delimiter is a space, consider multiple spaces to be equivalent
             # to a single delimiter, split on the space(s), and consider the delimiter
             # count to be one fewer than the items returned.
@@ -211,6 +216,7 @@ class CsvFile(EncodedFile):
                 self.delim_counts[delim] = self.text.count(delim)
 
         def delim_count(self, delim: str) -> int:
+            """Return the previously counted occurrence total for the given delimiter."""
             return self.delim_counts[delim]
 
         def _well_quoted(self, element: str, qchar: str):
@@ -239,9 +245,11 @@ class CsvFile(EncodedFile):
             return (False, True, False)
 
         def record_format_error(self, pos_no: int, errmsg: str) -> None:
+            """Append a parse error message annotated with its character position."""
             self.item_errors.append(f"{errmsg} in position {pos_no}.")
 
         def items(self, delim: str | None, qchar: str | None) -> Any:
+            """Parse the line into a list of items, splitting on unquoted delimiters."""
             # Parses the line into a list of items, breaking it at delimiters that are not
             # within quoted stretches.
             self.item_errors = []
@@ -348,6 +356,7 @@ class CsvFile(EncodedFile):
             return elements
 
         def well_quoted_line(self, delim: str | None, qchar: str | None):
+            """Return a tuple of (all-well-quoted, quote-usage-count, uses-escape-char)."""
             # Returns a tuple of boolean, int, and boolean
             wq = [self._well_quoted(el, qchar) for el in self.items(delim, qchar)]
             return (all(b[0] for b in wq), sum([b[1] for b in wq]), any(b[2] for b in wq))
@@ -358,6 +367,7 @@ class CsvFile(EncodedFile):
         possible_delimiters: list[str] | None = None,
         possible_quotechars: list[str] | None = None,
     ):
+        """Analyse a line stream and return the detected (delimiter, quote char, escape char) tuple."""
         # Returns a tuple consisting of the delimiter, quote character, and escape
         # character for quote characters within elements of a line.  All may be None.
         conf = _state.conf

execsql/exporters/protocol.py

@@ -0,0 +1,128 @@
+"""
+Exporter Protocol definitions for execsql.
+
+Defines two ``@runtime_checkable`` Protocols that describe the two main
+exporter calling conventions used throughout the ``exporters`` package:
+
+- :class:`QueryExporter` — functions that accept a SQL SELECT statement
+  and a database connection, execute the query, and write the results.
+- :class:`RowsetExporter` — functions that accept pre-fetched column
+  headers and rows and write them to an output destination.
+
+These Protocols capture the *most common* parameter signature.  Several
+concrete exporters have additional keyword arguments (``tablename``,
+``sheetname``, ``template_file``, ``write_types``, ``and_val``, etc.)
+that extend the base contract.  Such functions remain structurally
+compatible: they satisfy the Protocol when called with the base
+arguments, and the extra parameters have defaults or are supplied by
+the dispatch layer.
+
+.. note::
+
+   The ``io_export.py`` dispatch chain is **not** refactored here.
+   These Protocols exist as a documentation and static-type-checking
+   layer that formalises the implicit interface already present in the
+   codebase.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+__all__ = ["QueryExporter", "RowsetExporter"]
+
+
+@runtime_checkable
+class QueryExporter(Protocol):
+    """Protocol for exporters that execute a query and write output.
+
+    The canonical signature is::
+
+        def __call__(
+            self,
+            select_stmt: str,
+            db: Any,
+            outfile: str,
+            append: bool = False,
+            desc: str | None = None,
+            zipfile: str | None = None,
+        ) -> None: ...
+
+    Conforming functions
+    --------------------
+    - ``write_query_to_json``
+    - ``write_query_to_html``
+    - ``write_query_to_cgi_html``
+    - ``write_query_to_latex``
+    - ``write_query_to_values``
+    - ``prettyprint_query`` (adds ``and_val``)
+
+    Functions with extended signatures
+    ----------------------------------
+    - ``write_query_to_xml`` (adds ``tablename``)
+    - ``write_query_to_json_ts`` (adds ``write_types``)
+    - ``write_query_to_ods`` (adds ``sheetname``, no ``zipfile``)
+    - ``write_query_to_hdf5`` (adds ``table_name``, no ``zipfile``)
+    - ``write_query_to_duckdb`` (adds ``tablename``, no ``desc``/``zipfile``)
+    - ``write_query_to_sqlite`` (adds ``tablename``, no ``desc``/``zipfile``)
+    - ``report_query`` (adds ``template_file``)
+    - ``write_queries_to_ods`` (``table_list`` instead of ``select_stmt``)
+    """
+
+    def __call__(
+        self,
+        select_stmt: str,
+        db: Any,
+        outfile: str,
+        append: bool = False,
+        desc: str | None = None,
+        zipfile: str | None = None,
+    ) -> None: ...
+
+
+@runtime_checkable
+class RowsetExporter(Protocol):
+    """Protocol for exporters that accept pre-fetched headers and rows.
+
+    The canonical signature is::
+
+        def __call__(
+            self,
+            outfile: str,
+            hdrs: list[str],
+            rows: Any,
+            append: bool = False,
+            desc: str | None = None,
+            zipfile: str | None = None,
+        ) -> None: ...
+
+    Conforming functions
+    --------------------
+    - ``export_values``
+
+    Functions with extended signatures
+    ----------------------------------
+    - ``export_html`` (adds ``querytext``)
+    - ``export_cgi_html`` (adds ``querytext``)
+    - ``export_latex`` (adds ``querytext``)
+    - ``export_ods`` (adds ``querytext``, ``sheetname``, no ``zipfile``)
+    - ``prettyprint_rowset`` (uses ``colhdrs``/``output_dest``, adds ``and_val``)
+    - ``export_duckdb`` (adds ``tablename``, no ``desc``/``zipfile``)
+    - ``export_sqlite`` (adds ``tablename``, no ``desc``/``zipfile``)
+    - ``write_query_to_feather`` (minimal: ``outfile``, ``headers``, ``rows`` only)
+    - ``write_query_to_parquet`` (minimal: ``outfile``, ``headers``, ``rows`` only)
+    - ``write_query_raw`` (uses ``rowsource`` + ``db_encoding``)
+    - ``write_query_b64`` (uses ``rowsource`` only)
+    - ``write_delimited_file`` (uses ``filefmt``, ``column_headers``, ``rowsource``,
+      ``file_encoding``)
+    """
+
+    def __call__(
+        self,
+        outfile: str,
+        hdrs: list[str],
+        rows: Any,
+        append: bool = False,
+        desc: str | None = None,
+        zipfile: str | None = None,
+    ) -> None: ...

execsql/exporters/xls.py

@@ -26,10 +26,14 @@ class XlsFile:
         return "XlsFile()"
 
     class XlsLog:
+        """Capture xlrd warning messages as a list of strings."""
+
         def __init__(self) -> None:
+            """Initialise an empty message list."""
             self.log_msgs = []
 
         def write(self, msg: str) -> None:
+            """Append a log message to the internal list."""
             self.log_msgs.append(msg)
 
     def __init__(self) -> None:
@@ -161,10 +165,14 @@ class XlsxFile:
         return "XlsxFile()"
 
     class XlsxLog:
+        """Capture openpyxl warning messages as a list of strings."""
+
         def __init__(self) -> None:
+            """Initialise an empty message list."""
             self.log_msgs = []
 
         def write(self, msg: str) -> None:
+            """Append a log message to the internal list."""
             self.log_msgs.append(msg)
 
     def __init__(self) -> None:

execsql/format.py

@@ -19,6 +19,8 @@ from pathlib import Path
 import sqlglot
 import sqlglot.errors
 
+__all__ = ["collect_paths", "format_file", "main", "parse_keyword"]
+
 # ---------------------------------------------------------------------------
 # Constants
 # ---------------------------------------------------------------------------
@@ -345,7 +347,7 @@ def main() -> None:
                 source = path.read_text(encoding="utf-8")
             except OSError as exc:
                 _err_console.print(f"[bold red]Error:[/bold red] reading {path}: {exc}")
-                raise typer.Exit(code=1)
+                raise typer.Exit(code=1) from None
 
             formatted = format_file(source, indent=indent, use_sql=use_sql)
 

execsql/gui/__init__.py

@@ -21,6 +21,8 @@ from typing import TYPE_CHECKING, Any
 if TYPE_CHECKING:
     from execsql.gui.base import GuiBackend
 
+__all__ = ["get_backend", "gui_manager_loop"]
+
 
 def get_backend(framework: str = "tkinter") -> GuiBackend:
     """Return the best available backend for *framework*.

execsql/gui/base.py

@@ -8,6 +8,8 @@ from typing import TYPE_CHECKING, Any
 if TYPE_CHECKING:
     pass
 
+__all__ = ["GuiBackend"]
+
 
 class GuiBackend(ABC):
     """Abstract base for all GUI backends.

execsql/gui/console.py

@@ -13,6 +13,8 @@ from typing import Any
 
 from execsql.gui.base import GuiBackend
 
+__all__ = ["ConsoleBackend"]
+
 
 def _print_table(headers: list, rows: list, file: Any = None) -> None:
     """Print a simple ASCII table to the given file (default stderr)."""

execsql/gui/desktop.py

@@ -27,6 +27,7 @@ except ImportError as _e:
         "tkinter is not available on this Python installation.",
     ) from _e
 
+__all__ = ["TkinterBackend"]
 
 # ---------------------------------------------------------------------------
 # Helpers