execsql2 2.0.0a2__py3-none-any.whl → 2.1.1__py3-none-any.whl

execsql/state.py

@@ -28,24 +28,39 @@ Variable groups defined here:
 - **Utility functions** — ``xcmd_test()`` (evaluate a conditional string),
   ``endloop()`` (finalise a compiled loop).
 
-The bottom of this module re-exports frequently-used names from sibling
-modules so that ``_state.ErrInfo``, ``_state.runscripts``, etc. resolve
-correctly even though those modules themselves import ``execsql.state``.
+All re-exports have been removed. Each module now imports directly from
+its source module rather than accessing names via ``_state``.
 """
 
-import getpass
 import re
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
-    from execsql.config import ConfigData
+    import multiprocessing as _mp
+    import threading as _threading
+
+    from execsql.config import ConfigData, StatObj, WriteHooks
+    from execsql.db.base import DatabasePool
+    from execsql.exporters.base import ExportMetadata, WriteSpec
+    from execsql.script import (
+        CommandList,
+        CounterVars,
+        IfLevels,
+        MetaCommandList,
+        ScriptCmd,
+        ScriptExecSpec,
+        SubVarSet,
+    )
+    from execsql.utils.fileio import FileWriter, Logger, TempFileMgr
+    from execsql.utils.mail import MailSpec
+    from execsql.utils.timer import Timer
 
 # ---------------------------------------------------------------------------
 # Configuration / encoding
 # ---------------------------------------------------------------------------
 
 # Configuration data, initialized in main()
-conf: Optional[ConfigData] = None
+conf: ConfigData | None = None
 
 # Default encodings
 logfile_encoding: str = "utf8"  # Should never be changed; is not configurable.
@@ -55,41 +70,41 @@ logfile_encoding: str = "utf8"  # Should never be changed; is not configurable.
 # ---------------------------------------------------------------------------
 
 # The last command run.  This should be a ScriptCmd object.
-last_command: Any = None
+last_command: ScriptCmd | None = None
 
 # The last user password entered via 'get_password()'
-upass: Optional[str] = None
+upass: str | None = None
 
 # A compiled regex to match prefixed regular expressions, used to check
 # for unsubstituted variables.
 varlike = re.compile(r"!![$@&~#]?\w+!!", re.I)
 
 # A WriteSpec object for messages to be written when the program halts due to an error.
-err_halt_writespec: Any = None
+err_halt_writespec: WriteSpec | None = None
 
 # A MailSpec object for email to be sent when the program halts due to an error.
-err_halt_email: Any = None
+err_halt_email: MailSpec | None = None
 
 # A ScriptExecSpec object for a script to be executed when the program halts due to an error.
-err_halt_exec: Any = None
+err_halt_exec: ScriptExecSpec | None = None
 
 # A WriteSpec object for messages to be written when the program halts due to user cancellation.
-cancel_halt_writespec: Any = None
+cancel_halt_writespec: WriteSpec | None = None
 
 # A MailSpec object for email to be sent when the program halts due to user cancellation.
-cancel_halt_mailspec: Any = None
+cancel_halt_mailspec: MailSpec | None = None
 
 # A ScriptExecSpec object for a script to be executed when the program halts due to user cancellation.
-cancel_halt_exec: Any = None
+cancel_halt_exec: ScriptExecSpec | None = None
 
 # A stack of the CommandList objects currently in the queue to be executed.
-commandliststack: list = []
+commandliststack: list[CommandList] = []
 
 # A dictionary of CommandList objects (ordinarily created by BEGIN/END SCRIPT metacommands).
-savedscripts: dict = {}
+savedscripts: dict[str, CommandList] = {}
 
 # A stack of CommandList objects used when compiling the statements within a loop.
-loopcommandstack: list = []
+loopcommandstack: list[CommandList] = []
 
 # A global flag to indicate that commands should be compiled into the topmost entry
 # in the loopcommandstack rather than executed.
@@ -114,54 +129,54 @@ defer_rx = re.compile(r"(!{([$@&~#]?[a-z0-9_]+)}!)", re.I)
 stringtypes: type = str
 
 # The execution log object; set at startup.
-exec_log: Any = None
+exec_log: Logger | None = None
 
 # The substitution variable set; set at startup.
-subvars: Any = None
+subvars: SubVarSet | None = None
 
 # The program execution status tracker; set at startup.
-status: Any = None
+status: StatObj | None = None
 
 # ---------------------------------------------------------------------------
 # Runtime objects — initialized in main() to avoid circular imports at load time.
 # ---------------------------------------------------------------------------
 
 # Stack-based conditional state (IfLevels instance).
-if_stack: Any = None
+if_stack: IfLevels | None = None
 
 # Global counter variables (CounterVars instance).
-counters: Any = None
+counters: CounterVars | None = None
 
 # Elapsed-time tracker (Timer instance).
-timer: Any = None
+timer: Timer | None = None
 
 # Redirectable output (WriteHooks instance).
-output: Any = None
+output: WriteHooks | None = None
 
 # Database connection pool (DatabasePool instance).
-dbs: Any = None
+dbs: DatabasePool | None = None
 
 # Temporary file manager (TempFileMgr instance).
-tempfiles: Any = None
+tempfiles: TempFileMgr | None = None
 
 # Export metadata tracker (ExportMetadata instance).
-export_metadata: Any = None
+export_metadata: ExportMetadata | None = None
 
 # Metacommand dispatch table (MetaCommandList instance).
-metacommandlist: Any = None
+metacommandlist: MetaCommandList | None = None
 
 # Conditional predicate dispatch table (MetaCommandList instance).
-conditionallist: Any = None
+conditionallist: MetaCommandList | None = None
 
 # Asynchronous file-writer subprocess (FileWriter instance).
-filewriter: Any = None
+filewriter: FileWriter | None = None
 
 # GUI console object.
-gui_console: Any = None
+gui_console: Any = None  # Varies by backend (ConsoleUI, DesktopUI, TextualUI).
 
 # Queue and thread used to communicate with the GUI manager.
-gui_manager_queue: Any = None
-gui_manager_thread: Any = None
+gui_manager_queue: _mp.Queue | None = None
+gui_manager_thread: _threading.Thread | None = None
 
 # ---------------------------------------------------------------------------
 # Version numbers (parsed from package __version__)
@@ -170,18 +185,14 @@ gui_manager_thread: Any = None
 try:
     from execsql import __version__ as _pkg_version
 
-    import re as _re
-
     _vparts = _pkg_version.split(".")
-    # Strip pre-release suffix (e.g. "0a1" → "0") before converting to int.
-    _int = lambda s: int(_re.match(r"\d+", s).group())
-    primary_vno: int = _int(_vparts[0]) if len(_vparts) > 0 else 0
-    secondary_vno: int = _int(_vparts[1]) if len(_vparts) > 1 else 0
-    tertiary_vno: int = _int(_vparts[2]) if len(_vparts) > 2 else 0
+    primary_vno: int = int(_vparts[0]) if len(_vparts) > 0 else 0
+    secondary_vno: int = int(_vparts[1]) if len(_vparts) > 1 else 0
+    tertiary_vno: int = int(_vparts[2]) if len(_vparts) > 2 else 0
 except Exception:
-    primary_vno = 1
-    secondary_vno = 130
-    tertiary_vno = 1
+    primary_vno = 0
+    secondary_vno = 0
+    tertiary_vno = 0
 
 # ---------------------------------------------------------------------------
 # Utility functions defined directly here to avoid circular imports.
@@ -190,192 +201,139 @@ except Exception:
 
 def xcmd_test(teststr: str) -> bool:
     """Evaluate a conditional test string and return a boolean result."""
-    from execsql.parser import CondParser
-    from execsql.exceptions import ErrInfo
+    import execsql.parser as _parser
+    import execsql.exceptions as _exc
 
-    result = CondParser(teststr).parse().eval()
+    result = _parser.CondParser(teststr).parse().eval()
     if result is not None:
         return result
-    raise ErrInfo(type="cmd", command_text=teststr, other_msg="Unrecognized conditional")
+    raise _exc.ErrInfo(type="cmd", command_text=teststr, other_msg="Unrecognized conditional")
 
 
 def endloop() -> None:
     """Complete the current loop being compiled and push it onto the command stack."""
-    from execsql.exceptions import ErrInfo
+    import execsql.exceptions as _exc
 
     global compiling_loop
     if len(loopcommandstack) == 0:
-        raise ErrInfo("error", other_msg="END LOOP metacommand without a matching preceding LOOP metacommand.")
+        raise _exc.ErrInfo("error", other_msg="END LOOP metacommand without a matching preceding LOOP metacommand.")
     compiling_loop = False
     commandliststack.append(loopcommandstack[-1])
     loopcommandstack.pop()
 
 
 # ---------------------------------------------------------------------------
-# Deferred re-exports
-# Placed at the bottom so that circular imports resolve correctly:
-# all state variables above are defined before any module below is loaded.
-# Modules that `import execsql.state as _state` will receive a partial
-# module (containing only the variables above) if they are themselves
-# imported during this block — which is safe because those modules only
-# access _state.X inside function/method bodies, never at class-definition time.
+# Test-support utilities
 # ---------------------------------------------------------------------------
 
-# Exceptions and parser — always safe (exceptions.py / parser.py import state
-# but only use _state inside function bodies, never at module level after init).
-from execsql.exceptions import ErrInfo  # noqa: E402
-from execsql.parser import CondParser, NumericParser  # noqa: E402
-
-# script.py defines the core execution data structures.
-from execsql.script import (  # noqa: E402
-    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,
-)
-
-# xcmd_test also lives in conditions.py; keep the version defined above
-# (identical logic) so that state.xcmd_test works without an extra import.
-# write_warning / exit_now / fatal_error / exception_desc
-from execsql.utils.errors import (  # noqa: E402
-    exception_desc,
-    exit_now,
-    fatal_error,
-    file_size_date,
-    write_warning,
-)
-
-# File-I/O helpers
-from execsql.utils.fileio import (  # noqa: E402
-    check_dir,
-    EncodedFile,
-    FileWriter,
-    Logger,
-    TempFileMgr,
-    filewriter_write,
-    filewriter_close,
-    filewriter_close_all_after_write,
-    filewriter_open_as_new,
-    filewriter_end,
-)
-
-# String utilities
-from execsql.utils.strings import (  # noqa: E402
-    clean_words,
-    fold_words,
-    is_doublequoted,
-    unquoted,
-    unquoted2,
-    get_subvarset,
-)
-
-# Other utilities
-from execsql.utils.crypto import Encrypt  # noqa: E402
-from execsql.utils.timer import Timer  # noqa: E402
-from execsql.utils.mail import Mailer, MailSpec  # noqa: E402
-from execsql.utils.datetime import parse_datetime  # noqa: E402
-from execsql.utils.auth import get_password  # noqa: E402
-
-# Data models
-from execsql.models import DataTable  # noqa: E402
-from execsql.types import DT_Boolean, DT_Date, DT_Timestamp, DT_TimestampTZ  # noqa: E402
-
-# Export infrastructure
-from execsql.exporters.base import ExportRecord, ExportMetadata, WriteSpec  # noqa: E402
-from execsql.exporters.pretty import prettyprint_query, prettyprint_rowset  # noqa: E402
-from execsql.exporters.templates import report_query  # noqa: E402
-from execsql.exporters.delimited import write_delimited_file, CsvFile  # noqa: E402
-from execsql.exporters.html import write_query_to_html, write_query_to_cgi_html  # noqa: E402
-from execsql.exporters.json import write_query_to_json, write_query_to_json_ts  # noqa: E402
-from execsql.exporters.xml import write_query_to_xml  # noqa: E402
-from execsql.exporters.ods import write_query_to_ods, write_queries_to_ods, OdsFile  # noqa: E402
-from execsql.exporters.sqlite import write_query_to_sqlite  # noqa: E402
-from execsql.exporters.duckdb import write_query_to_duckdb  # noqa: E402
-from execsql.exporters.latex import write_query_to_latex  # noqa: E402
-from execsql.exporters.feather import write_query_to_feather, write_query_to_hdf5  # noqa: E402
-from execsql.exporters.raw import write_query_raw, write_query_b64 as write_query_b  # noqa: E402
-from execsql.exporters.values import write_query_to_values  # noqa: E402
-from execsql.exporters.xls import XlsFile, XlsxFile  # noqa: E402
-
-# Alias for HDF — upstream used write_query_to_hdf
-write_query_to_hdf = write_query_to_hdf5
-
-# Import infrastructure
-from execsql.importers.csv import importtable, importfile  # noqa: E402
-from execsql.importers.ods import ods_data, importods  # noqa: E402
-from execsql.importers.xls import xls_data, importxls  # noqa: E402
-from execsql.importers.feather import import_feather, import_parquet  # noqa: E402
-from execsql.importers.base import import_data_table  # noqa: E402
-
-# Database layer
-from execsql.db.base import DatabasePool  # noqa: E402
-from execsql.db.postgres import PostgresDatabase  # noqa: E402
-from execsql.db.sqlite import SQLiteDatabase  # noqa: E402
-from execsql.db.mysql import MySQLDatabase  # noqa: E402
-from execsql.db.duckdb import DuckDBDatabase  # noqa: E402
-from execsql.db.firebird import FirebirdDatabase  # noqa: E402
-from execsql.db.oracle import OracleDatabase  # noqa: E402
-from execsql.db.access import AccessDatabase  # noqa: E402
-from execsql.db.sqlserver import SqlServerDatabase  # noqa: E402
-from execsql.db.dsn import DsnDatabase  # noqa: E402
-
-# Database type descriptors
-from execsql.types import dbt_postgres, dbt_firebird  # noqa: E402
-
-# GUI layer — pluggable backends: Textual (TUI), Tkinter (desktop), Console
-from execsql.utils.gui import (  # noqa: E402
-    gui_console_isrunning,
-    enable_gui,
-    gui_console_on,
-    gui_console_off,
-    gui_console_hide,
-    gui_console_show,
-    gui_console_progress,
-    gui_console_save,
-    gui_console_status,
-    gui_console_wait_user,
-    gui_console_height,
-    gui_console_width,
-    gui_connect,
-    gui_credentials,
-    GuiSpec,
-    ConsoleUIError,
-    ActionSpec,
-    EntrySpec,
-    GUI_HALT,
-    GUI_MSG,
-    GUI_PAUSE,
-    GUI_DISPLAY,
-    GUI_ENTRY,
-    GUI_COMPARE,
-    GUI_SELECTROWS,
-    GUI_SELECTSUB,
-    GUI_ACTION,
-    GUI_MAP,
-    GUI_OPENFILE,
-    GUI_SAVEFILE,
-    GUI_DIRECTORY,
-    QUERY_CONSOLE,
-    GUI_CREDENTIALS,
-    GUI_CONNECT,
-    get_yn,
-    get_yn_win,
-    pause,
-    pause_win,
-)
+
+def reset() -> None:
+    """Reset all module-level state to initial values.
+
+    Intended for use in tests. Clears mutable containers, resets counters,
+    and sets all lazy singletons back to ``None`` so that each test starts
+    from a clean slate.
+    """
+    global compiling_loop, loop_nest_level, cmds_run
+    global conf, last_command, upass
+    global err_halt_writespec, err_halt_email, err_halt_exec
+    global cancel_halt_writespec, cancel_halt_mailspec, cancel_halt_exec
+    global exec_log, subvars, status, if_stack, counters, timer
+    global output, dbs, tempfiles, export_metadata
+    global metacommandlist, conditionallist, filewriter
+    global gui_console, gui_manager_queue, gui_manager_thread
+
+    # Mutable containers — clear in-place (no rebind needed)
+    commandliststack.clear()
+    loopcommandstack.clear()
+    savedscripts.clear()
+
+    # Scalar flags and counters
+    compiling_loop = False
+    loop_nest_level = 0
+    cmds_run = 0
+
+    # Close open database connections before discarding the pool.
+    if dbs is not None:
+        try:
+            dbs.closeall()
+        except Exception:
+            pass
+
+    # Lazy singletons — reset to None
+    conf = None
+    last_command = None
+    upass = None
+    err_halt_writespec = None
+    err_halt_email = None
+    err_halt_exec = None
+    cancel_halt_writespec = None
+    cancel_halt_mailspec = None
+    cancel_halt_exec = None
+    exec_log = None
+    subvars = None
+    status = None
+    if_stack = None
+    counters = None
+    timer = None
+    output = None
+    dbs = None
+    tempfiles = None
+    export_metadata = None
+    metacommandlist = None
+    conditionallist = None
+    # filewriter is a multiprocessing.Process managed by atexit — do NOT null
+    # it here.  Nulling it while the subprocess is alive creates two competing
+    # consumers on the shared fw_input queue, causing test-to-test races.
+    gui_console = None
+    gui_manager_queue = None
+    gui_manager_thread = None
+
+
+def initialize(
+    config: ConfigData,
+    dispatch_table: object,
+    conditional_table: object,
+) -> None:
+    """Initialize the shared runtime singletons for a new execsql run.
+
+    Called once from :func:`execsql.cli._run` after configuration has been
+    loaded.  Consolidates object construction in one place so that the
+    sequence is documented, testable, and not scattered across the CLI
+    entry-point.
+
+    Args:
+        config: A fully-populated :class:`execsql.config.ConfigData` instance.
+        dispatch_table: The metacommand dispatch table
+            (``execsql.metacommands.DISPATCH_TABLE``).
+        conditional_table: The conditional-predicate dispatch table
+            (``execsql.metacommands.conditions.CONDITIONAL_TABLE``).
+
+    Note:
+        ``subvars``, ``status``, ``output``, ``filewriter``, and ``exec_log``
+        are **not** set here because they require CLI-specific arguments
+        (script path, subprocess queues, local class definitions).  Those are
+        assigned directly in ``_run()`` before and after this call.
+    """
+    global conf, if_stack, counters, timer, dbs, tempfiles
+    global export_metadata, metacommandlist, conditionallist
+
+    # These names are re-exported at the bottom of this module (after this
+    # function definition), so they are guaranteed to be available by the time
+    # initialize() is called from cli._run().  Using the module-level names
+    # avoids F811 "redefinition of unused name" from local imports.
+    import execsql.script as _script
+    import execsql.utils.timer as _timer_mod
+    import execsql.db.base as _db_base
+    import execsql.utils.fileio as _fileio_mod
+    import execsql.exporters.base as _exporters_base
+
+    conf = config
+    if_stack = _script.IfLevels()
+    counters = _script.CounterVars()
+    timer = _timer_mod.Timer()
+    dbs = _db_base.DatabasePool()
+    tempfiles = _fileio_mod.TempFileMgr()
+    export_metadata = _exporters_base.ExportMetadata()
+    metacommandlist = dispatch_table
+    conditionallist = conditional_table