execsql2 2.5.0__py3-none-any.whl → 2.7.1__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:
@@ -105,156 +103,238 @@ __all__ = [
     "endloop",
     "reset",
     "initialize",
+    # New public API
+    "RuntimeContext",
+    "get_context",
+    "set_context",
 ]
 
 # ---------------------------------------------------------------------------
-# Configuration / encoding
+# Compile-time constants — immutable after module load, stay in __dict__
 # ---------------------------------------------------------------------------
 
-# Configuration data, initialized in main()
-conf: ConfigData | None = None
-
-# Default encodings
-logfile_encoding: str = "utf8"  # Should never be changed; is not configurable.
-
-# ---------------------------------------------------------------------------
-# Runtime state variables
-# ---------------------------------------------------------------------------
-
-# 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:
@@ -266,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(
@@ -367,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

{execsql2-2.5.0.dist-info → execsql2-2.7.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.5.0
+Version: 2.7.1
 Summary: Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables.
 Project-URL: Repository, https://github.com/geocoug/execsql
 Project-URL: Issues, https://github.com/geocoug/execsql/issues
@@ -54,6 +54,7 @@ Requires-Dist: polars; extra == 'all'
 Requires-Dist: psycopg2-binary; extra == 'all'
 Requires-Dist: pymysql; extra == 'all'
 Requires-Dist: pyodbc; extra == 'all'
+Requires-Dist: pyyaml; extra == 'all'
 Requires-Dist: tables; extra == 'all'
 Requires-Dist: xlrd; extra == 'all'
 Provides-Extra: all-db
@@ -76,6 +77,7 @@ Requires-Dist: openpyxl; extra == 'dev'
 Requires-Dist: polars; extra == 'dev'
 Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pyyaml; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Requires-Dist: tables; extra == 'dev'
 Requires-Dist: tox-uv>=1.13.1; extra == 'dev'
@@ -91,6 +93,7 @@ Requires-Dist: jinja2; extra == 'formats'
 Requires-Dist: odfpy; extra == 'formats'
 Requires-Dist: openpyxl; extra == 'formats'
 Requires-Dist: polars; extra == 'formats'
+Requires-Dist: pyyaml; extra == 'formats'
 Requires-Dist: tables; extra == 'formats'
 Requires-Dist: xlrd; extra == 'formats'
 Provides-Extra: mssql
@@ -227,7 +230,7 @@ Run `execsql --help` for the full option list, or `execsql -m` to list all metac
 # Features
 
 - Import data from CSV, TSV, Excel, OpenDocument, Feather, or Parquet files into a database table.
-- Export query results in 15+ formats including CSV, TSV, JSON, XML, HTML, LaTeX, OpenDocument, Feather, HDF5, DuckDB, SQLite, plain text, and Jinja2 templates.
+- Export query results in 20+ formats including CSV, TSV, JSON, YAML, XML, HTML, Markdown, LaTeX, XLSX, OpenDocument, Feather, Parquet, HDF5, DuckDB, SQLite, plain text, and Jinja2 templates.
 - Copy data between databases, including across different DBMS types.
 - Conditionally execute SQL and metacommands using `IF`/`ELSE`/`ENDIF` based on data values, DBMS type, or user input.
 - Loop over blocks of SQL and metacommands using `LOOP`/`ENDLOOP`.