execsql2 2.4.5__py3-none-any.whl → 2.6.0__py3-none-any.whl

execsql/state.py

@@ -12,27 +12,25 @@ and then access attributes (``_state.conf``, ``_state.subvars``, etc.)
 inside function/method bodies — never at class-definition time — to avoid
 circular-import issues at load time.
 
-Variable groups defined here:
-
-- **Configuration** — ``conf`` (:class:`execsql.config.ConfigData`),
-  ``logfile_encoding``.
-- **Runtime flags** — ``last_command``, ``upass``, ``varlike`` regex,
-  halt/cancel write-spec and mail-spec objects.
-- **Execution stack** — ``commandliststack``, ``savedscripts``,
-  ``loopcommandstack``, ``compiling_loop``, loop regexes and nesting counter.
-- **Lazy singletons** — ``if_stack``, ``counters``, ``timer``, ``output``,
-  ``dbs``, ``tempfiles``, ``export_metadata``, ``metacommandlist``,
-  ``filewriter``, ``gui_console``, GUI queue/thread.
-- **Version** — ``primary_vno``, ``secondary_vno``, ``tertiary_vno`` parsed
-  from ``__version__``.
-- **Utility functions** — ``xcmd_test()`` (evaluate a conditional string),
-  ``endloop()`` (finalise a compiled loop).
-
-All re-exports have been removed. Each module now imports directly from
-its source module rather than accessing names via ``_state``.
+Internally, all mutable state lives on a :class:`RuntimeContext` instance
+(``_ctx``).  The module's ``__class__`` is swapped to a custom
+:class:`types.ModuleType` subclass that transparently proxies attribute
+reads and writes to the active context.  This means:
+
+- External code continues to use ``_state.conf``, ``_state.subvars = ...``,
+  etc. with zero changes.
+- Functions *within* this module use ``_ctx.conf``, ``_ctx.subvars``, etc.
+  directly, because Python's ``LOAD_GLOBAL`` / ``STORE_GLOBAL`` bytecodes
+  access ``__dict__`` directly and do not trigger ``__getattr__`` /
+  ``__setattr__`` on the module class.
+
+Use :func:`get_context` / :func:`set_context` to obtain or replace the
+active context programmatically.
 """
 
 import re
+import sys
+import types
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
@@ -55,154 +53,288 @@ if TYPE_CHECKING:
     from execsql.utils.mail import MailSpec
     from execsql.utils.timer import Timer
 
-# ---------------------------------------------------------------------------
-# Configuration / encoding
-# ---------------------------------------------------------------------------
-
-# Configuration data, initialized in main()
-conf: ConfigData | None = None
-
-# Default encodings
-logfile_encoding: str = "utf8"  # Should never be changed; is not configurable.
+__all__ = [
+    # Configuration / encoding
+    "conf",
+    "logfile_encoding",
+    # Runtime state
+    "last_command",
+    "upass",
+    "varlike",
+    "err_halt_writespec",
+    "err_halt_email",
+    "err_halt_exec",
+    "cancel_halt_writespec",
+    "cancel_halt_mailspec",
+    "cancel_halt_exec",
+    "commandliststack",
+    "savedscripts",
+    "loopcommandstack",
+    "compiling_loop",
+    "endloop_rx",
+    "loop_rx",
+    "loop_nest_level",
+    "cmds_run",
+    "defer_rx",
+    "stringtypes",
+    "exec_log",
+    "subvars",
+    "status",
+    # Lazy singletons
+    "if_stack",
+    "counters",
+    "timer",
+    "output",
+    "dbs",
+    "tempfiles",
+    "export_metadata",
+    "metacommandlist",
+    "conditionallist",
+    "filewriter",
+    "gui_console",
+    "gui_manager_queue",
+    "gui_manager_thread",
+    # Version
+    "primary_vno",
+    "secondary_vno",
+    "tertiary_vno",
+    # Functions
+    "xcmd_test",
+    "endloop",
+    "reset",
+    "initialize",
+    # New public API
+    "RuntimeContext",
+    "get_context",
+    "set_context",
+]
 
 # ---------------------------------------------------------------------------
-# Runtime state variables
+# Compile-time constants — immutable after module load, stay in __dict__
 # ---------------------------------------------------------------------------
 
-# The last command run.  This should be a ScriptCmd object.
-last_command: ScriptCmd | None = None
-
-# The last user password entered via 'get_password()'
-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: WriteSpec | None = None
-
-# A MailSpec object for email to be sent when the program halts due to an error.
-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: ScriptExecSpec | None = None
-
-# A WriteSpec object for messages to be written when the program halts due to user cancellation.
-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: MailSpec | None = None
-
-# A ScriptExecSpec object for a script to be executed when the program halts due to user cancellation.
-cancel_halt_exec: ScriptExecSpec | None = None
-
-# A stack of the CommandList objects currently in the queue to be executed.
-commandliststack: list[CommandList] = []
-
-# A dictionary of CommandList objects (ordinarily created by BEGIN/END SCRIPT metacommands).
-savedscripts: dict[str, CommandList] = {}
-
-# A stack of CommandList objects used when compiling the statements within a loop.
-loopcommandstack: list[CommandList] = []
-
-# A global flag to indicate that commands should be compiled into the topmost entry
-# in the loopcommandstack rather than executed.
-compiling_loop: bool = False
-
 # Compiled regex for END LOOP metacommand, which is immediate.
 endloop_rx = re.compile(r"^\s*END\s+LOOP\s*$", re.I)
 
-# Compiled regex for *start of* LOOP metacommand, for testing while compiling commands within a loop.
+# Compiled regex for *start of* LOOP metacommand, for testing while compiling
+# commands within a loop.
 loop_rx = re.compile(r"\s*LOOP\s+", re.I)
 
-# Nesting counter, to ensure loops are only ended when nesting level is zero.
-loop_nest_level: int = 0
-
-# A count of all of the commands run.
-cmds_run: int = 0
-
 # Pattern for deferred substitution, e.g.: "!{somevar}!"
 defer_rx = re.compile(r"(!{([$@&~#]?[a-z0-9_]+)}!)", re.I)
 
 # The string type (str in Python 3).
 stringtypes: type = str
 
-# The execution log object; set at startup.
-exec_log: Logger | None = None
-
-# The substitution variable set; set at startup.
-subvars: SubVarSet | None = None
-
-# The program execution status tracker; set at startup.
-status: StatObj | None = None
-
 # ---------------------------------------------------------------------------
-# Runtime objects — initialized in main() to avoid circular imports at load time.
+# Version numbers (parsed from package __version__)
 # ---------------------------------------------------------------------------
 
-# Stack-based conditional state (IfLevels instance).
-if_stack: IfLevels | None = None
+try:
+    from execsql import __version__ as _pkg_version
 
-# Global counter variables (CounterVars instance).
-counters: CounterVars | None = None
+    _vparts = _pkg_version.split(".")
+    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 = 0
+    secondary_vno = 0
+    tertiary_vno = 0
 
-# Elapsed-time tracker (Timer instance).
-timer: Timer | None = None
 
-# Redirectable output (WriteHooks instance).
-output: WriteHooks | None = None
+# ---------------------------------------------------------------------------
+# RuntimeContext — holds all mutable state for a single execsql session
+# ---------------------------------------------------------------------------
 
-# Database connection pool (DatabasePool instance).
-dbs: DatabasePool | None = None
+_CONTEXT_ATTRS: frozenset[str] = frozenset(
+    {
+        # Configuration
+        "conf",
+        "logfile_encoding",
+        # Runtime flags
+        "last_command",
+        "upass",
+        "err_halt_writespec",
+        "err_halt_email",
+        "err_halt_exec",
+        "cancel_halt_writespec",
+        "cancel_halt_mailspec",
+        "cancel_halt_exec",
+        # Execution stack
+        "commandliststack",
+        "savedscripts",
+        "loopcommandstack",
+        "compiling_loop",
+        "loop_nest_level",
+        "cmds_run",
+        # I/O
+        "exec_log",
+        "subvars",
+        "status",
+        "output",
+        "filewriter",
+        # Lazy singletons
+        "if_stack",
+        "counters",
+        "timer",
+        "dbs",
+        "tempfiles",
+        "export_metadata",
+        "metacommandlist",
+        "conditionallist",
+        # GUI
+        "gui_console",
+        "gui_manager_queue",
+        "gui_manager_thread",
+    },
+)
+
+
+class RuntimeContext:
+    """All mutable runtime state for a single execsql execution session.
+
+    A fresh instance provides clean default values identical to the original
+    module-level declarations.  Use :func:`get_context` to obtain the active
+    instance, or :func:`set_context` to replace it.
+    """
 
-# Temporary file manager (TempFileMgr instance).
-tempfiles: TempFileMgr | None = None
+    __slots__ = (
+        # Configuration
+        "conf",
+        "logfile_encoding",
+        # Runtime flags
+        "last_command",
+        "upass",
+        "err_halt_writespec",
+        "err_halt_email",
+        "err_halt_exec",
+        "cancel_halt_writespec",
+        "cancel_halt_mailspec",
+        "cancel_halt_exec",
+        # Execution stack
+        "commandliststack",
+        "savedscripts",
+        "loopcommandstack",
+        "compiling_loop",
+        "loop_nest_level",
+        "cmds_run",
+        # I/O
+        "exec_log",
+        "subvars",
+        "status",
+        "output",
+        "filewriter",
+        # Lazy singletons
+        "if_stack",
+        "counters",
+        "timer",
+        "dbs",
+        "tempfiles",
+        "export_metadata",
+        "metacommandlist",
+        "conditionallist",
+        # GUI
+        "gui_console",
+        "gui_manager_queue",
+        "gui_manager_thread",
+    )
 
-# Export metadata tracker (ExportMetadata instance).
-export_metadata: ExportMetadata | None = None
+    def __init__(self) -> None:
+        # Configuration
+        self.conf: ConfigData | None = None
+        self.logfile_encoding: str = "utf8"
+
+        # Runtime flags
+        self.last_command: ScriptCmd | None = None
+        self.upass: str | None = None
+        self.err_halt_writespec: WriteSpec | None = None
+        self.err_halt_email: MailSpec | None = None
+        self.err_halt_exec: ScriptExecSpec | None = None
+        self.cancel_halt_writespec: WriteSpec | None = None
+        self.cancel_halt_mailspec: MailSpec | None = None
+        self.cancel_halt_exec: ScriptExecSpec | None = None
+
+        # Execution stack
+        self.commandliststack: list[CommandList] = []
+        self.savedscripts: dict[str, CommandList] = {}
+        self.loopcommandstack: list[CommandList] = []
+        self.compiling_loop: bool = False
+        self.loop_nest_level: int = 0
+        self.cmds_run: int = 0
+
+        # I/O
+        self.exec_log: Logger | None = None
+        self.subvars: SubVarSet | None = None
+        self.status: StatObj | None = None
+        self.output: WriteHooks | None = None
+        self.filewriter: FileWriter | None = None
+
+        # Lazy singletons
+        self.if_stack: IfLevels | None = None
+        self.counters: CounterVars | None = None
+        self.timer: Timer | None = None
+        self.dbs: DatabasePool | None = None
+        self.tempfiles: TempFileMgr | None = None
+        self.export_metadata: ExportMetadata | None = None
+        self.metacommandlist: MetaCommandList | None = None
+        self.conditionallist: MetaCommandList | None = None
+
+        # GUI
+        self.gui_console: Any = None
+        self.gui_manager_queue: _mp.Queue | None = None
+        self.gui_manager_thread: _threading.Thread | None = None
 
-# Metacommand dispatch table (MetaCommandList instance).
-metacommandlist: MetaCommandList | None = None
 
-# Conditional predicate dispatch table (MetaCommandList instance).
-conditionallist: MetaCommandList | None = None
+# ---------------------------------------------------------------------------
+# Module proxy — transparently delegates context attr access to _ctx
+# ---------------------------------------------------------------------------
 
-# Asynchronous file-writer subprocess (FileWriter instance).
-filewriter: FileWriter | None = None
 
-# GUI console object.
-gui_console: Any = None  # Varies by backend (ConsoleUI, DesktopUI, TextualUI).
+class _StateModule(types.ModuleType):
+    """Module subclass that proxies mutable state attributes to the active RuntimeContext."""
 
-# Queue and thread used to communicate with the GUI manager.
-gui_manager_queue: _mp.Queue | None = None
-gui_manager_thread: _threading.Thread | None = None
+    def __getattr__(self, name: str) -> Any:
+        if name in _CONTEXT_ATTRS:
+            return getattr(self.__dict__["_ctx"], name)
+        raise AttributeError(f"module {self.__name__!r} has no attribute {name!r}")
 
-# ---------------------------------------------------------------------------
-# Version numbers (parsed from package __version__)
-# ---------------------------------------------------------------------------
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name in _CONTEXT_ATTRS:
+            setattr(self.__dict__["_ctx"], name, value)
+        else:
+            super().__setattr__(name, value)
 
-try:
-    from execsql import __version__ as _pkg_version
+    def __delattr__(self, name: str) -> None:
+        if name in _CONTEXT_ATTRS:
+            # Reset to the fresh-context default.  Needed for
+            # unittest.mock.patch compatibility: patch checks
+            # ``name in target.__dict__`` to decide whether to restore
+            # via setattr (local) or delattr (non-local).  Since context
+            # attrs live on _ctx, not __dict__, patch takes the delattr
+            # path.  We reset to the default rather than truly deleting.
+            _defaults = RuntimeContext()
+            setattr(self.__dict__["_ctx"], name, getattr(_defaults, name))
+        else:
+            super().__delattr__(name)
+
+    def __dir__(self) -> list[str]:
+        return sorted(set(super().__dir__()) | _CONTEXT_ATTRS)
 
-    _vparts = _pkg_version.split(".")
-    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 = 0
-    secondary_vno = 0
-    tertiary_vno = 0
 
 # ---------------------------------------------------------------------------
-# Utility functions defined directly here to avoid circular imports.
+# Utility functions — use _ctx directly (LOAD_GLOBAL bypasses the proxy)
 # ---------------------------------------------------------------------------
 
 
 def xcmd_test(teststr: str) -> bool:
     """Evaluate a conditional test string and return a boolean result."""
-    import execsql.parser as _parser
     import execsql.exceptions as _exc
+    import execsql.parser as _parser
 
     result = _parser.CondParser(teststr).parse().eval()
     if result is not None:
@@ -214,80 +346,60 @@ def endloop() -> None:
     """Complete the current loop being compiled and push it onto the command stack."""
     import execsql.exceptions as _exc
 
-    global compiling_loop
-    if len(loopcommandstack) == 0:
+    if len(_ctx.loopcommandstack) == 0:
         raise _exc.ErrInfo("error", other_msg="END LOOP metacommand without a matching preceding LOOP metacommand.")
-    compiling_loop = False
-    commandliststack.append(loopcommandstack[-1])
-    loopcommandstack.pop()
+    _ctx.compiling_loop = False
+    _ctx.commandliststack.append(_ctx.loopcommandstack[-1])
+    _ctx.loopcommandstack.pop()
 
 
 # ---------------------------------------------------------------------------
-# Test-support utilities
+# Context management
+# ---------------------------------------------------------------------------
+
+
+def get_context() -> RuntimeContext:
+    """Return the active :class:`RuntimeContext`."""
+    return _ctx
+
+
+def set_context(ctx: RuntimeContext) -> None:
+    """Replace the active :class:`RuntimeContext`.
+
+    Args:
+        ctx: The new context to install.  All subsequent ``_state.foo``
+            accesses will resolve against this instance.
+    """
+    global _ctx
+    _ctx = ctx
+
+
+# ---------------------------------------------------------------------------
+# Initialization and reset
 # ---------------------------------------------------------------------------
 
 
 def reset() -> None:
-    """Reset all module-level state to initial values.
+    """Reset all mutable 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.
+    Intended for use in tests.  Creates a fresh :class:`RuntimeContext`,
+    preserving only the ``filewriter`` subprocess (which is ``atexit``-managed
+    and must not be discarded while alive).
     """
-    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
+    global _ctx
+
+    # Preserve filewriter — it's atexit-managed and must survive resets.
+    old_fw = _ctx.filewriter
 
     # Close open database connections before discarding the pool.
-    if dbs is not None:
+    if _ctx.dbs is not None:
         try:
-            dbs.closeall()
+            _ctx.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
+    _ctx = RuntimeContext()
+    _ctx.filewriter = old_fw
 
 
 def initialize(
@@ -315,25 +427,26 @@ def initialize(
         (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
+    import execsql.script as _script
+    import execsql.utils.fileio as _fileio_mod
+    import execsql.utils.timer as _timer_mod
+
+    _ctx.conf = config
+    _ctx.if_stack = _script.IfLevels()
+    _ctx.counters = _script.CounterVars()
+    _ctx.timer = _timer_mod.Timer()
+    _ctx.dbs = _db_base.DatabasePool()
+    _ctx.tempfiles = _fileio_mod.TempFileMgr()
+    _ctx.export_metadata = _exporters_base.ExportMetadata()
+    _ctx.metacommandlist = dispatch_table
+    _ctx.conditionallist = conditional_table
+
+
+# ---------------------------------------------------------------------------
+# Bootstrap — create the initial context and swap the module class
+# ---------------------------------------------------------------------------
 
-    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
+_ctx = RuntimeContext()
+sys.modules[__name__].__class__ = _StateModule