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

execsql/metacommands/io_write.py

@@ -0,0 +1,248 @@
+"""WRITE metacommand handlers.
+
+Implements ``x_write``, ``x_write_create_table`` (CSV, ODS, XLS, alias),
+``x_write_prefix``, ``x_write_suffix``, and ``x_writescript``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import execsql.state as _state
+from execsql.exceptions import ErrInfo
+from execsql.exporters.delimited import CsvFile
+from execsql.importers.ods import ods_data
+from execsql.importers.xls import xls_data
+from execsql.models import DataTable
+from execsql.script import substitute_vars
+from execsql.utils.errors import exception_desc
+from execsql.utils.fileio import check_dir, filewriter_close, filewriter_open_as_new, filewriter_write
+from execsql.utils.gui import ConsoleUIError
+
+
+def x_write(**kwargs: Any) -> None:
+    msg = f"{kwargs['text']}\n"
+    tee = kwargs["tee"]
+    tee = bool(tee)
+    outf = kwargs["filename"]
+    if _state.conf.write_prefix is not None:
+        msg = substitute_vars(_state.conf.write_prefix) + " " + msg
+    if _state.conf.write_suffix is not None:
+        msg = msg[:-1] + " " + substitute_vars(_state.conf.write_suffix) + "\n"
+    if outf:
+        check_dir(outf)
+        filewriter_write(outf, msg)
+    if (not outf) or tee:
+        try:
+            _state.output.write(msg)
+        except TypeError as e:
+            raise ErrInfo(
+                type="other",
+                command_text=kwargs["metacommandline"],
+                other_msg="TypeError in 'write' metacommand.",
+            ) from e
+        except ConsoleUIError as e:
+            _state.output.reset()
+            _state.exec_log.log_status_info(f"Console UI write failed (message {{{e.value}}}); output reset to stdout.")
+            _state.output.write(msg.encode(_state.conf.output_encoding))
+    if _state.conf.tee_write_log:
+        _state.exec_log.log_user_msg(msg)
+    return None
+
+
+def x_write_create_table(**kwargs: Any) -> None:
+    filename = kwargs["filename"]
+    if not Path(filename).exists():
+        raise ErrInfo(
+            type="cmd",
+            command_text=kwargs["metacommandline"],
+            other_msg="Input file does not exist",
+        )
+    quotechar = kwargs["quotechar"]
+    delimchar = kwargs["delimchar"]
+    encoding = kwargs["encoding"]
+    if delimchar:
+        if delimchar.lower() == "tab":
+            delimchar = chr(9)
+        elif delimchar.lower() in ("unitsep", "us"):
+            delimchar = chr(31)
+    junk_hdrs = kwargs["skip"]
+    if not junk_hdrs:
+        junk_hdrs = 0
+    else:
+        junk_hdrs = int(junk_hdrs)
+    enc = encoding if encoding else _state.conf.import_encoding
+    inf = CsvFile(filename, enc, junk_header_lines=junk_hdrs)
+    if quotechar and delimchar:
+        inf.lineformat(delimchar, quotechar, None)
+    inf.evaluate_column_types()
+    sql = inf.create_table(_state.dbs.current().type, kwargs["schema"], kwargs["table"], pretty=True)
+    inf.close()
+    comment = kwargs["comment"]
+    outfile = kwargs["outfile"]
+
+    def write(txt: str) -> None:
+        if outfile is None or outfile == "stdout":
+            _state.output.write(txt)
+        else:
+            filewriter_write(outfile, txt)
+
+    if outfile:
+        check_dir(outfile)
+    if comment:
+        write(f"-- {comment}\n")
+    write(f"{sql}\n")
+
+
+def x_write_create_table_ods(**kwargs: Any) -> None:
+    schemaname = kwargs["schema"]
+    tablename = kwargs["table"]
+    filename = kwargs["filename"]
+    sheetname = kwargs["sheet"]
+    hdr_rows = kwargs["skip"]
+    if not hdr_rows:
+        hdr_rows = 0
+    else:
+        hdr_rows = int(hdr_rows)
+    comment = kwargs["comment"]
+    outfile = kwargs["outfile"]
+    if not Path(filename).exists():
+        raise ErrInfo(
+            type="cmd",
+            command_text=kwargs["metacommandline"],
+            other_msg="Input file does not exist",
+        )
+    hdrs, data = ods_data(filename, sheetname, hdr_rows)
+    tablespec = DataTable(hdrs, data)
+    sql = tablespec.create_table(_state.dbs.current().type, schemaname, tablename, pretty=True)
+    if outfile:
+        if comment:
+            filewriter_write(outfile, f"-- {comment}\n")
+        filewriter_write(outfile, sql)
+        filewriter_close(outfile)
+    else:
+        if comment:
+            _state.output.write(f"-- {comment}\n")
+        _state.output.write(f"{sql}\n")
+
+
+def x_write_create_table_xls(**kwargs: Any) -> None:
+    schemaname = kwargs["schema"]
+    tablename = kwargs["table"]
+    filename = kwargs["filename"]
+    sheetname = kwargs["sheet"]
+    junk_hdrs = kwargs["skip"]
+    encoding = kwargs["encoding"]
+    enc = encoding if encoding else _state.conf.import_encoding
+    if not junk_hdrs:
+        junk_hdrs = 0
+    else:
+        junk_hdrs = int(junk_hdrs)
+    comment = kwargs["comment"]
+    outfile = kwargs["outfile"]
+    if not Path(filename).exists():
+        raise ErrInfo(
+            type="cmd",
+            command_text=kwargs["metacommandline"],
+            other_msg="Input file does not exist",
+        )
+    hdrs, data = xls_data(filename, sheetname, junk_hdrs, enc)
+    tablespec = DataTable(hdrs, data)
+    sql = tablespec.create_table(_state.dbs.current().type, schemaname, tablename, pretty=True)
+    if outfile:
+        if comment:
+            filewriter_write(outfile, f"-- {comment}\n")
+        filewriter_write(outfile, sql)
+        filewriter_close(outfile)
+    else:
+        if comment:
+            _state.output.write(f"-- {comment}\n")
+        _state.output.write(f"{sql}\n")
+
+
+def x_write_create_table_alias(**kwargs: Any) -> None:
+    alias = kwargs["alias"].lower()
+    schema = kwargs["schema"]
+    table = kwargs["table"]
+    comment = kwargs["comment"]
+    outfile = kwargs["filename"]
+    if alias not in _state.dbs.aliases():
+        raise ErrInfo(
+            type="cmd",
+            command_text=kwargs["metacommandline"],
+            other_msg=f"Unrecognized database alias: {alias}.",
+        )
+    db = _state.dbs.aliased_as(alias)
+    tbl = db.schema_qualified_table_name(schema, table)
+    try:
+        if not db.table_exists(table, schema):
+            raise ErrInfo(
+                type="cmd",
+                command_text=kwargs["metacommandline"],
+                other_msg=f"Table {tbl} does not exist",
+            )
+    except Exception:
+        pass  # Best-effort check; some adapters lack information_schema.
+    select_stmt = f"select * from {tbl};"
+    try:
+        hdrs, rows = db.select_rowsource(select_stmt)
+    except ErrInfo:
+        raise
+    except Exception as e:
+        raise ErrInfo("db", select_stmt, exception_msg=exception_desc()) from e
+    tablespec = DataTable(hdrs, rows)
+    sql = tablespec.create_table(_state.dbs.current().type, kwargs["schema1"], kwargs["table1"], pretty=True)
+    if outfile:
+        if comment:
+            filewriter_write(outfile, f"-- {comment}\n")
+        filewriter_write(outfile, sql)
+        filewriter_close(outfile)
+    else:
+        if comment:
+            _state.output.write(f"-- {comment}\n")
+        _state.output.write(f"{sql}\n")
+
+
+def x_write_prefix(**kwargs: Any) -> None:
+    pf = kwargs["prefix"]
+    if pf.lower() == "clear":
+        _state.conf.write_prefix = None
+    else:
+        _state.conf.write_prefix = pf
+    return None
+
+
+def x_write_suffix(**kwargs: Any) -> None:
+    sf = kwargs["suffix"]
+    if sf.lower() == "clear":
+        _state.conf.write_suffix = None
+    else:
+        _state.conf.write_suffix = sf
+    return None
+
+
+def x_writescript(**kwargs: Any) -> None:
+    script_id = kwargs["script_id"]
+    output_dest = kwargs["filename"]
+    append = kwargs["append"]
+
+    def write(txt: str) -> None:
+        if output_dest is None or output_dest == "stdout":
+            _state.output.write(txt)
+        else:
+            filewriter_write(output_dest, txt)
+
+    if output_dest is not None and output_dest != "stdout":
+        check_dir(output_dest)
+        if not append:
+            filewriter_open_as_new(output_dest)
+    script = _state.savedscripts[script_id]
+    if script.paramnames is not None and len(script.paramnames) > 0:
+        write(f"BEGIN SCRIPT {script_id} ({', '.join(script.paramnames)})\n")
+    else:
+        write(f"BEGIN SCRIPT {script_id}\n")
+    lines = [c.commandline() for c in script.cmdlist]
+    for line in lines:
+        write(f"{line}\n")
+    write(f"END SCRIPT {script_id}\n")

execsql/metacommands/prompt.py

@@ -29,7 +29,6 @@ from typing import Any
 import execsql.state as _state
 from execsql.script import current_script_line
 from execsql.utils.errors import exception_desc, exit_now
-from execsql.utils.fileio import EncodedFile, check_dir
 from execsql.utils.gui import (
     ActionSpec,
     EntrySpec,
@@ -38,7 +37,6 @@ from execsql.utils.gui import (
     GUI_DIRECTORY,
     GUI_DISPLAY,
     GUI_ENTRY,
-    GUI_HALT,
     GUI_MAP,
     GUI_MSG,
     GUI_OPENFILE,
@@ -210,12 +208,12 @@ def x_prompt_entryform(**kwargs: Any) -> None:
                     initial_value = str(str(v["initial_value"]).lower() in ("yes", "true", "on", "1"))
                 else:
                     initial_value = str(v["initial_value"])
-            except Exception:
+            except Exception as e:
                 raise ErrInfo(
                     type="cmd",
                     command_text=kwargs["metacommandline"],
                     other_msg=f"The initial value of {v['initial_value']} can't be used.",
-                )
+                ) from e
         if "lookup_table" in colhdrs:
             lt = v["lookup_table"]
             if lt:
@@ -226,23 +224,23 @@ def x_prompt_entryform(**kwargs: Any) -> None:
             if entry_width:
                 try:
                     entry_width = int(entry_width)
-                except Exception:
+                except Exception as e:
                     raise ErrInfo(
                         type="cmd",
                         command_text=kwargs["metacommandline"],
                         other_msg=f"Entry width {entry_width} is not an integer",
-                    )
+                    ) from e
         if "height" in colhdrs:
             entry_height = v.get("height")
             if entry_height:
                 try:
                     entry_height = int(entry_height)
-                except Exception:
+                except Exception as e:
                     raise ErrInfo(
                         type="cmd",
                         command_text=kwargs["metacommandline"],
                         other_msg=f"Entry height {entry_height} is not an integer",
-                    )
+                    ) from e
                 if entry_height < 1:
                     entry_height = 1
         if "form_column" in colhdrs:
@@ -250,12 +248,12 @@ def x_prompt_entryform(**kwargs: Any) -> None:
             if entry_col:
                 try:
                     entry_col = int(entry_col)
-                except Exception:
+                except Exception as e:
                     raise ErrInfo(
                         type="cmd",
                         command_text=kwargs["metacommandline"],
                         other_msg=f"Entry column {entry_col} is not an integer",
-                    )
+                    ) from e
                 if entry_col < 1:
                     entry_col = 1
         subvarset = _state.subvars if subvar[0] != "~" else _state.commandliststack[-1].localvars
@@ -363,15 +361,15 @@ def prompt_compare(button_list: list, **kwargs: Any) -> Any:
     if alias1 is not None:
         try:
             db1 = _state.dbs.aliased_as(alias1)
-        except Exception:
-            raise ErrInfo(type="error", other_msg=badaliasmsg % alias1)
+        except Exception as e:
+            raise ErrInfo(type="error", other_msg=badaliasmsg % alias1) from e
     else:
         db1 = _state.dbs.current()
     if alias2 is not None:
         try:
             db2 = _state.dbs.aliased_as(alias2)
-        except Exception:
-            raise ErrInfo(type="error", other_msg=badaliasmsg % alias2)
+        except Exception as e:
+            raise ErrInfo(type="error", other_msg=badaliasmsg % alias2) from e
     else:
         db2 = _state.dbs.current()
     sq_name1 = db1.schema_qualified_table_name(schema1, table1)
@@ -666,8 +664,8 @@ def x_prompt_savefile(**kwargs: Any) -> None:
                 subvarset5.add_substitution(sub_name5, Path(fn).stem)
     except (ErrInfo, SystemExit):
         raise
-    except Exception:
-        raise ErrInfo(type="exception", exception_msg=exception_desc())
+    except Exception as e:
+        raise ErrInfo(type="exception", exception_msg=exception_desc()) from e
     return None
 
 
@@ -733,8 +731,8 @@ def x_prompt_openfile(**kwargs: Any) -> None:
                 subvarset5.add_substitution(sub_name5, Path(fn).stem)
     except (ErrInfo, SystemExit):
         raise
-    except Exception:
-        raise ErrInfo(type="exception", exception_msg=exception_desc())
+    except Exception as e:
+        raise ErrInfo(type="exception", exception_msg=exception_desc()) from e
     return None
 
 
@@ -769,8 +767,8 @@ def x_prompt_directory(**kwargs: Any) -> None:
             )
     except (ErrInfo, SystemExit):
         raise
-    except Exception:
-        raise ErrInfo(type="exception", exception_msg=exception_desc())
+    except Exception as e:
+        raise ErrInfo(type="exception", exception_msg=exception_desc()) from e
     return None
 
 
@@ -787,15 +785,15 @@ def prompt_select_rows(button_list: list, **kwargs: Any) -> Any:
     if alias1 is not None:
         try:
             db1 = _state.dbs.aliased_as(alias1)
-        except Exception:
-            raise ErrInfo(type="error", other_msg=badaliasmsg % alias1)
+        except Exception as e:
+            raise ErrInfo(type="error", other_msg=badaliasmsg % alias1) from e
     else:
         db1 = _state.dbs.current()
     if alias2 is not None:
         try:
             db2 = _state.dbs.aliased_as(alias2)
-        except Exception:
-            raise ErrInfo(type="error", other_msg=badaliasmsg % alias2)
+        except Exception as e:
+            raise ErrInfo(type="error", other_msg=badaliasmsg % alias2) from e
     else:
         db2 = _state.dbs.current()
     sq_name1 = db1.schema_qualified_table_name(schema1, table1)
@@ -942,48 +940,6 @@ def x_pause(**kwargs: Any) -> None:
     return None
 
 
-def x_halt_msg(**kwargs: Any) -> None:
-    errmsg = kwargs["errmsg"]
-    tee = kwargs["tee"]
-    tee = bool(tee)
-    outf = kwargs["filename"]
-    errlevel = kwargs["errorlevel"]
-    if errlevel:
-        errlevel = int(errlevel)
-    else:
-        errlevel = 3
-    conf = _state.conf
-    if outf:
-        check_dir(outf)
-        of = EncodedFile(outf, conf.output_encoding).open("a")
-        of.write(f"{errmsg}\n")
-        of.close()
-    schema = kwargs.get("schema")
-    table = kwargs.get("table")
-    if table:
-        db = _state.dbs.current()
-        db_obj = db.schema_qualified_table_name(schema, table)
-        sql = f"select * from {db_obj};"
-        headers, rows = db.select_data(sql)
-    else:
-        headers, rows = None, None
-    enable_gui()
-    return_queue = _queue.Queue()
-    gui_args = {
-        "title": "HALT",
-        "message": errmsg,
-        "button_list": [("OK", 1, "<Return>")],
-        "no_cancel": True,
-        "column_headers": headers,
-        "rowset": rows,
-        "help_url": None,
-    }
-    _state.gui_manager_queue.put(GuiSpec(GUI_HALT, gui_args, return_queue))
-    return_queue.get(block=True)
-    _state.exec_log.log_exit_halt(*current_script_line(), msg=errmsg)
-    exit_now(errlevel, None)
-
-
 def x_msg(**kwargs: Any) -> None:
     message = kwargs["message"]
     current_script_line()

execsql/metacommands/system.py

@@ -89,6 +89,11 @@ def x_log_datavars(**kwargs: Any) -> None:
     _state.conf.log_datavars = setting in ("yes", "on", "true", "1")
 
 
+def x_log_sql(**kwargs: Any) -> None:
+    setting = kwargs["setting"].lower()
+    _state.conf.log_sql = setting in ("yes", "on", "true", "1")
+
+
 def x_console(**kwargs: Any) -> None:
     onoff = kwargs["onoff"].lower()
     if onoff == "on":
@@ -251,6 +256,6 @@ def x_execute(**kwargs: Any) -> None:
         db.commit()
     except ErrInfo:
         raise
-    except Exception:
-        raise ErrInfo("db", command_text=sql, exception_msg=exception_desc())
+    except Exception as e:
+        raise ErrInfo("db", command_text=sql, exception_msg=exception_desc()) from e
     return None

execsql/models.py

@@ -40,6 +40,13 @@ from execsql.types import (
     DT_Varchar,
 )
 
+__all__ = [
+    "Column",
+    "DataTable",
+    "JsonDatatype",
+    "to_json_type",
+]
+
 
 class Column:
     # Column objects are used to compile information about the data types that a set of data

execsql/parser.py

@@ -27,6 +27,16 @@ from typing import Any
 
 from execsql.exceptions import CondParserError, NumericParserError
 
+__all__ = [
+    "SourceString",
+    "CondTokens",
+    "NumTokens",
+    "CondAstNode",
+    "NumericAstNode",
+    "CondParser",
+    "NumericParser",
+]
+
 
 class SourceString:
     def __init__(self, source_string: str) -> None:

execsql/script/__init__.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+"""
+Core script-execution engine for execsql.
+
+This module contains the data structures and functions that load, parse, and
+drive execution of execsql ``.sql`` script files.  It is the heart of the
+runtime.
+
+Key classes:
+
+- :class:`BatchLevels` — tracks which databases are used in nested BEGIN/END
+  BATCH blocks for commit/rollback handling.
+- :class:`IfItem` / :class:`IfLevels` — stack-based IF/ELSE/ENDIF nesting.
+- :class:`CounterVars` — named integer counters (``@NAME``).
+- :class:`SubVarSet` — global ``!!$VAR!!`` substitution-variable store, plus
+  ``&ENV``, ``@COUNTER``, ``~LOCAL``, and ``#ARG`` prefixes.
+- :class:`LocalSubVarSet` / :class:`ScriptArgSubVarSet` — per-script-scope
+  variable overlays.
+- :class:`MetaCommand` — one entry in the metacommand dispatch table (regex +
+  handler function + flags).
+- :class:`MetaCommandList` — ordered list of :class:`MetaCommand` entries;
+  ``get_match()`` finds the first matching entry for a given line.
+- :class:`SqlStmt` — wraps a single SQL string; ``run()`` executes it via the
+  active database connection.
+- :class:`MetacommandStmt` — wraps a metacommand line; ``run()`` dispatches
+  through :attr:`execsql.state.metacommandlist`.
+- :class:`ScriptCmd` — pairs a statement with its source-file location.
+- :class:`CommandList` — ordered list of :class:`ScriptCmd` objects plus an
+  execution cursor; ``run_next()`` drives one step of execution.
+- :class:`CommandListWhileLoop` / :class:`CommandListUntilLoop` — loop
+  variants of :class:`CommandList` that re-evaluate a condition each pass.
+- :class:`ScriptFile` — reads and tokenises a ``.sql`` file into
+  :class:`ScriptCmd` objects.
+- :class:`ScriptExecSpec` — specification for deferred script execution.
+
+Key functions:
+
+- :func:`set_system_vars` — populates built-in ``$VARNAME`` system variables.
+- :func:`substitute_vars` — performs ``!!$VAR!!`` and ``!{$var}!`` expansion.
+- :func:`runscripts` — central execution loop; pops the top
+  :class:`CommandList` from ``_state.commandliststack`` and drives
+  ``run_next()`` until the stack is empty.
+- :func:`current_script_line` — returns the source location of the currently
+  executing command.
+- :func:`read_sqlfile` — parses a SQL script file into a new
+  :class:`CommandList` and pushes it onto ``_state.commandliststack``.
+"""
+
+from execsql.script.control import BatchLevels, IfItem, IfLevels
+from execsql.script.engine import (
+    CommandList,
+    CommandListUntilLoop,
+    CommandListWhileLoop,
+    MetaCommand,
+    MetaCommandList,
+    MetacommandStmt,
+    ScriptCmd,
+    ScriptExecSpec,
+    ScriptFile,
+    SqlStmt,
+    current_script_line,
+    read_sqlfile,
+    read_sqlstring,
+    runscripts,
+    set_system_vars,
+    substitute_vars,
+)
+from execsql.script.variables import CounterVars, LocalSubVarSet, ScriptArgSubVarSet, SubVarSet
+
+__all__ = [
+    "BatchLevels",
+    "IfItem",
+    "IfLevels",
+    "CounterVars",
+    "SubVarSet",
+    "LocalSubVarSet",
+    "ScriptArgSubVarSet",
+    "MetaCommand",
+    "MetaCommandList",
+    "SqlStmt",
+    "MetacommandStmt",
+    "ScriptCmd",
+    "CommandList",
+    "CommandListWhileLoop",
+    "CommandListUntilLoop",
+    "ScriptFile",
+    "ScriptExecSpec",
+    "set_system_vars",
+    "substitute_vars",
+    "runscripts",
+    "current_script_line",
+    "read_sqlfile",
+    "read_sqlstring",
+]