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

execsql/cli/__init__.py

@@ -5,10 +5,13 @@ initialisation, database connection, and script execution.
 
 Submodules:
 
-- :mod:`execsql.cli.help`      — Rich-formatted help output & console objects
+- :mod:`execsql.cli.application` — the Typer app, its command group, and plain help rendering
+- :mod:`execsql.cli.commands`  — one module per command (``run``, ``format``, ``lint``)
+- :mod:`execsql.cli.dispatch`  — the rule that inserts ``run`` when no command is given
+- :mod:`execsql.cli.help`      — metacommand/encoding tables, --init-config, console objects
 - :mod:`execsql.cli.dsn`       — Connection-string (DSN URL) parser
 - :mod:`execsql.cli.run`       — Core execution logic (``_run``, ``_connect_initial_db``, ``_ping_db``, ``_print_dry_run``, ``_print_profile``)
-- :mod:`execsql.cli.lint`      — AST-based ``--lint`` static analyser and Rich result printer
+- :mod:`execsql.cli.lint`      — AST-based static analyser behind ``execsql lint``, and its output formats
 """
 
 from __future__ import annotations
@@ -17,13 +20,14 @@ import sys
 import traceback
 from pathlib import Path
 
-import typer
-
-from execsql import __version__
+from execsql.cli import commands  # noqa: F401 — registers every command on app
+from execsql.cli.application import app
+from execsql.cli.commands.run import main
 from execsql.cli.dsn import _parse_connection_string, _SCHEME_TO_DBTYPE  # noqa: F401 — re-export
 from execsql.cli.help import _console, _err_console, _init_config, _print_encodings, _print_metacommands  # noqa: F401 — re-export
 from execsql.cli.run import _connect_initial_db, _run  # noqa: F401 — re-export
-from execsql.exceptions import ConfigError, ErrInfo
+from execsql.cli.run import _end_run_on_sigterm
+from execsql.exceptions import ConfigError, ConfigFileError, ErrInfo
 
 __all__ = [
     "_SCHEME_TO_DBTYPE",
@@ -41,583 +45,6 @@ __all__ = [
 ]
 
 
-# ---------------------------------------------------------------------------
-# Typer app
-# ---------------------------------------------------------------------------
-
-app = typer.Typer(
-    name="execsql",
-    help="Run a SQL script against a database with metacommand support.",
-    add_completion=False,
-    rich_markup_mode="rich",
-    no_args_is_help=True,
-)
-
-
-def _version_callback(value: bool) -> None:
-    if value:
-        _console.print(f"execsql [bold cyan]{__version__}[/bold cyan]")
-        raise typer.Exit()
-
-
-@app.command(
-    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
-)
-def main(
-    ctx: typer.Context,
-    # Positional args collected manually (script + optional server/db/file)
-    args: list[str] | None = typer.Argument(
-        None,
-        metavar="SQL_SCRIPT [SERVER DATABASE | DATABASE_FILE]",
-        help=(
-            "SQL script file to execute. Optionally followed by server and database "
-            "name (client-server DBs) or a database file path (file-based DBs)."
-        ),
-    ),
-    # -- Connection --------------------------------------------------------
-    db_type: str | None = typer.Option(
-        None,
-        "-t",
-        "--type",
-        metavar="{a,d,p,s,l,m,k,o,f}",
-        help=(
-            "Database type: [bold]a[/bold]=MS-Access, [bold]p[/bold]=PostgreSQL, "
-            "[bold]s[/bold]=SQL Server, [bold]l[/bold]=SQLite, [bold]m[/bold]=MySQL/MariaDB, "
-            "[bold]k[/bold]=DuckDB, [bold]o[/bold]=Oracle, [bold]f[/bold]=Firebird, "
-            "[bold]d[/bold]=DSN."
-        ),
-    ),
-    dsn: str | None = typer.Option(
-        None,
-        "--dsn",
-        "--connection-string",
-        metavar="URL",
-        help=(
-            "Database connection URL, e.g. [cyan]postgresql://user:pass@host:5432/db[/cyan]. "
-            "Supported schemes: postgresql, mysql, mssql, oracle, firebird, sqlite, duckdb. "
-            "Overrides [cyan]-t[/cyan]/[cyan]-u[/cyan]/[cyan]-p[/cyan] and positional server/db args."
-        ),
-    ),
-    user: str | None = typer.Option(
-        None,
-        "-u",
-        "--user",
-        help="Database user name.",
-    ),
-    port: int | None = typer.Option(
-        None,
-        "-p",
-        "--port",
-        help="Database server port.",
-    ),
-    no_passwd: bool = typer.Option(
-        False,
-        "-w",
-        "--no-passwd",
-        help="Skip password prompt when user is specified.",
-    ),
-    new_db: bool = typer.Option(
-        False,
-        "-n",
-        "--new-db",
-        help="Create a new SQLite or Postgres database if it does not exist.",
-    ),
-    # -- Encoding ----------------------------------------------------------
-    database_encoding: str | None = typer.Option(
-        None,
-        "-e",
-        "--database-encoding",
-        help="Character encoding used in the database.",
-    ),
-    script_encoding: str | None = typer.Option(
-        None,
-        "-f",
-        "--script-encoding",
-        help="Character encoding of the script file. [dim]Default: UTF-8[/dim]",
-    ),
-    output_encoding: str | None = typer.Option(
-        None,
-        "-g",
-        "--output-encoding",
-        help="Encoding for WRITE and EXPORT output.",
-    ),
-    import_encoding: str | None = typer.Option(
-        None,
-        "-i",
-        "--import-encoding",
-        help="Encoding for data files used with IMPORT.",
-    ),
-    # -- Import/Export -----------------------------------------------------
-    import_buffer: int | None = typer.Option(
-        None,
-        "-z",
-        "--import-buffer",
-        metavar="KB",
-        help="Import buffer size in KB. [dim]Default: 32[/dim]",
-    ),
-    scanlines: int | None = typer.Option(
-        None,
-        "-s",
-        "--scan-lines",
-        metavar="N",
-        help="Lines to scan for IMPORT format detection. [dim]0 = scan entire file.[/dim]",
-    ),
-    boolean_int: str | None = typer.Option(
-        None,
-        "-b",
-        "--boolean-int",
-        metavar="{0,1,t,f,y,n}",
-        help="Treat integers 0 and 1 as boolean values.",
-    ),
-    make_dirs: str | None = typer.Option(
-        None,
-        "-d",
-        "--directories",
-        metavar="{0,1,t,f,y,n}",
-        help="Auto-create directories for EXPORT metacommand. [dim]n=no (default), y=yes[/dim]",
-    ),
-    output_dir: str | None = typer.Option(
-        None,
-        "--output-dir",
-        metavar="DIR",
-        help=(
-            "Default base directory for EXPORT output files. "
-            "Relative paths in EXPORT metacommands are joined to this directory. "
-            "Absolute paths and [cyan]stdout[/cyan] are unaffected."
-        ),
-    ),
-    progress: bool = typer.Option(
-        False,
-        "--progress",
-        help="Show a progress bar for long-running IMPORT operations.",
-    ),
-    # -- Execution ---------------------------------------------------------
-    command: str | None = typer.Option(
-        None,
-        "-c",
-        "--command",
-        metavar="SCRIPT",
-        help=(
-            "Execute an inline SQL/metacommand script string instead of a script file. "
-            "Use shell [cyan]$'line1\\nline2'[/cyan] syntax for multi-line scripts."
-        ),
-    ),
-    dry_run: bool = typer.Option(
-        False,
-        "--dry-run",
-        help="Parse the script and print the command list without connecting to a database or executing anything.",
-    ),
-    lint: bool = typer.Option(
-        False,
-        "--lint",
-        help=(
-            "Parse the script and perform static analysis without connecting to a database or executing anything. "
-            "Reports unmatched IF/ENDIF/LOOP/BATCH blocks (errors), potentially undefined variables, "
-            "and missing INCLUDE files (warnings). Exits 0 if no errors, 1 if errors found."
-        ),
-    ),
-    parse_tree: bool = typer.Option(
-        False,
-        "--parse-tree",
-        help=(
-            "Parse the script into an abstract syntax tree and print the tree structure. "
-            "Does not connect to a database or execute anything."
-        ),
-    ),
-    debug: bool = typer.Option(
-        False,
-        "--debug",
-        help="Start in step-through debug mode. The debug REPL pauses before each statement.",
-    ),
-    no_system_cmd: bool = typer.Option(
-        False,
-        "--no-system-cmd",
-        help="Disable the SYSTEM_CMD (SHELL) metacommand. Scripts that use SHELL will fail with an error.",
-    ),
-    no_rm_file: bool = typer.Option(
-        False,
-        "--no-rm-file",
-        help="Disable the RM_FILE metacommand. Scripts that try to delete files will fail with an error.",
-    ),
-    no_serve: bool = typer.Option(
-        False,
-        "--no-serve",
-        help="Disable the SERVE metacommand. Scripts that try to stream a file to stdout will fail with an error.",
-    ),
-    profile: bool = typer.Option(
-        False,
-        "--profile",
-        help="Record per-statement execution times and print a timing summary after the script completes.",
-    ),
-    profile_limit: int = typer.Option(
-        20,
-        "--profile-limit",
-        help="Number of top statements to show in the --profile timing summary (default: 20).",
-    ),
-    # -- GUI ---------------------------------------------------------------
-    use_gui: str | None = typer.Option(
-        None,
-        "-v",
-        "--visible-prompts",
-        metavar="{0,1,2,3}",
-        help=(
-            "GUI level: [bold]0[/bold]=none (default), [bold]1[/bold]=GUI for password/pause, "
-            "[bold]2[/bold]=GUI for password/pause + DB selection, [bold]3[/bold]=full GUI console."
-        ),
-    ),
-    gui_framework: str | None = typer.Option(
-        None,
-        "--gui-framework",
-        metavar="{tkinter,textual}",
-        help="GUI framework to use with [cyan]--visible-prompts[/cyan]. [dim]Default: tkinter[/dim]",
-    ),
-    # -- Configuration -----------------------------------------------------
-    config_file: str | None = typer.Option(
-        None,
-        "--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 [cyan][config][/cyan] section."
-        ),
-    ),
-    init_config: bool = typer.Option(
-        False,
-        "--init-config",
-        help="Print a default [cyan]execsql.conf[/cyan] template to stdout and exit.",
-    ),
-    sub_vars: list[str] | None = typer.Option(
-        None,
-        "-a",
-        "--assign-arg",
-        metavar="VALUE",
-        help="Define the replacement string for a substitution variable [cyan]$ARG_x[/cyan].",
-    ),
-    user_logfile: bool = typer.Option(
-        False,
-        "-l",
-        "--user-logfile",
-        help="Write a log file to [cyan]~/execsql.log[/cyan].",
-    ),
-    # -- Information -------------------------------------------------------
-    metacommands: bool = typer.Option(
-        False,
-        "-m",
-        "--metacommands",
-        help="List metacommands and exit.",
-    ),
-    encodings: bool = typer.Option(
-        False,
-        "-y",
-        "--encodings",
-        help="List available encoding names and exit.",
-    ),
-    dump_keywords: bool = typer.Option(
-        False,
-        "--dump-keywords",
-        help="Dump all metacommand keywords as JSON and exit.",
-    ),
-    list_plugins: bool = typer.Option(
-        False,
-        "--list-plugins",
-        help="List all discovered plugins (metacommands, exporters, importers) and exit.",
-    ),
-    ping: bool = typer.Option(
-        False,
-        "--ping",
-        help=(
-            "Test database connectivity and exit. "
-            "Prints connection details and the server version on success (exit 0), "
-            "or the error message on failure (exit 1). "
-            "No script file is required."
-        ),
-    ),
-    online_help: bool = typer.Option(
-        False,
-        "-o",
-        "--online-help",
-        help="Open the online documentation in the default browser.",
-    ),
-    version: bool | None = typer.Option(
-        None,
-        "--version",
-        callback=_version_callback,
-        is_eager=True,
-        help="Show version and exit.",
-    ),
-) -> None:
-    """Run [bold]SQL_SCRIPT[/bold] against the specified database.
-
-    [dim]Positional arguments after the script file:[/dim]
-
-    [green]Client-server databases:[/green]
-      execsql script.sql [SERVER] [DATABASE]
-
-    [green]File-based databases (SQLite, DuckDB, Access):[/green]
-      execsql script.sql [DATABASE_FILE]
-    """
-    # ------------------------------------------------------------------
-    # Early exits (no script file needed)
-    # ------------------------------------------------------------------
-    if metacommands:
-        _print_metacommands()
-        raise typer.Exit()
-
-    if encodings:
-        _print_encodings()
-        raise typer.Exit()
-
-    if init_config:
-        _init_config()
-        raise typer.Exit()
-
-    if dump_keywords:
-        import json as _json
-
-        from execsql.metacommands import (
-            ALL_EXPORT_FORMATS,
-            DATABASE_TYPES,
-            DISPATCH_TABLE,
-            JSON_VARIANT_FORMATS,
-            METADATA_FORMATS,
-            QUERY_EXPORT_FORMATS,
-            SERVE_FORMATS,
-            TABLE_EXPORT_FORMATS,
-        )
-        from execsql.metacommands.conditions import CONDITIONAL_TABLE
-
-        mc_kw = DISPATCH_TABLE.keywords_by_category()
-        cond_kw = CONDITIONAL_TABLE.keywords_by_category()
-
-        data = {
-            "metacommands": {
-                "control": sorted(mc_kw.get("control", [])),
-                "block": sorted(
-                    mc_kw.get("block", []) + ["BEGIN SCRIPT", "END SCRIPT", "BEGIN SQL", "END SQL"],
-                ),
-                "action": sorted(mc_kw.get("action", [])),
-                "config": sorted(mc_kw.get("config", [])),
-                "prompt": sorted(mc_kw.get("prompt", [])),
-            },
-            "conditions": sorted(cond_kw.get("condition", []) + ["IS_FALSE", "NOT", "OR"]),
-            "config_options": sorted(mc_kw.get("config_option", [])),
-            "export_formats": {
-                "query": sorted(QUERY_EXPORT_FORMATS),
-                "table": sorted(TABLE_EXPORT_FORMATS),
-                "serve": sorted(SERVE_FORMATS),
-                "metadata": sorted(METADATA_FORMATS),
-                "json_variants": sorted(JSON_VARIANT_FORMATS),
-                "all": sorted(ALL_EXPORT_FORMATS),
-            },
-            "database_types": sorted(DATABASE_TYPES),
-            "variable_patterns": {
-                "system": "!!$name!!",
-                "environment": "!!&name!!",
-                "parameter": "!!#name!!",
-                "column": "!!@name!!",
-                "local": "!!~name!!",
-                "local_alt": "!!+name!!",
-                "regular": "!!name!!",
-                "deferred": "!{name}!",
-            },
-        }
-        _console.print_json(_json.dumps(data, indent=2))
-        raise typer.Exit()
-
-    if list_plugins:
-        from execsql.plugins import (
-            EXPORTER_GROUP,
-            IMPORTER_GROUP,
-            METACOMMAND_GROUP,
-            _load_entry_points,
-        )
-
-        _console.print("\n[bold cyan]Installed plugins:[/bold cyan]\n")
-
-        mc_plugins = _load_entry_points(METACOMMAND_GROUP)
-        ex_plugins = _load_entry_points(EXPORTER_GROUP)
-        im_plugins = _load_entry_points(IMPORTER_GROUP)
-
-        if not mc_plugins and not ex_plugins and not im_plugins:
-            _console.print("  [dim]No plugins found.[/dim]")
-            _console.print()
-            _console.print(
-                "  Plugins are discovered via Python entry points.\n"
-                "  See the execsql documentation for how to create plugins.",
-            )
-        else:
-            if mc_plugins:
-                _console.print(f"  [bold]Metacommands[/bold] ({len(mc_plugins)}):")
-                for name, _ in mc_plugins:
-                    _console.print(f"    - {name}")
-            if ex_plugins:
-                _console.print(f"  [bold]Exporters[/bold] ({len(ex_plugins)}):")
-                for name, _ in ex_plugins:
-                    _console.print(f"    - {name}")
-            if im_plugins:
-                _console.print(f"  [bold]Importers[/bold] ({len(im_plugins)}):")
-                for name, _ in im_plugins:
-                    _console.print(f"    - {name}")
-
-        _console.print()
-        raise typer.Exit()
-
-    if online_help:
-        import webbrowser
-
-        webbrowser.open("https://execsql2.readthedocs.io/en/latest/", new=2, autoraise=True)
-        raise typer.Exit()
-
-    if config_file and not Path(config_file).is_file():
-        _err_console.print(
-            f"[bold red]Error:[/bold red] Config file [cyan]{config_file!r}[/cyan] does not exist.",
-        )
-        raise typer.Exit(code=2)
-
-    positional = args or []
-    if command is not None:
-        script_name = None  # inline mode — no script file
-    elif ping:
-        # --ping does not require a script file; positional args are still
-        # available for server/db arguments if --dsn is not used.
-        script_name = None
-    else:
-        if not positional:
-            _err_console.print(
-                "[bold red]Error:[/bold red] No SQL script file specified. Use [cyan]-c[/cyan] to run an inline script.",
-            )
-            raise typer.Exit(code=1)
-        script_name = positional[0]
-        if not Path(script_name).exists():
-            _err_console.print(
-                f'[bold red]Error:[/bold red] SQL script file [cyan]"{script_name}"[/cyan] does not exist.',
-            )
-            raise typer.Exit(code=1)
-
-    # ------------------------------------------------------------------
-    # Validate positional args and db_type choice
-    # ------------------------------------------------------------------
-
-    if db_type and db_type not in ("a", "d", "p", "s", "l", "m", "k", "o", "f"):
-        _err_console.print(
-            f"[bold red]Error:[/bold red] Invalid database type [cyan]{db_type!r}[/cyan]. "
-            "Choose from: a, d, p, s, l, m, k, o, f",
-        )
-        raise typer.Exit(code=2)
-
-    if use_gui and use_gui not in ("0", "1", "2", "3"):
-        _err_console.print(
-            f"[bold red]Error:[/bold red] Invalid GUI level [cyan]{use_gui!r}[/cyan]. Choose from: 0, 1, 2, 3",
-        )
-        raise typer.Exit(code=2)
-
-    if gui_framework and gui_framework.lower() not in ("tkinter", "textual"):
-        _err_console.print(
-            f"[bold red]Error:[/bold red] Invalid GUI framework [cyan]{gui_framework!r}[/cyan]. Choose from: tkinter, textual",
-        )
-        raise typer.Exit(code=2)
-
-    if boolean_int and boolean_int.lower() not in ("0", "1", "t", "f", "y", "n"):
-        _err_console.print(
-            f"[bold red]Error:[/bold red] Invalid --boolean-int value [cyan]{boolean_int!r}[/cyan].",
-        )
-        raise typer.Exit(code=2)
-
-    # ------------------------------------------------------------------
-    # Parse tree: parse script into AST and print tree structure
-    # ------------------------------------------------------------------
-    if parse_tree:
-        from execsql.script.ast import format_tree
-        from execsql.script.parser import parse_script, parse_string
-
-        try:
-            if command is not None:
-                tree = parse_string(command.replace("\\n", "\n").replace("\\t", "\t"), "<inline>")
-            elif script_name is not None:
-                encoding = script_encoding or "utf-8"
-                tree = parse_script(script_name, encoding=encoding)
-            else:
-                _err_console.print(
-                    "[bold red]Error:[/bold red] --parse-tree requires a script file or -c command.",
-                )
-                raise typer.Exit(code=1)
-        except ErrInfo as exc:
-            _err_console.print(f"[bold red]Parse error:[/bold red] {exc.errmsg()}")
-            raise typer.Exit(code=1) from exc
-
-        _console.print(format_tree(tree))
-        raise typer.Exit()
-
-    # ------------------------------------------------------------------
-    # Lint: AST-based static analysis (no DB connection needed)
-    # ------------------------------------------------------------------
-    if lint:
-        from execsql.cli.lint import _print_lint_results, lint as _lint_script
-        from execsql.script.parser import parse_script, parse_string
-
-        label = script_name or "<inline>"
-        try:
-            if command is not None:
-                tree = parse_string(command.replace("\\n", "\n").replace("\\t", "\t"), "<inline>")
-            elif script_name is not None:
-                encoding = script_encoding or "utf-8"
-                tree = parse_script(script_name, encoding=encoding)
-            else:
-                _err_console.print(
-                    "[bold red]Error:[/bold red] --lint requires a script file or -c command.",
-                )
-                raise typer.Exit(code=1)
-        except ErrInfo as exc:
-            # Parse failure IS a lint error — report it
-            issues = [("error", label, 0, f"Parse error: {exc.errmsg()}")]
-            exit_code = _print_lint_results(issues, label)
-            raise typer.Exit(code=exit_code) from exc
-
-        issues = _lint_script(tree, script_path=script_name)
-        exit_code = _print_lint_results(issues, label)
-        raise typer.Exit(code=exit_code)
-
-    # ------------------------------------------------------------------
-    # Delegate to the real main implementation
-    # ------------------------------------------------------------------
-    _run(
-        positional=positional,
-        sub_vars=sub_vars,
-        boolean_int=boolean_int,
-        make_dirs=make_dirs,
-        database_encoding=database_encoding,
-        script_encoding=script_encoding,
-        output_encoding=output_encoding,
-        import_encoding=import_encoding,
-        user_logfile=user_logfile,
-        new_db=new_db,
-        port=port,
-        scanlines=scanlines,
-        db_type=db_type,
-        user=user,
-        use_gui=use_gui,
-        gui_framework=gui_framework,
-        no_passwd=no_passwd,
-        import_buffer=import_buffer,
-        script_name=script_name,
-        command=command,
-        dry_run=dry_run,
-        dsn=dsn,
-        output_dir=output_dir,
-        progress=progress,
-        profile=profile,
-        profile_limit=profile_limit,
-        ping=ping,
-        lint=lint,
-        debug=debug,
-        no_system_cmd=no_system_cmd,
-        no_rm_file=no_rm_file,
-        no_serve=no_serve,
-        config_file=config_file,
-    )
-
-
 # ---------------------------------------------------------------------------
 # Legacy entry point (kept for backwards compat with pyproject.toml script)
 # ---------------------------------------------------------------------------
@@ -625,6 +52,7 @@ def main(
 
 def _legacy_main() -> None:
     """Entry point that wraps the Typer app for use as a console_scripts target."""
+    _end_run_on_sigterm()
     try:
         app()
     except SystemExit as exc:
@@ -634,9 +62,14 @@ def _legacy_main() -> None:
 
         exit_now(1, exc)
     except ConfigError as exc:
-        strace = traceback.extract_tb(sys.exc_info()[2])[-1:]
-        lno = strace[0][1]
-        sys.exit(f"Configuration error on line {lno} of execsql: {exc}")
+        # Upstream printed the line of its own source that raised, which
+        # located nothing for the user. A file error names the file instead.
+        hint = (
+            "\nRun `execsql config --validate` to list every problem in the config files."
+            if isinstance(exc, ConfigFileError)
+            else ""
+        )
+        sys.exit(f"Configuration error: {exc}{hint}")
     except Exception:
         strace = traceback.extract_tb(sys.exc_info()[2])[-1:]
         lno = strace[0][1]