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

execsql/exporters/ods.py

@@ -23,20 +23,25 @@ from execsql.utils.errors import exception_desc, fatal_error
 from execsql.utils.fileio import filewriter_close
 from execsql.utils.strings import unquoted
 
+__all__ = ["OdsFile", "export_ods", "write_query_to_ods", "write_queries_to_ods"]
+
 
 class OdsFile:
+    """Wrapper around the ``odfpy`` library for reading and writing OpenDocument Spreadsheet files."""
+
     def __repr__(self) -> str:
         return "OdsFile()"
 
     def __init__(self) -> None:
+        """Import odfpy and initialise the workbook state."""
         global of
         try:
-            import of as of
-            import of.opendocument
-            import of.table
-            import of.text
-            import of.number
-            import of.style
+            import odf as of  # noqa: F401 — submodule imports below register on the `of` alias
+            import odf.opendocument  # noqa: F401
+            import odf.table  # noqa: F401
+            import odf.text  # noqa: F401
+            import odf.number  # noqa: F401
+            import odf.style  # noqa: F401
         except ImportError:
             fatal_error("The odfpy library is needed to create OpenDocument spreadsheets.")
         self.filename = None
@@ -44,6 +49,7 @@ class OdsFile:
         self.cell_style_names = []
 
     def open(self, filename: str) -> None:
+        """Open an existing ODS file or create a new one at the given path."""
         self.filename = filename
         if Path(filename).is_file():
             self.wbk = of.opendocument.load(filename)
@@ -61,6 +67,7 @@ class OdsFile:
             self.wbk = of.opendocument.OpenDocumentSpreadsheet()
 
     def define_body_style(self) -> None:
+        """Register the ``body`` cell style in the workbook if not already defined."""
         st_name = "body"
         if st_name not in self.cell_style_names:
             body_style = of.style.Style(name=st_name, family="table-cell")
@@ -69,6 +76,7 @@ class OdsFile:
             self.cell_style_names.append(st_name)
 
     def define_header_style(self) -> None:
+        """Register the ``header`` cell style (bottom-bordered) in the workbook if not already defined."""
         st_name = "header"
         if st_name not in self.cell_style_names:
             header_style = of.style.Style(name=st_name, family="table-cell")
@@ -84,6 +92,7 @@ class OdsFile:
             self.cell_style_names.append(st_name)
 
     def define_iso_datetime_style(self) -> None:
+        """Register an ISO-8601 datetime number style in the workbook if not already defined."""
         st_name = "iso_datetime"
         if st_name not in self.cell_style_names:
             dt_style = of.number.DateStyle(name="iso-datetime")
@@ -110,6 +119,7 @@ class OdsFile:
             self.cell_style_names.append(st_name)
 
     def define_iso_date_style(self) -> None:
+        """Register an ISO-8601 date number style in the workbook if not already defined."""
         st_name = "iso_date"
         if st_name not in self.cell_style_names:
             dt_style = of.number.DateStyle(name="iso-date")
@@ -125,10 +135,12 @@ class OdsFile:
             self.cell_style_names.append(st_name)
 
     def sheetnames(self) -> list[str]:
+        """Return a list of worksheet names in the open workbook."""
         # Returns a list of the worksheet names in the specified ODS spreadsheet.
         return [sheet.getAttribute("name") for sheet in self.wbk.spreadsheet.getElementsByType(of.table.Table)]
 
     def sheet_named(self, sheetname: Any) -> Any:
+        """Return the sheet matching a name or 1-based integer index, or ``None`` if not found."""
         # Return the sheet with the matching name.  If the name is actually an integer,
         # return that sheet number.
         if isinstance(sheetname, int):
@@ -153,6 +165,7 @@ class OdsFile:
         return None
 
     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."""
         sheet = self.sheet_named(sheetname)
         if not sheet:
             raise OdsFileError(f"There is no sheet named {sheetname}")
@@ -195,10 +208,12 @@ class OdsFile:
         return [row_data(r) for r in rows]
 
     def new_sheet(self, sheetname: str) -> Any:
+        """Create and return a detached sheet object that can later be added to the workbook."""
         # Returns a sheet (a named Table) that has not yet been added to the workbook
         return of.table.Table(name=sheetname)
 
     def add_row_to_sheet(self, datarow: Any, of_table: Any, header: bool = False) -> None:
+        """Append a data row to an ODS table, applying header or body cell styles as appropriate."""
         if header:
             self.define_header_style()
             style_name = "header"
@@ -211,7 +226,7 @@ class OdsFile:
             if isinstance(item, bool):
                 # Booleans must be evaluated before numbers.
                 tc = of.table.TableCell(valuetype="boolean", value=1 if item else 0, stylename=style_name)
-            elif isinstance(item, (float, int)):
+            elif isinstance(item, float | int):
                 tc = of.table.TableCell(valuetype="float", value=item, stylename=style_name)
             elif isinstance(item, datetime.datetime):
                 self.define_iso_datetime_style()
@@ -247,15 +262,18 @@ class OdsFile:
             tr.addElement(tc)
 
     def add_sheet(self, of_table: Any) -> None:
+        """Attach a prepared sheet object to the workbook's spreadsheet element."""
         self.wbk.spreadsheet.addElement(of_table)
 
     def save_close(self) -> None:
+        """Serialise the workbook to disk and release all resources."""
         with open(self.filename, "wb") as ofile:
             self.wbk.write(ofile)
         self.filename = None
         self.wbk = None
 
     def close(self) -> None:
+        """Release the workbook reference without saving."""
         self.filename = None
         self.wbk = None
 
@@ -269,6 +287,7 @@ def export_ods(
     sheetname: str | None = None,
     desc: str | None = None,
 ) -> None:
+    """Write a single-sheet ODS file from pre-fetched column headers and rows."""
     # If not given, determine the worksheet name to use.  The pattern is "Sheetx", where x is
     # the first integer for which there is not already a sheet name.
     if append and Path(outfile).is_file():
@@ -338,12 +357,13 @@ def write_query_to_ods(
     sheetname: str | None = None,
     desc: str | None = None,
 ) -> None:
+    """Execute a SELECT and write the result set as a single-sheet ODS spreadsheet."""
     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_ods(outfile, hdrs, rows, append, select_stmt, sheetname, desc)
 
 
@@ -355,6 +375,7 @@ def write_queries_to_ods(
     tee: bool = False,
     desc: str | None = None,
 ) -> None:
+    """Write multiple tables/queries to separate sheets in a single ODS workbook."""
     from execsql.exporters.pretty import prettyprint_query
     from execsql.exporters.base import ExportRecord
 
@@ -403,8 +424,8 @@ def write_queries_to_ods(
             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
         # Add the data to a new sheet.
         tbl = wbk.new_sheet(sheet_name)
         wbk.add_row_to_sheet(hdrs, tbl, header=True)

execsql/exporters/parquet.py

@@ -13,16 +13,19 @@ from execsql.exceptions import ErrInfo
 from execsql.utils.errors import exception_desc
 from execsql.utils.fileio import filewriter_close
 
+__all__ = ["write_query_to_parquet"]
+
 
 def write_query_to_parquet(outfile: str, headers: list[str], rows: Any) -> None:
+    """Write a row source as an Apache Parquet 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 parquet format.",
-        )
+        ) from e
     rows_list = list(rows)
     if rows_list:
         df = pl.DataFrame(rows_list, schema=headers, orient="row")

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):
@@ -43,12 +47,12 @@ def prettyprint_rowset(
     if not isinstance(rows, list):
         try:
             rows = list(rows)
-        except Exception:
+        except Exception as e:
             raise ErrInfo(
                 "exception",
                 exception_msg=exception_desc(),
                 other_msg="Can't create a list in memory of the data to be displayed as formatted text.",
-            )
+            ) from e
     rcols = range(len(colhdrs))
     rrows = range(len(rows))
     colwidths = [max(0, len(colhdrs[j]), *(len(as_ucode(rows[i][j])) for i in rrows)) for j in rcols]
@@ -76,13 +80,15 @@ def prettyprint_rowset(
                 ofile = EncodedFile(output_dest, _state.conf.output_encoding).open("w")
         else:
             ofile = ZipWriter(zipfile, output_dest, append)
-    if desc is not None:
-        ofile.write(f"{desc}\n")
-    for row in rows:
-        ln = f"{margin}{row}\n"
-        ofile.write(ln)
-    if output_dest != "stdout":
-        ofile.close()
+    try:
+        if desc is not None:
+            ofile.write(f"{desc}\n")
+        for row in rows:
+            ln = f"{margin}{row}\n"
+            ofile.write(ln)
+    finally:
+        if output_dest != "stdout":
+            ofile.close()
     return None
 
 
@@ -95,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,35 +25,38 @@ 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"
         of = open(outfile, mode)  # noqa: SIM115
     else:
         of = ZipWriter(zipfile, outfile, append)
-    for row in rowsource:
-        for col in row:
-            if isinstance(col, bytearray):
-                of.write(col)
-            else:
-                if isinstance(col, str):
-                    of.write(bytes(col, db_encoding))
+    try:
+        for row in rowsource:
+            for col in row:
+                if isinstance(col, bytearray):
+                    of.write(col)
                 else:
-                    of.write(bytes(str(col), db_encoding))
-    of.close()
+                    if isinstance(col, str):
+                        of.write(bytes(col, db_encoding))
+                    else:
+                        of.write(bytes(str(col), db_encoding))
+    finally:
+        of.close()
 
 
 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"
         of = open(outfile, mode)  # noqa: SIM115
     else:
         of = ZipWriter(zipfile, outfile, append)
-    for row in rowsource:
-        for col in row:
-            of.write(base64.standard_b64decode(col))
-    of.close()
+    try:
+        for row in rowsource:
+            for col in row:
+                of.write(base64.standard_b64decode(col))
+    finally:
+        of.close()

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,12 +74,13 @@ 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:
         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_sqlite(outfile, hdrs, rows, append, tablename)

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,21 +17,26 @@ 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
 
         inf = EncodedFile(self.infname, conf.script_encoding)
-        self.template = string.Template(inf.open("r").read())
-        inf.close()
+        fh = inf.open("r")
+        try:
+            self.template = string.Template(fh.read())
+        finally:
+            fh.close()
 
     def __repr__(self) -> str:
         return f"StrTemplateReport({self.infname})"
@@ -43,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
@@ -58,18 +65,25 @@ class StrTemplateReport:
                     ofile = EncodedFile(output_dest, conf.output_encoding).open("w")
             else:
                 ofile = ZipWriter(zipfile, output_dest, append)
-        for dd in data_dict_rows:
-            ofile.write(self.template.safe_substitute(dd))
-        if output_dest != "stdout":
-            ofile.close()
+        try:
+            for dd in data_dict_rows:
+                ofile.write(self.template.safe_substitute(dd))
+        finally:
+            if output_dest != "stdout":
+                ofile.close()
 
 
 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/",
@@ -79,11 +93,14 @@ class JinjaTemplateReport:
         from execsql.utils.fileio import EncodedFile
 
         inf = EncodedFile(template_file, conf.script_encoding)
-        self.template = jinja2.Template(inf.open("r").read())
-        inf.close()
+        fh = inf.open("r")
+        try:
+            self.template = SandboxedEnvironment().from_string(fh.read())
+        finally:
+            fh.close()
 
     def __repr__(self) -> str:
-        return f"StrTemplateReport({self.infname})"
+        return f"JinjaTemplateReport({self.infname})"
 
     def write_report(
         self,
@@ -93,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
@@ -110,14 +128,13 @@ 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:
-            raise ErrInfo("error", other_msg=e.message + f" on template line {e.lineno}")
-        except jinja2.TemplateError as e:
-            raise ErrInfo("error", other_msg=f"Jinja2 template error ({e.message})")
-        except:
-            raise
-        if output_dest != "stdout":
-            ofile.close()
+        except self._jinja2.TemplateSyntaxError as e:
+            raise ErrInfo("error", other_msg=e.message + f" on template line {e.lineno}") from 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":
+                ofile.close()
 
 
 def report_query(
@@ -128,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
@@ -40,24 +43,26 @@ def export_values(
                 f = ef.open("wt")
         else:
             f = ZipWriter(zipfile, outfile, append)
-    if desc is not None:
-        f.write(f"-- {desc}\n")
-    f.write(f"INSERT INTO !!target_table!!\n    ({', '.join(hdrs)})\n")
-    f.write("VALUES\n")
-    firstrow = True
-    for r in rows:
-        if firstrow:
-            firstrow = False
-        else:
-            f.write(",\n")
-        quoted_row = [
-            f"'{v.replace(chr(39), chr(39) * 2)}'" if isinstance(v, str) else str(v) if v is not None else "NULL"
-            for v in r
-        ]
-        f.write(f"    ({', '.join(quoted_row)})")
-    f.write("\n    ;\n")
-    if outfile.lower() != "stdout":
-        f.close()
+    try:
+        if desc is not None:
+            f.write(f"-- {desc}\n")
+        f.write(f"INSERT INTO !!target_table!!\n    ({', '.join(hdrs)})\n")
+        f.write("VALUES\n")
+        firstrow = True
+        for r in rows:
+            if firstrow:
+                firstrow = False
+            else:
+                f.write(",\n")
+            quoted_row = [
+                f"'{v.replace(chr(39), chr(39) * 2)}'" if isinstance(v, str) else str(v) if v is not None else "NULL"
+                for v in r
+            ]
+            f.write(f"    ({', '.join(quoted_row)})")
+        f.write("\n    ;\n")
+    finally:
+        if outfile.lower() != "stdout":
+            f.close()
 
 
 def write_query_to_values(
@@ -68,10 +73,11 @@ 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:
         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_values(outfile, hdrs, rows, append, desc, zipfile=zipfile)