execsql2 2.23.1__py3-none-any.whl → 2.25.0__py3-none-any.whl

execsql/cli/options.py

@@ -0,0 +1,108 @@
+"""Options shared by more than one command, each defined once.
+
+A command declares a shared option by annotating a parameter with one of the
+types below, so ``run`` and ``ping`` cannot drift apart on a flag's spelling,
+metavar or help text. Options that belong to a single command stay in that
+command's module.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated
+
+import typer
+
+__all__ = [
+    "ConfigFileOpt",
+    "DbTypeOpt",
+    "DsnOpt",
+    "NoPasswdOpt",
+    "OutputFormat",
+    "OutputFormatOpt",
+    "PortOpt",
+    "ScriptEncodingOpt",
+    "UserOpt",
+]
+
+# -- Connection (run, ping) ----------------------------------------------------
+
+DbTypeOpt = Annotated[
+    str | None,
+    typer.Option(
+        "-t",
+        "--type",
+        metavar="{a,d,p,s,l,m,k,o,f}",
+        help=(
+            "Database type: a=MS-Access, p=PostgreSQL, "
+            "s=SQL Server, l=SQLite, m=MySQL/MariaDB, "
+            "k=DuckDB, o=Oracle, f=Firebird, "
+            "d=DSN."
+        ),
+    ),
+]
+
+DsnOpt = Annotated[
+    str | None,
+    typer.Option(
+        "--dsn",
+        "--connection-string",
+        metavar="URL",
+        help=(
+            "Database connection URL, e.g. postgresql://user:pass@host:5432/db. "
+            "Supported schemes: postgresql (postgres), mysql (mariadb), mssql (sqlserver), oracle, firebird, sqlite, duckdb. "
+            "Overrides -t/-u/-p and positional server/db args."
+        ),
+    ),
+]
+
+UserOpt = Annotated[str | None, typer.Option("-u", "--user", help="Database user name.")]
+
+PortOpt = Annotated[int | None, typer.Option("-p", "--port", help="Database server port.")]
+
+NoPasswdOpt = Annotated[
+    bool,
+    typer.Option("-w", "--no-passwd", help="Skip password prompt when user is specified."),
+]
+
+# -- Configuration (run, ping, config) -----------------------------------------
+
+ConfigFileOpt = Annotated[
+    str | None,
+    typer.Option(
+        "--config",
+        metavar="FILE",
+        help=(
+            "Path to an execsql configuration file. "
+            "Loaded after the implicit search paths so its values take precedence. "
+            "The file may chain additional configs via its [config] section."
+        ),
+    ),
+]
+
+# -- Script files (run, format, lint) ------------------------------------------
+
+ScriptEncodingOpt = Annotated[
+    str | None,
+    typer.Option(
+        "-f",
+        "--script-encoding",
+        metavar="NAME",
+        help="Character encoding of the script file. Default: [encoding] script from a config file, else UTF-8.",
+    ),
+]
+
+# -- Machine-readable output (ping, config, list) ------------------------------
+
+
+class OutputFormat(str, Enum):
+    """Output formats for commands that report data rather than check files."""
+
+    text = "text"
+    json = "json"
+
+
+OutputFormatOpt = Annotated[
+    OutputFormat,
+    typer.Option("--output-format", help="text for people; json for tools."),
+]

execsql/cli/run.py

@@ -33,7 +33,6 @@ __all__ = ["_connect_initial_db", "_ping_db", "_print_dry_run", "_print_profile"
 
 # Lint helper — imported lazily inside _run() to keep start-up cost low, but
 # re-exported here so that tests and callers can reach it via cli.run.
-from execsql.cli.lint import _print_lint_results  # noqa: F401 — re-export (used by cli/__init__.py)
 
 
 # ---------------------------------------------------------------------------
@@ -289,6 +288,21 @@ def _load_config(
     return ConfigData(script_path, subvars, config_file=config_file)
 
 
+def _tool_config(config_file: str | None) -> ConfigData:
+    """The config ``execsql format`` and ``execsql lint`` read.
+
+    Read once per invocation, from the system, user and working-directory
+    locations plus *config_file* — not per script, so a script directory's
+    own ``execsql.conf`` applies only when passed with ``--config``.
+    """
+    return _load_config(None, _seed_early_subvars(), config_file)
+
+
+def _configured_script_encoding(conf: ConfigData) -> str | None:
+    """``[encoding] script`` from *conf*, or ``None`` when no config file sets it."""
+    return conf.script_encoding if "script_encoding" in conf.sources else None
+
+
 def _seed_script_subvars(subvars: SubVarSet, script_name: str | None) -> None:
     """Add substitution variables that depend on the script path."""
     from execsql.utils.errors import file_size_date
@@ -492,14 +506,16 @@ def _setup_logging(
     use_gui: str | None,
     no_passwd: bool,
     import_buffer: int | None,
+    named_vars: list[tuple[str, str]] | None = None,
 ) -> Logger:
-    """Create the execution logger, log initial info, and seed ``$RUN_ID``."""
+    """Create the execution logger, log initial info, and seed ``$RUN_ID``, ``-a`` and ``--var`` values."""
     from execsql.utils.errors import file_size_date
 
     opts_dict = {
         k: v
         for k, v in {
-            "sub_vars": sub_vars,
+            # Count only: -a values are opaque and often secrets.
+            "sub_vars": f"{len(sub_vars)} value(s)" if sub_vars else None,
             "boolean_int": boolean_int,
             "make_dirs": make_dirs,
             "database_encoding": database_encoding,
@@ -520,7 +536,7 @@ def _setup_logging(
     }
     logger = Logger(
         script_name or "<inline>",
-        conf.db or "",
+        conf.db or conf.db_file or "",
         conf.server,
         opts_dict,
         conf.user_logfile,
@@ -537,6 +553,9 @@ def _setup_logging(
         )
 
     subvars.add_substitution("$RUN_ID", logger.run_id)
+    # Passwords from the DSN or config files, known before the first connection.
+    logger.add_redaction_value(getattr(conf, "db_password", None))
+    logger.add_redaction_value(getattr(conf, "smtp_password", None))
 
     if sub_vars:
         for n, repl in enumerate(sub_vars):
@@ -550,6 +569,13 @@ def _setup_logging(
             logger.log_status_info(
                 f"Command-line substitution variable assignment: {var} set to {{***}}",
             )
+    # --var values: named, set after config files so they win over
+    # [variables]; a SUB in the script can still reassign them. Values are
+    # redacted for the same reason as -a's.
+    for name, value in named_vars or ():
+        subvars.add_substitution(name, value)
+        logger.add_redaction_value(value)
+        logger.log_status_info(f"Command-line substitution variable assignment: {name} set to {{***}}")
 
     return logger
 
@@ -587,12 +613,13 @@ def _run(
     profile: bool = False,
     profile_limit: int = 20,
     ping: bool = False,
-    lint: bool = False,
     debug: bool = False,
     no_system_cmd: bool = False,
     no_rm_file: bool = False,
     no_serve: bool = False,
     config_file: str | None = None,
+    named_vars: list[tuple[str, str]] | None = None,
+    manifest_path: str | None = None,
 ) -> None:
     """Initialise state, connect to the database, load the script, and run it.
 
@@ -605,12 +632,6 @@ def _run(
     connection details (DBMS name, server version, and location), and calls
     :func:`_ping_db` which raises ``SystemExit(0)``.  No script is loaded or
     executed.  *script_name* and *command* may both be ``None`` in ping mode.
-
-    When *lint* is ``True``, the script is parsed and statically analysed for
-    structural issues (unmatched IF/ENDIF/LOOP/BATCH blocks, potentially
-    undefined variables, missing INCLUDE files, empty scripts) without
-    connecting to a database or executing anything.  Exits with code 0 if no
-    errors were found, or code 1 if errors were found.
     """
     import execsql.state as _state
 
@@ -698,6 +719,8 @@ def _run(
         if sub_vars:
             for n, repl in enumerate(sub_vars):
                 _state.subvars.add_substitution(f"$ARG_{n + 1}", repl)
+        for name, value in named_vars or ():
+            _state.subvars.add_substitution(name, value)
         _ast_tree = _load_script(command, script_name, conf.script_encoding)
         _print_dry_run(_ast_tree)
         raise SystemExit(0)
@@ -713,27 +736,21 @@ def _run(
         _state.dbs.add("initial", db)
         _ping_db(db)  # raises SystemExit
 
-    import execsql.utils.fileio as _fileio
+    manifest = None
+    if manifest_path:
+        from execsql import manifest as _manifest
+
+        variables = [f"$ARG_{n + 1}" for n in range(len(sub_vars or ()))] + [name for name, _ in named_vars or ()]
+        manifest = _manifest.start(manifest_path, script_name, variables)
+        manifest.config_files = list(conf.files_read)
 
     if _state.filewriter is None or not _state.filewriter.is_alive():
-        # Drain stale messages from the queues so a previously-dead subprocess
-        # can't leak responses or unconsumed commands into the new one. On
-        # macOS (`spawn`) the OS pipe buffer is small enough that retained
-        # entries from a crashed writer would deadlock the next put().
-        for q in (_fileio.fw_input, _fileio.fw_output):
-            try:
-                while True:
-                    q.get_nowait()
-            except Exception:
-                pass
-        _fileio.filewriter = _state.filewriter = FileWriter(
-            _fileio.fw_input,
-            _fileio.fw_output,
+        _state.filewriter = FileWriter(
             file_encoding=conf.output_encoding,
             open_timeout=getattr(conf, "outfile_open_timeout", 10),
         )
         _state.filewriter.start()
-        atexit.register(filewriter_end)
+        atexit.register(filewriter_end, _state.filewriter)
 
     # ------------------------------------------------------------------
     # Logging
@@ -758,6 +775,7 @@ def _run(
         use_gui=use_gui,
         no_passwd=no_passwd,
         import_buffer=import_buffer,
+        named_vars=named_vars,
     )
 
     # ------------------------------------------------------------------
@@ -765,11 +783,6 @@ def _run(
     # ------------------------------------------------------------------
     _ast_tree = _load_script(command, script_name, conf.script_encoding)
 
-    # ------------------------------------------------------------------
-    # NOTE: --lint is handled as an early exit in cli/__init__.py (AST
-    # linter) before _run() is called.  No lint code path here.
-    # ------------------------------------------------------------------
-
     # ------------------------------------------------------------------
     # Start GUI console if requested
     # ------------------------------------------------------------------
@@ -794,6 +807,8 @@ def _run(
         _state.dbs.add("initial", db)
 
     _state.exec_log.log_db_connect(db)
+    if manifest is not None:
+        manifest.set_database(db)
     _state.subvars.add_substitution("$CURRENT_DBMS", db.type.dbms_id)
     _state.subvars.add_substitution("$CURRENT_DATABASE", db.name())
     _state.subvars.add_substitution("$DB_SERVER", db.server_name)
@@ -822,6 +837,8 @@ def _run(
 
     if _ast_tree is not None:
         _execute_script_ast(_ast_tree, conf, profile=profile, profile_limit=profile_limit)
+    if manifest is not None:
+        manifest.finish(0)
 
 
 # ---------------------------------------------------------------------------
@@ -829,6 +846,28 @@ def _run(
 # ---------------------------------------------------------------------------
 
 
+def _end_run_on_sigterm() -> None:
+    """Make SIGTERM end the process through ``SystemExit`` (exit status 143).
+
+    Python's default SIGTERM action stops the process without running
+    ``atexit`` handlers, so the run's log (buffered until close) was lost,
+    the open transaction was not rolled back explicitly, and a running
+    ``SYSTEM_CMD`` was left behind.  ``timeout``, ``docker stop``, systemd
+    and CI cancellation all send SIGTERM.  Installed by the console entry
+    point only: ``execsql.run()`` leaves the host program's signals alone.
+    """
+    import signal
+
+    def _terminate(signum: int, _frame: Any) -> None:
+        import execsql.state as _state
+
+        if _state.exec_log is not None:
+            _state.exec_log.log_exit_terminated()
+        raise SystemExit(128 + signum)
+
+    signal.signal(signal.SIGTERM, _terminate)
+
+
 def _execute_script_ast(
     tree: Any,
     conf: ConfigData,
@@ -856,7 +895,8 @@ def _execute_script_ast(
     try:
         execute(tree)
     except SystemExit as exc:
-        if gui_console_isrunning() and conf.gui_wait_on_exit:
+        terminated = _state.exec_log is not None and _state.exec_log.exit_type == "terminated"
+        if gui_console_isrunning() and conf.gui_wait_on_exit and not terminated:
             gui_console_wait_user(
                 "Script complete; close the console window to exit execsql.",
             )
@@ -868,6 +908,9 @@ def _execute_script_ast(
         sys.exit(exc.code)
     except ConfigError:
         raise
+    except KeyboardInterrupt:
+        _state.exec_log.log_exit_interrupted()
+        raise
     except ErrInfo as exc:
         from execsql.utils.errors import exit_now
 
@@ -881,6 +924,7 @@ def _execute_script_ast(
         exit_now(1, ErrInfo("exception", exception_msg=msg))
 
     _state.dbs.do_rollback = False
+    _flush_output_files()
     if gui_console_isrunning() and conf.gui_wait_on_exit:
         gui_console_wait_user(
             "Script complete; close the console window to exit execsql.",
@@ -943,10 +987,30 @@ def _execute_script_textual_console(tree: Any, conf: ConfigData) -> None:
             exit_now(1, ErrInfo("exception", exception_msg=msg))
 
     _state.dbs.do_rollback = False
+    _flush_output_files()
     _state.exec_log.log_status_info(f"{_state.cmds_run} commands run")
     _state.exec_log.log_exit_end()
 
 
+def _flush_output_files() -> None:
+    """Flush file output at the normal end of a script; lost output fails the run.
+
+    A WRITE/EXPORT target that stays locked past ``outfile_open_timeout`` has
+    its output discarded.  That must not end in a successful exit status.
+    """
+    from execsql.utils.fileio import filewriter_close_all_after_write
+
+    try:
+        filewriter_close_all_after_write()
+    except ErrInfo as exc:
+        from execsql.utils.errors import exit_now
+
+        # The loss belongs to no particular statement; keep exit_now from
+        # attributing it to whatever line happened to run last.
+        exc.script_file = ""
+        exit_now(1, exc)
+
+
 # ---------------------------------------------------------------------------
 # Utility: build the database connection for the initial/default database
 # ---------------------------------------------------------------------------