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

execsql/exporters/pretty.py

@@ -16,6 +16,8 @@ from execsql.exceptions import ErrInfo
 from execsql.utils.errors import exception_desc
 from execsql.utils.fileio import filewriter_close
 
+__all__ = ["prettyprint_query", "prettyprint_rowset"]
+
 
 def prettyprint_rowset(
     colhdrs: list[str],
@@ -26,6 +28,8 @@ def prettyprint_rowset(
     desc: str | None = None,
     zipfile: str | None = None,
 ) -> None:
+    """Format a pre-fetched result set as a fixed-width human-readable text table and write it."""
+
     # Adapted from the pp() function by Aaron Watters,
     # posted to gadfly-rdbms@egroups.com 1999-01-18.
     def as_ucode(s):
@@ -97,6 +101,7 @@ def prettyprint_query(
     desc: str | None = None,
     zipfile: str | None = None,
 ) -> None:
+    """Execute a SELECT and write the result set as a column-aligned text table."""
     _state.status.sql_error = False
     names, rows = db.select_data(select_stmt)
     prettyprint_rowset(names, rows, outfile, append, and_val, desc, zipfile=zipfile)

execsql/exporters/raw.py

@@ -9,11 +9,14 @@ used by the ``EXPORT … FORMAT raw`` and ``FORMAT b64`` metacommand
 variants.
 """
 
+import base64
 from typing import Any
 
 from execsql.exporters.zip import ZipWriter
 from execsql.utils.fileio import filewriter_close
 
+__all__ = ["write_query_raw", "write_query_b64"]
+
 
 def write_query_raw(
     outfile: str,
@@ -22,6 +25,7 @@ def write_query_raw(
     append: bool = False,
     zipfile: str | None = None,
 ) -> None:
+    """Write raw binary column data from a row source directly to a file or ZIP archive."""
     if zipfile is None:
         filewriter_close(outfile)
         mode = "wb" if not append else "ab"
@@ -43,9 +47,7 @@ def write_query_raw(
 
 
 def write_query_b64(outfile: str, rowsource: Any, append: bool = False, zipfile: str | None = None) -> None:
-    global base64
-    import base64
-
+    """Decode base64 column data from a row source and write the raw bytes to a file or ZIP archive."""
     if zipfile is None:
         filewriter_close(outfile)
         mode = "wb" if not append else "ab"

execsql/exporters/sqlite.py

@@ -14,6 +14,8 @@ from typing import Any
 from execsql.exceptions import ErrInfo
 from execsql.types import dbt_sqlite
 
+__all__ = ["export_sqlite", "write_query_to_sqlite"]
+
 
 def export_sqlite(
     outfile: str,
@@ -22,6 +24,7 @@ def export_sqlite(
     append: bool,
     tablename: str,
 ) -> None:
+    """Write pre-fetched rows to a table in an SQLite database file, creating it if necessary."""
     import sqlite3
 
     from execsql.models import DataTable
@@ -71,6 +74,7 @@ def write_query_to_sqlite(
     append: bool,
     tablename: str,
 ) -> None:
+    """Execute a SELECT and write the result set to a named table in an SQLite database."""
     from execsql.utils.errors import exception_desc
 
     try:

execsql/exporters/templates.py

@@ -9,6 +9,7 @@ substitution) and :func:`report_query`, which drives the
 variants.  The Jinja2 template processor is loaded lazily when selected.
 """
 
+import string
 from typing import Any
 
 import execsql.state as _state
@@ -16,14 +17,16 @@ from execsql.exceptions import ErrInfo
 from execsql.utils.errors import fatal_error
 from execsql.utils.fileio import filewriter_close
 
+__all__ = ["StrTemplateReport", "JinjaTemplateReport", "report_query"]
+
 
 class StrTemplateReport:
+    """Generates a report by applying Python's :class:`string.Template` to each row of a data table."""
+
     # Exporting/reporting using Python's default string.Template, iterated over all
     # rows of a data table.
     def __init__(self, template_file: str) -> None:
-        global string
-        import string
-
+        """Load and compile the template from the given file path."""
         conf = _state.conf
         self.infname = template_file
         from execsql.utils.fileio import EncodedFile
@@ -46,6 +49,7 @@ class StrTemplateReport:
         append: bool = False,
         zipfile: str | None = None,
     ) -> None:
+        """Render the template for each row in ``data_dict_rows`` and write the output."""
         conf = _state.conf
         from execsql.utils.fileio import EncodedFile
         from execsql.exporters.zip import ZipWriter
@@ -70,12 +74,16 @@ class StrTemplateReport:
 
 
 class JinjaTemplateReport:
+    """Generates a report by rendering a Jinja2 template against the full data table."""
+
     # Exporting/reporting using the Jinja2 templating library.
     def __init__(self, template_file: str) -> None:
-        global jinja2
+        """Load and compile the Jinja2 template from the given file path."""
         try:
             import jinja2
             from jinja2.sandbox import SandboxedEnvironment
+
+            self._jinja2 = jinja2
         except ImportError:
             fatal_error(
                 "The jinja2 library is required to produce reports with the Jinja2 templating system.   See http://jinja.pocoo.org/",
@@ -102,6 +110,7 @@ class JinjaTemplateReport:
         append: bool = False,
         zipfile: str | None = None,
     ) -> None:
+        """Render the Jinja2 template with ``headers`` and ``datatable`` context and write the output."""
         conf = _state.conf
         from execsql.utils.fileio import EncodedFile
         from execsql.exporters.zip import ZipWriter
@@ -119,9 +128,9 @@ class JinjaTemplateReport:
                 ofile = ZipWriter(zipfile, output_dest, append)
         try:
             ofile.write(self.template.render(headers=headers, datatable=data_dict_rows))
-        except jinja2.TemplateSyntaxError as e:
+        except self._jinja2.TemplateSyntaxError as e:
             raise ErrInfo("error", other_msg=e.message + f" on template line {e.lineno}") from e
-        except jinja2.TemplateError as e:
+        except self._jinja2.TemplateError as e:
             raise ErrInfo("error", other_msg=f"Jinja2 template error ({e.message})") from e
         finally:
             if output_dest != "stdout":
@@ -136,6 +145,7 @@ def report_query(
     append: bool = False,
     zipfile: str | None = None,
 ) -> None:
+    """Execute a SELECT and render the result set through a str-template or Jinja2 template file."""
     # Write (export) a template-based report.
     conf = _state.conf
     _state.status.sql_error = False

execsql/exporters/values.py

@@ -16,6 +16,8 @@ from execsql.exceptions import ErrInfo
 from execsql.utils.errors import exception_desc
 from execsql.utils.fileio import filewriter_close
 
+__all__ = ["export_values", "write_query_to_values"]
+
 
 def export_values(
     outfile: str,
@@ -25,6 +27,7 @@ def export_values(
     desc: str | None = None,
     zipfile: str | None = None,
 ) -> None:
+    """Write pre-fetched rows as SQL INSERT … VALUES statements to a file or ZIP archive."""
     conf = _state.conf
     if outfile.lower() == "stdout":
         f = _state.output
@@ -70,6 +73,7 @@ def write_query_to_values(
     desc: str | None = None,
     zipfile: str | None = None,
 ) -> None:
+    """Execute a SELECT and write the result set as SQL INSERT … VALUES statements."""
     try:
         hdrs, rows = db.select_rowsource(select_stmt)
     except ErrInfo:

execsql/exporters/xls.py

@@ -16,8 +16,12 @@ from typing import Any
 from execsql.exceptions import XlsFileError, XlsxFileError
 from execsql.utils.errors import fatal_error
 
+__all__ = ["XlsFile", "XlsxFile"]
+
 
 class XlsFile:
+    """Read-only wrapper around ``xlrd`` for importing legacy ``.xls`` spreadsheets."""
+
     def __repr__(self) -> str:
         return "XlsFile()"
 
@@ -29,9 +33,11 @@ class XlsFile:
             self.log_msgs.append(msg)
 
     def __init__(self) -> None:
+        """Import xlrd and initialise file state; raises a fatal error if xlrd is absent."""
         try:
-            global xlrd
             import xlrd
+
+            self._xlrd = xlrd
         except ImportError:
             fatal_error("The xlrd library is needed to read Excel (.xls) spreadsheets.")
         self.filename = None
@@ -41,20 +47,23 @@ class XlsFile:
         self.errlog = self.XlsLog()
 
     def open(self, filename: str, encoding: str | None = None, read_only: bool = False) -> None:
+        """Open an existing ``.xls`` file for reading; raises XlsFileError if absent."""
         self.filename = filename
         self.encoding = encoding
         self.read_only = read_only
         if Path(filename).is_file():
             # The 'read_only' argument is not used, but is present for compatibility with XlsxFile.open().
-            self.wbk = xlrd.open_workbook(filename, logfile=self.errlog, encoding_override=self.encoding)
+            self.wbk = self._xlrd.open_workbook(filename, logfile=self.errlog, encoding_override=self.encoding)
             self.datemode = self.wbk.datemode
         else:
             raise XlsFileError(f"There is no Excel file {self.filename}.")
 
     def sheetnames(self) -> Any:
+        """Return the list of sheet objects in the open workbook."""
         return self.wbk.sheets()
 
     def sheet_named(self, sheetname: Any) -> Any:
+        """Return the sheet matching a name or 1-based integer, raising XlsFileError if absent."""
         # Return the sheet with the matching name.  If the name is actually an integer,
         # return that sheet number.
         if isinstance(sheetname, int):
@@ -74,6 +83,7 @@ class XlsFile:
         return sheet
 
     def sheet_data(self, sheetname: Any, junk_header_rows: int = 0) -> list:
+        """Return all row data from the named sheet, optionally skipping leading junk rows."""
         try:
             sheet = self.sheet_named(sheetname)
         except Exception as e:
@@ -109,7 +119,7 @@ class XlsFile:
                         datarow.append(c.value)
                 elif c.ctype == 3:
                     # date
-                    dt = xlrd.xldate_as_tuple(c.value, self.datemode)
+                    dt = self._xlrd.xldate_as_tuple(c.value, self.datemode)
                     # Convert to time or datetime
                     if not any(dt[:3]):
                         # No date values
@@ -121,7 +131,7 @@ class XlsFile:
                     datarow.append(bool(c.value))
                 elif c.ctype == 5:
                     # Error code
-                    datarow.append(xlrd.error_text_from_code(c.value))
+                    datarow.append(self._xlrd.error_text_from_code(c.value))
                 elif c.ctype == 6:
                     # blank
                     datarow.append(None)
@@ -145,6 +155,8 @@ class XlsFile:
 
 
 class XlsxFile:
+    """Read/write wrapper around ``openpyxl`` for ``.xlsx`` spreadsheets."""
+
     def __repr__(self) -> str:
         return "XlsxFile()"
 
@@ -156,9 +168,11 @@ class XlsxFile:
             self.log_msgs.append(msg)
 
     def __init__(self) -> None:
+        """Import openpyxl and initialise file state; raises a fatal error if openpyxl is absent."""
         try:
-            global openpyxl
             import openpyxl
+
+            self._openpyxl = openpyxl
         except ImportError:
             fatal_error("The openpyxl library is needed to read Excel (.xlsx) spreadsheets.")
         self.filename = None
@@ -168,18 +182,20 @@ class XlsxFile:
         self.errlog = self.XlsxLog()
 
     def open(self, filename: str, encoding: str | None = None, read_only: bool = False) -> None:
+        """Open an existing ``.xlsx`` file for reading; raises XlsxFileError if absent."""
         self.filename = filename
         self.encoding = encoding
         self.read_only = read_only
         if Path(filename).is_file():
             if read_only:
-                self.wbk = openpyxl.load_workbook(filename, read_only=True)
+                self.wbk = self._openpyxl.load_workbook(filename, read_only=True)
             else:
-                self.wbk = openpyxl.load_workbook(filename)
+                self.wbk = self._openpyxl.load_workbook(filename)
         else:
             raise XlsxFileError(f"There is no Excel file {self.filename}.")
 
     def close(self) -> None:
+        """Close the open workbook and reset all state attributes."""
         if self.wbk is not None:
             self.wbk.close()
             self.wbk = None
@@ -187,9 +203,11 @@ class XlsxFile:
             self.encoding = None
 
     def sheetnames(self) -> list[str]:
+        """Return the list of worksheet names in the open workbook."""
         return self.wbk.sheetnames
 
     def sheet_named(self, sheetname: Any) -> Any:
+        """Return the sheet matching a name or 1-based integer index."""
         # Return the sheet with the matching name.  If the name is actually an integer,
         # return that sheet number.
         if isinstance(sheetname, int):
@@ -209,6 +227,7 @@ class XlsxFile:
         return sheet
 
     def sheet_data(self, sheetname: Any, junk_header_rows: int = 0) -> list:
+        """Return all row data from the named sheet, optionally skipping leading junk rows."""
         try:
             sheet = self.sheet_named(sheetname)
         except Exception as e:

execsql/exporters/xml.py

@@ -18,6 +18,8 @@ from execsql.exceptions import ErrInfo
 from execsql.utils.errors import exception_desc
 from execsql.utils.fileio import filewriter_close
 
+__all__ = ["write_query_to_xml"]
+
 
 def write_query_to_xml(
     select_stmt: str,
@@ -28,6 +30,7 @@ def write_query_to_xml(
     desc: str | None = None,
     zipfile: str | None = None,
 ) -> None:
+    """Execute a SELECT and write the result set as a well-formed XML document."""
     conf = _state.conf
     try:
         hdrs, rows = db.select_rowsource(select_stmt)

execsql/exporters/zip.py

@@ -15,9 +15,14 @@ import zipfile
 
 import execsql.state as _state
 
+__all__ = ["WriteableZipfile", "ZipWriter"]
+
 
 class WriteableZipfile:
+    """Thin ZipFile wrapper that accepts chunked string writes via an internal buffer."""
+
     def __init__(self, zipfile_name: str, append: bool = False) -> None:
+        """Open (or create) a ZIP archive and allocate a write buffer."""
         conf = _state.conf
         self.bufsize = conf.zip_buffer_mb * 1024 * 1000
         self.buf = memoryview(bytearray(self.bufsize))
@@ -31,6 +36,7 @@ class WriteableZipfile:
         self.close()
 
     def member_file(self, member_filename: str) -> None:
+        """Create a new member entry in the archive and open it for writing."""
         # Creates a ZipInfo object (file) within the zipfile and opens it for writing.
         self.current_zinfo = zipfile.ZipInfo(
             filename=member_filename,
@@ -49,6 +55,7 @@ class WriteableZipfile:
         self.current_handle = self.zf.open(self.current_zinfo, mode="w")
 
     def zip_buffer(self) -> None:
+        """Flush any buffered bytes to the currently open zip member file."""
         # Writes the buffer contents, if any, to the zip member file.
         if self.buflen > 0 and self.current_handle is not None:
             with self.zf._lock:
@@ -57,6 +64,7 @@ class WriteableZipfile:
             self.buflen = 0
 
     def write(self, str_data: str) -> None:
+        """Buffer a UTF-8-encoded string for writing to the currently open member."""
         # Writes the given text to the currently open member.
         # Convert from string to bytes.
         data = str_data.encode("utf-8")
@@ -67,26 +75,33 @@ class WriteableZipfile:
         self.buflen = self.buflen + datalen
 
     def close_member(self) -> None:
+        """Flush the buffer and close the currently open member file handle."""
         if self.current_handle is not None:
             self.zip_buffer()
             self.current_handle.close()
             self.current_handle = None
 
     def close(self) -> None:
+        """Close the open member (flushing the buffer) and finalise the ZIP archive."""
         self.close_member()
         self.zf.close()
 
 
 class ZipWriter:
+    """High-level write-only interface used by EXPORT metacommands to stream output into a ZIP archive."""
+
     def __init__(self, zip_fname: str, member_fname: str, append: bool = False) -> None:
+        """Open the archive at ``zip_fname`` and begin a new member file named ``member_fname``."""
         self.zip_fname = zip_fname
         self.member_fname = member_fname
         self.zwriter = WriteableZipfile(self.zip_fname, append)
         self.member = self.zwriter.member_file(member_fname)
 
     def write(self, str_data: str) -> None:
+        """Write a string to the current zip member."""
         self.zwriter.write(str_data)
 
     def close(self) -> None:
+        """Close the zip member and finalise the archive."""
         self.zwriter.close()
         self.zwriter = None

execsql/importers/base.py

@@ -17,6 +17,8 @@ from execsql.db.base import Database
 import execsql.state as _state
 from execsql.types import dbt_firebird
 
+__all__ = ["import_data_table"]
+
 
 def import_data_table(
     db: Database,
@@ -26,7 +28,7 @@ def import_data_table(
     hdrs: list[str],
     data: list[Any],
 ) -> None:
-    from execsql.utils.errors import exception_info
+    from execsql.utils.errors import exception_desc
 
     conf = _state.conf
     if any(x is None or len(x.strip()) == 0 for x in hdrs):
@@ -89,7 +91,7 @@ def import_data_table(
             raise ErrInfo(
                 type="db",
                 command_text=sql,
-                exception_msg=exception_info(),
+                exception_msg=exception_desc(),
                 other_msg=f"Could not create new table ({tablename}) for IMPORT metacommand",
             ) from e
     table_cols = db.table_columns(tablename, schemaname)
@@ -109,4 +111,4 @@ def import_data_table(
     except ErrInfo:
         raise
     except Exception as e:
-        raise ErrInfo("db", "Call to populate_table when importing data", exception_msg=exception_info()) from e
+        raise ErrInfo("db", "Call to populate_table when importing data", exception_msg=exception_desc()) from e

execsql/importers/csv.py

@@ -17,6 +17,8 @@ from execsql.db.base import Database
 import execsql.state as _state
 from execsql.types import dbt_firebird
 
+__all__ = ["importfile", "importtable"]
+
 
 def importtable(
     db: Database,
@@ -30,7 +32,7 @@ def importtable(
     encoding: str | None = None,
     junk_header_lines: int = 0,
 ) -> None:
-    from execsql.utils.errors import exception_info
+    from execsql.utils.errors import exception_desc
 
     conf = _state.conf
     if not Path(filename).is_file():
@@ -64,7 +66,7 @@ def importtable(
             raise ErrInfo(
                 type="db",
                 command_text=sql,
-                exception_msg=exception_info(),
+                exception_msg=exception_desc(),
                 other_msg=f"Could not create new table ({tablename}) for IMPORT metacommand",
             ) from e
     else:
@@ -89,7 +91,7 @@ def importtable(
         fq_tablename = db.schema_qualified_table_name(schemaname, tablename)
         raise ErrInfo(
             "exception",
-            exception_msg=exception_info(),
+            exception_msg=exception_desc(),
             other_msg=f"Can't import tabular file ({filename}) to table ({fq_tablename})",
         ) from e
     inf.close()
@@ -102,7 +104,7 @@ def importfile(
     columname: str,
     filename: str,
 ) -> None:
-    from execsql.utils.errors import exception_info
+    from execsql.utils.errors import exception_desc
 
     if schemaname is not None:
         if not db.table_exists(tablename, schemaname):
@@ -125,6 +127,6 @@ def importfile(
         fq_tablename = db.schema_qualified_table_name(schemaname, tablename)
         raise ErrInfo(
             "exception",
-            exception_msg=exception_info(),
+            exception_msg=exception_desc(),
             other_msg=f"Can't import file ({filename}) to table ({fq_tablename})",
         ) from e

execsql/importers/feather.py

@@ -14,6 +14,8 @@ from execsql.exceptions import ErrInfo
 from execsql.db.base import Database
 from execsql.importers.base import import_data_table
 
+__all__ = ["import_feather", "import_parquet"]
+
 
 def import_feather(
     db: Database,
@@ -22,14 +24,14 @@ def import_feather(
     filename: str,
     is_new: Any,
 ) -> None:
-    from execsql.utils.errors import exception_info
+    from execsql.utils.errors import exception_desc
 
     try:
         import polars as pl
     except Exception as e:
         raise ErrInfo(
             "exception",
-            exception_msg=exception_info(),
+            exception_msg=exception_desc(),
             other_msg="The polars Python library must be installed to import data from the Feather format.",
         ) from e
     df = pl.read_ipc(filename)
@@ -45,14 +47,14 @@ def import_parquet(
     filename: str,
     is_new: Any,
 ) -> None:
-    from execsql.utils.errors import exception_info
+    from execsql.utils.errors import exception_desc
 
     try:
         import polars as pl
     except Exception as e:
         raise ErrInfo(
             "exception",
-            exception_msg=exception_info(),
+            exception_msg=exception_desc(),
             other_msg="The polars Python library must be installed to import data from the Parquet format.",
         ) from e
     df = pl.read_parquet(filename)

execsql/importers/ods.py

@@ -17,6 +17,8 @@ from execsql.exporters.ods import OdsFile
 from execsql.importers.base import import_data_table
 import execsql.state as _state
 
+__all__ = ["importods", "ods_data"]
+
 
 def ods_data(
     filename: str,

execsql/importers/xls.py

@@ -16,6 +16,8 @@ from execsql.db.base import Database
 from execsql.importers.base import import_data_table
 import execsql.state as _state
 
+__all__ = ["importxls", "xls_data"]
+
 
 def xls_data(
     filename: str,