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

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,10 +83,11 @@ 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:
-            raise XlsFileError(f"There is no Excel worksheet named {sheetname} in {self.filename}.")
+        except Exception as e:
+            raise XlsFileError(f"There is no Excel worksheet named {sheetname} in {self.filename}.") from e
 
         # Don't rely on sheet.ncols and sheet.nrows, because Excel will count columns
         # and rows that have ever been filled, even if they are now empty.  Base the column count
@@ -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,10 +227,11 @@ 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:
-            raise XlsxFileError(f"There is no Excel worksheet named {sheetname} in {self.filename}.")
+        except Exception as e:
+            raise XlsxFileError(f"There is no Excel worksheet named {sheetname} in {self.filename}.") from e
         # Don't rely on sheet.max_column and sheet.max_row, because Excel will count columns
         # and rows that have ever been filled, even if they are now empty.  Base the column count
         # on the number of contiguous non-empty cells in the first row, and process the data up to nrows until

execsql/exporters/xml.py

@@ -8,7 +8,9 @@ to a well-formed XML file with one element per row and column values as
 child elements or attributes.
 """
 
+import re
 from typing import Any
+from xml.sax.saxutils import escape as xml_escape
 
 import execsql.state as _state
 from execsql.exporters.zip import ZipWriter
@@ -16,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,
@@ -26,13 +30,14 @@ 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)
     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
     if zipfile is None:
         filewriter_close(outfile)
         from execsql.utils.fileio import EncodedFile
@@ -47,14 +52,27 @@ def write_query_to_xml(
     else:
         f = ZipWriter(zipfile, outfile, append)
         f.write(f"<?xml version='1.0' encoding='{conf.output_encoding}'?>\n")
-    if desc is not None:
-        f.write(f"<!--{desc}-->\n")
-    f.write(f"<{tablename}>\n")
-    str_hdrs = [str(h) for h in hdrs]
-    for row in rows:
-        f.write("  <row>\n")
-        for i, col in enumerate(str_hdrs):
-            f.write(f"    <{col}>{row[i]}</{col}>\n")
-        f.write("  </row>\n")
-    f.write(f"</{tablename}>\n")
-    f.close()
+
+    def _safe_xml_name(name: str) -> str:
+        """Sanitize a string for use as an XML element name."""
+        # Replace characters that are invalid in XML names with underscores.
+        s = re.sub(r"[^\w.\-]", "_", str(name))
+        # XML names must start with a letter or underscore, not a digit or dot.
+        if s and not (s[0].isalpha() or s[0] == "_"):
+            s = "_" + s
+        return s or "_"
+
+    try:
+        if desc is not None:
+            f.write(f"<!--{desc.replace('--', '- -')}-->\n")
+        safe_tablename = _safe_xml_name(tablename)
+        f.write(f"<{safe_tablename}>\n")
+        str_hdrs = [_safe_xml_name(h) for h in hdrs]
+        for row in rows:
+            f.write("  <row>\n")
+            for i, col in enumerate(str_hdrs):
+                f.write(f"    <{col}>{xml_escape(str(row[i]) if row[i] is not None else '')}</{col}>\n")
+            f.write("  </row>\n")
+        f.write(f"</{safe_tablename}>\n")
+    finally:
+        f.close()

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,
@@ -85,13 +87,13 @@ def import_data_table(
             # ...except for Firebird.
             if db.type == dbt_firebird:
                 db.conn.commit()
-        except Exception:
+        except Exception as e:
             raise ErrInfo(
                 type="db",
                 command_text=sql,
                 exception_msg=exception_info(),
                 other_msg=f"Could not create new table ({tablename}) for IMPORT metacommand",
-            )
+            ) from e
     table_cols = db.table_columns(tablename, schemaname)
     if conf.import_common_cols_only:
         import_cols = [col for col in hdrs if col.lower() in [tc.lower() for tc in table_cols]]
@@ -108,5 +110,5 @@ def import_data_table(
         db.commit()
     except ErrInfo:
         raise
-    except Exception:
-        raise ErrInfo("db", "Call to populate_table when importing data", exception_msg=exception_info())
+    except Exception as e:
+        raise ErrInfo("db", "Call to populate_table when importing data", exception_msg=exception_info()) 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,
@@ -60,13 +62,13 @@ def importtable(
             # ...except for Firebird.  Execute the commit directly via the connection so it is always done.
             if db.type == dbt_firebird:
                 db.conn.commit()
-        except Exception:
+        except Exception as e:
             raise ErrInfo(
                 type="db",
                 command_text=sql,
                 exception_msg=exception_info(),
                 other_msg=f"Could not create new table ({tablename}) for IMPORT metacommand",
-            )
+            ) from e
     else:
         if schemaname is not None:
             if not db.table_exists(tablename, schemaname):
@@ -85,13 +87,13 @@ def importtable(
         db.commit()
     except ErrInfo:
         raise
-    except Exception:
+    except Exception as e:
         fq_tablename = db.schema_qualified_table_name(schemaname, tablename)
         raise ErrInfo(
             "exception",
             exception_msg=exception_info(),
             other_msg=f"Can't import tabular file ({filename}) to table ({fq_tablename})",
-        )
+        ) from e
     inf.close()
 
 
@@ -121,10 +123,10 @@ def importfile(
         db.commit()
     except ErrInfo:
         raise
-    except Exception:
+    except Exception as e:
         fq_tablename = db.schema_qualified_table_name(schemaname, tablename)
         raise ErrInfo(
             "exception",
             exception_msg=exception_info(),
             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,
@@ -26,12 +28,12 @@ def import_feather(
 
     try:
         import polars as pl
-    except Exception:
+    except Exception as e:
         raise ErrInfo(
             "exception",
             exception_msg=exception_info(),
             other_msg="The polars Python library must be installed to import data from the Feather format.",
-        )
+        ) from e
     df = pl.read_ipc(filename)
     hdrs = df.columns
     data = [list(row) for row in df.rows()]
@@ -49,12 +51,12 @@ def import_parquet(
 
     try:
         import polars as pl
-    except Exception:
+    except Exception as e:
         raise ErrInfo(
             "exception",
             exception_msg=exception_info(),
             other_msg="The polars Python library must be installed to import data from the Parquet format.",
-        )
+        ) from e
     df = pl.read_parquet(filename)
     hdrs = df.columns
     data = [list(row) for row in df.rows()]

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,
@@ -31,12 +33,12 @@ def ods_data(
     wbk = OdsFile()
     try:
         wbk.open(filename)
-    except Exception:
-        raise ErrInfo(type="cmd", other_msg=f"{filename} is not a valid OpenDocument spreadsheet.")
+    except Exception as e:
+        raise ErrInfo(type="cmd", other_msg=f"{filename} is not a valid OpenDocument spreadsheet.") from e
     try:
         alldata = wbk.sheet_data(sheetname, junk_header_rows)
-    except Exception:
-        raise ErrInfo(type="cmd", other_msg=f"{sheetname} is not a worksheet in {filename}.")
+    except Exception as e:
+        raise ErrInfo(type="cmd", other_msg=f"{sheetname} is not a worksheet in {filename}.") from e
     colhdrs = alldata[0]
     if any(x is None or len(x.strip()) == 0 for x in colhdrs):
         if conf.del_empty_cols:

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,
@@ -45,12 +47,12 @@ def xls_data(
         raise ErrInfo(type="cmd", other_msg=f"{filename} is not a recognizable Excel spreadsheet name.")
     try:
         wbk.open(filename, encoding, read_only=True)
-    except Exception:
-        raise ErrInfo(type="cmd", other_msg=f"{filename} is not a valid Excel spreadsheet.")
+    except Exception as e:
+        raise ErrInfo(type="cmd", other_msg=f"{filename} is not a valid Excel spreadsheet.") from e
     try:
         alldata = wbk.sheet_data(sheetname, junk_header_rows)
-    except Exception:
-        raise ErrInfo(type="cmd", other_msg=f"Error reading worksheet {sheetname} from {filename}.")
+    except Exception as e:
+        raise ErrInfo(type="cmd", other_msg=f"Error reading worksheet {sheetname} from {filename}.") from e
     if len(alldata) == 0:
         raise ErrInfo(type="cmd", other_msg=f"There are no data on worksheet {sheetname} of file {filename}.")
     if ext3 == "lsx":