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

execsql/db/oracle.py

@@ -16,8 +16,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__ = ["OracleDatabase"]
+
 
 class OracleDatabase(Database):
+    """Oracle adapter using the cx_Oracle (python-oracledb) driver."""
+
     def __init__(
         self,
         server_name: str,

execsql/db/postgres.py

@@ -19,11 +19,14 @@ from execsql.utils.auth import clear_stored_password, get_password, password_fro
 from execsql.utils.strings import encodings_match
 import execsql.state as _state
 
+__all__ = ["PostgresDatabase"]
 
 DEFAULT_CONNECT_TIMEOUT = 30  # seconds
 
 
 class PostgresDatabase(Database):
+    """PostgreSQL adapter using psycopg2, with schema support, server-side COPY, and keyring auth."""
+
     def __init__(
         self,
         server_name: str,

execsql/db/sqlite.py

@@ -18,11 +18,14 @@ from execsql.exceptions import ErrInfo
 from execsql.utils.errors import exception_desc, fatal_error
 import execsql.state as _state
 
+__all__ = ["SQLiteDatabase"]
 
 DEFAULT_CONNECT_TIMEOUT = 30  # seconds
 
 
 class SQLiteDatabase(Database):
+    """SQLite adapter using the Python standard-library sqlite3 module."""
+
     def __init__(self, SQLite_fn: str, timeout: float = DEFAULT_CONNECT_TIMEOUT) -> None:
         try:
             import sqlite3  # noqa: F401

execsql/db/sqlserver.py

@@ -7,6 +7,7 @@ Implements :class:`SqlServerDatabase`, which connects to Microsoft SQL
 Server via ``pyodbc``.  Corresponds to ``-t s`` on the CLI.
 """
 
+import re
 
 from execsql.db.base import Database
 from execsql.exceptions import ErrInfo
@@ -14,8 +15,12 @@ from execsql.utils.errors import fatal_error
 from execsql.utils.auth import clear_stored_password, get_password, password_from_keyring
 import execsql.state as _state
 
+__all__ = ["SqlServerDatabase"]
+
 
 class SqlServerDatabase(Database):
+    """Microsoft SQL Server adapter using pyodbc, trying drivers from newest to oldest."""
+
     def __init__(
         self,
         server_name: str,
@@ -96,9 +101,13 @@ class SqlServerDatabase(Database):
                     try:
                         self.conn = pyodbc.connect(connstr)
                     except Exception:
-                        _state.exec_log.log_status_info(f"Could not connect using: {connstr}")
+                        _state.exec_log.log_status_info(
+                            f"Could not connect using: {re.sub(r'Pwd=[^;]*', 'Pwd=***', connstr)}",
+                        )
                     else:
-                        _state.exec_log.log_status_info(f"Connected using: {connstr}")
+                        _state.exec_log.log_status_info(
+                            f"Connected using: {re.sub(r'Pwd=[^;]*', 'Pwd=***', connstr)}",
+                        )
                         return True
                 return False
 

execsql/exceptions.py

@@ -21,6 +21,24 @@ from a single location.  Notable exceptions:
 - :class:`CondParserError` / :class:`NumericParserError` — parser failures.
 """
 
+__all__ = [
+    "ExecSqlError",
+    "ConfigError",
+    "ExecSqlTimeoutError",
+    "ErrInfo",
+    "DataTypeError",
+    "DbTypeError",
+    "ColumnError",
+    "DataTableError",
+    "DatabaseNotImplementedError",
+    "OdsFileError",
+    "XlsFileError",
+    "XlsxFileError",
+    "ConsoleUIError",
+    "CondParserError",
+    "NumericParserError",
+]
+
 
 class ExecSqlError(Exception):
     """Base class for simple single-message execsql exceptions.

execsql/exporters/base.py

@@ -22,6 +22,8 @@ from execsql.script import current_script_line
 from execsql.utils.errors import file_size_date
 from execsql.utils.gui import ConsoleUIError
 
+__all__ = ["WriteSpec", "ExportRecord", "ExportMetadata"]
+
 
 class ExportRecord:
     """Records the details of a single EXPORT operation for metadata tracking.
@@ -88,15 +90,18 @@ class ExportMetadata:
         self.recordlist: list[ExportRecord] = []
 
     def add(self, exp_record: ExportRecord) -> None:
+        """Append an export record to the collection."""
         self.recordlist.append(exp_record)
 
     def get(self):
+        """Return column headers and all not-yet-exported records, marking them exported."""
         recs = [er.record for er in self.recordlist if not er.exported]
         for er in self.recordlist:
             er.exported = True
         return self.colhdrs, recs
 
     def get_all(self):
+        """Return column headers and every record regardless of prior export state."""
         recs = [er.record for er in self.recordlist]
         for er in self.recordlist:
             er.exported = True
@@ -130,6 +135,7 @@ class WriteSpec:
         self.written = False
 
     def write(self) -> None:
+        """Execute the deferred write, expanding substitution variables first."""
         # Writes the message per the specifications given to '__init__()'.  Substitution
         # variables are processed.
         # Inputs: no inputs.

execsql/exporters/delimited.py

@@ -29,9 +29,14 @@ from execsql.utils.errors import exception_desc
 from execsql.utils.fileio import filewriter_close
 from execsql.utils.strings import clean_words, fold_words
 
+__all__ = ["LineDelimiter", "CsvFile", "CsvWriter", "DelimitedWriter", "write_delimited_file"]
+
 
 class LineDelimiter:
+    """Encapsulates delimiter, quote character, and escape rules for a single line format."""
+
     def __init__(self, delim: str | None, quote: str | None, escchar: str | None) -> None:
+        """Initialise the line-format constants for a given delimiter/quote pair."""
         self.delimiter = delim
         self.joinchar = delim if delim else ""
         self.quotechar = quote
@@ -44,6 +49,7 @@ class LineDelimiter:
             self.quotedquote = None
 
     def delimited(self, datarow: Any, add_newline: bool = True) -> str:
+        """Format a sequence of values as a single delimited text line."""
         conf = _state.conf
         if self.quotechar:
             d_row = []
@@ -79,22 +85,30 @@ class LineDelimiter:
 
 
 class DelimitedWriter:
+    """Low-level writer that formats data rows as delimited text and sends them to an open file object."""
+
     def __init__(self, outfile: Any, delim: str | None, quote: str | None, escchar: str | None) -> None:
+        """Wrap an open file object with a :class:`LineDelimiter` for row-by-row writing."""
         self.outfile = outfile
         self.line_delimiter = LineDelimiter(delim, quote, escchar)
 
     def write(self, text_str: str) -> None:
+        """Write a raw string directly to the underlying file object."""
         self.outfile.write(text_str)
 
     def writerow(self, datarow: Any) -> None:
+        """Format one data row as delimited text and write it to the file."""
         self.outfile.write(self.line_delimiter.delimited(datarow))
 
     def writerows(self, datarows: Any) -> None:
+        """Write each row in an iterable of data rows to the file."""
         for row in datarows:
             self.writerow(row)
 
 
 class CsvWriter:
+    """Opens a named file (or stdout) and exposes a row-oriented delimited-text writing API."""
+
     def __init__(
         self,
         filename: str,
@@ -113,21 +127,32 @@ class CsvWriter:
         self.dwriter = DelimitedWriter(self.output, delim, quote, escchar)
 
     def write(self, text_str: str) -> None:
+        """Write a raw string to the output file."""
         self.dwriter.write(text_str)
 
     def writerow(self, datarow: Any) -> None:
+        """Format and write a single data row."""
         self.dwriter.writerow(datarow)
 
     def writerows(self, datarows: Any) -> None:
+        """Format and write each row in an iterable."""
         self.dwriter.writerows(datarows)
 
     def close(self) -> None:
+        """Close the underlying output file."""
         self.output.close()
         self.output = None
 
 
 class CsvFile(EncodedFile):
+    """Full delimited-file reader/writer with automatic format diagnosis.
+
+    Supports custom delimiters, quoting, encoding, junk-header skipping,
+    column-type inference, and ZIP output via :class:`CsvWriter`.
+    """
+
     def __init__(self, csvfname: str, file_encoding: str, junk_header_lines: int = 0) -> None:
+        """Open a CSV file path for later reading or writing."""
         super().__init__(csvfname, file_encoding)
         self.csvfname = csvfname
         self.junk_header_lines = junk_header_lines
@@ -143,6 +168,7 @@ class CsvFile(EncodedFile):
         return f"CsvFile({self.csvfname!r}, {self.encoding!r})"
 
     def openclean(self, mode: str) -> Any:
+        """Return an opened file object with the configured number of junk header lines skipped."""
         # Returns an opened file object with junk headers stripped.
         f = self.open(mode)
         for _ in range(self.junk_header_lines):
@@ -150,6 +176,7 @@ class CsvFile(EncodedFile):
         return f
 
     def lineformat(self, delimiter: str | None, quotechar: str | None, escapechar: str | None) -> None:
+        """Explicitly set the delimiter, quote character, and escape character."""
         # Specifies the format of a line.
         self.delimiter = delimiter
         self.quotechar = quotechar
@@ -413,6 +440,7 @@ class CsvFile(EncodedFile):
         )
 
     def evaluate_line_format(self) -> None:
+        """Scan the file to auto-detect the delimiter, quote character, and escape character."""
         # Scans the file to determine the delimiter, quote character, and escapechar.
         if not self.lineformat_set:
             f = self.openclean("rt")
@@ -426,6 +454,7 @@ class CsvFile(EncodedFile):
         self.parse_errors.append(f"{errmsg} in position {pos_no}")
 
     def read_and_parse_line(self, f: Any) -> list:
+        """Read and parse one line from an open file, returning a list of field values."""
         # Returns a list of line elements, parsed according to the established delimiter and quotechar.
         elements = []
         eat_multiple_delims = self.delimiter == " "
@@ -571,6 +600,7 @@ class CsvFile(EncodedFile):
         return elements
 
     def reader(self) -> Any:
+        """Yield parsed rows from the file as lists of field values."""
         conf = _state.conf
         self.evaluate_line_format()
         f = self.openclean("rt")
@@ -597,6 +627,7 @@ class CsvFile(EncodedFile):
             f.close()
 
     def writer(self, append: bool = False) -> CsvWriter:
+        """Return a :class:`CsvWriter` configured with this file's format settings."""
         return CsvWriter(self.filename, self.encoding, self.delimiter, self.quotechar, self.escapechar, append)
 
     def _colhdrs(self, inf: Any) -> list[str]:
@@ -640,17 +671,20 @@ class CsvFile(EncodedFile):
         return colnames
 
     def column_headers(self) -> list[str]:
+        """Return the first row of the file as a list of column header strings."""
         if not self.lineformat_set:
             self.evaluate_line_format()
         inf = self.reader()
         return self._colhdrs(inf)
 
     def data_table_def(self) -> Any:
+        """Return a :class:`DataTable` describing the file's columns and types."""
         if self.table_data is None:
             self.evaluate_column_types()
         return self.table_data
 
     def evaluate_column_types(self) -> None:
+        """Scan the file and populate ``table_data`` with inferred column types."""
         if not self.lineformat_set:
             self.evaluate_line_format()
         inf = self.reader()
@@ -658,6 +692,7 @@ class CsvFile(EncodedFile):
         self.table_data = DataTable(colnames, inf)
 
     def create_table(self, database_type: Any, schemaname: str | None, tablename: str, pretty: bool = False) -> str:
+        """Generate a CREATE TABLE SQL statement for this file's inferred schema."""
         return self.table_data.create_table(database_type, schemaname, tablename, pretty)
 
 
@@ -670,6 +705,7 @@ def write_delimited_file(
     append: bool = False,
     zipfile: str | None = None,
 ) -> None:
+    """Write a query result set to a CSV, TSV, or other delimited text file."""
     delim = None
     quote = None
     escchar = None

execsql/exporters/duckdb.py

@@ -15,6 +15,8 @@ from typing import Any
 from execsql.exceptions import ErrInfo
 from execsql.types import dbt_duckdb
 
+__all__ = ["export_duckdb", "write_query_to_duckdb"]
+
 
 def export_duckdb(
     outfile: str,
@@ -23,6 +25,7 @@ def export_duckdb(
     append: bool,
     tablename: str,
 ) -> None:
+    """Write pre-fetched rows to a named table in a DuckDB database file."""
     try:
         import duckdb
     except Exception:
@@ -79,6 +82,7 @@ def write_query_to_duckdb(
     append: bool,
     tablename: str,
 ) -> None:
+    """Execute a SELECT and write the result set to a named table in a DuckDB database."""
     from execsql.utils.errors import exception_desc
 
     try:

execsql/exporters/feather.py

@@ -18,8 +18,11 @@ from execsql.types import DT_Boolean, DT_Date, DT_Timestamp, DT_TimestampTZ
 from execsql.utils.errors import exception_desc
 from execsql.utils.fileio import filewriter_close
 
+__all__ = ["write_query_to_feather", "write_query_to_hdf5"]
+
 
 def write_query_to_feather(outfile: str, headers: list[str], rows: Any) -> None:
+    """Write a row source as an Apache Arrow Feather v2 file using polars."""
     try:
         import polars as pl
     except ImportError as e:
@@ -45,6 +48,7 @@ def write_query_to_hdf5(
     append: bool = False,
     desc: str | None = None,
 ) -> None:
+    """Execute a SELECT and write the result set to an HDF5 file using the tables library."""
     try:
         import tables
     except ImportError as e:

execsql/exporters/html.py

@@ -25,6 +25,8 @@ from execsql.script import current_script_line
 from execsql.utils.errors import exception_desc
 from execsql.utils.fileio import filewriter_close
 
+__all__ = ["export_html", "export_cgi_html", "write_query_to_html", "write_query_to_cgi_html"]
+
 
 def export_html(
     outfile: str,
@@ -35,6 +37,7 @@ def export_html(
     desc: str | None = None,
     zipfile: str | None = None,
 ) -> None:
+    """Write a complete HTML document containing a data table to a file or ZIP archive."""
     conf = _state.conf
 
     def write_table(f):
@@ -164,6 +167,7 @@ def export_cgi_html(
     desc: str | None = None,
     zipfile: str | None = None,
 ) -> None:
+    """Write a CGI-style HTML fragment (Content-Type header + table) to a file or ZIP archive."""
     conf = _state.conf
 
     def write_table(f):
@@ -223,6 +227,7 @@ def write_query_to_html(
     desc: str | None = None,
     zipfile: str | None = None,
 ) -> None:
+    """Execute a SELECT and write the result set as a standalone HTML document."""
     try:
         hdrs, rows = db.select_rowsource(select_stmt)
     except ErrInfo:
@@ -240,6 +245,7 @@ def write_query_to_cgi_html(
     desc: str | None = None,
     zipfile: str | None = None,
 ) -> None:
+    """Execute a SELECT and write the result set as a CGI-style HTML fragment."""
     try:
         hdrs, rows = db.select_rowsource(select_stmt)
     except ErrInfo:

execsql/exporters/json.py

@@ -8,6 +8,7 @@ Provides :func:`write_query_to_json` (standard JSON array of objects) and
 both of which serialize a query result set to a file or stream.
 """
 
+import json
 from typing import Any
 
 import execsql.state as _state
@@ -17,6 +18,8 @@ from execsql.models import DataTable
 from execsql.utils.errors import exception_desc
 from execsql.utils.fileio import filewriter_close
 
+__all__ = ["write_query_to_json", "write_query_to_json_ts"]
+
 
 def write_query_to_json(
     select_stmt: str,
@@ -26,9 +29,7 @@ def write_query_to_json(
     desc: str | None = None,
     zipfile: str | None = None,
 ) -> None:
-    global json
-    import json
-
+    """Execute a SELECT and write the result set as a JSON array of objects."""
     conf = _state.conf
     try:
         hdrs, rows = db.select_rowsource(select_stmt)
@@ -75,9 +76,7 @@ def write_query_to_json_ts(
     desc: str | None = None,
     zipfile: str | None = None,
 ) -> None:
-    global json
-    import json
-
+    """Execute a SELECT and write the result set as a JSON object with a top-level field-type schema."""
     conf = _state.conf
     try:
         hdrs, rows = db.select_rowsource(select_stmt)

execsql/exporters/latex.py

@@ -17,6 +17,8 @@ from execsql.exceptions import ErrInfo
 from execsql.exporters.zip import WriteableZipfile
 import execsql.state as _state
 
+__all__ = ["export_latex", "write_query_to_latex"]
+
 
 def export_latex(
     outfile: str,
@@ -27,6 +29,7 @@ def export_latex(
     desc: str | None = None,
     zipfile: Any | None = None,
 ) -> None:
+    """Write pre-fetched rows as a LaTeX tabular environment to a file or ZIP archive."""
     from execsql.utils.fileio import EncodedFile
 
     def write_table(f: Any) -> None:
@@ -120,6 +123,7 @@ def write_query_to_latex(
     desc: str | None = None,
     zipfile: Any | None = None,
 ) -> None:
+    """Execute a SELECT and write the result set as a LaTeX tabular table."""
     from execsql.utils.errors import exception_desc
 
     try:

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,6 +357,7 @@ 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:
@@ -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
 

execsql/exporters/parquet.py

@@ -13,8 +13,11 @@ 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 as e:

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)