execsql2 2.1.2__py3-none-any.whl → 2.4.0__py3-none-any.whl

execsql/{cli.py → cli/run.py}

@@ -1,7 +1,8 @@
-"""Command-line interface for execsql.
+"""Core execution logic for the execsql CLI.
 
-Parses arguments, initialises global state, establishes a database
-connection, loads the SQL script, and drives the main execution loop.
+Initialises global state, connects to the database, loads the SQL script,
+and drives the main execution loop.  Separated from argument parsing
+(``cli/__init__.py``) for testability and maintainability.
 """
 
 from __future__ import annotations
@@ -13,563 +14,16 @@ import os
 import sys
 import traceback
 from pathlib import Path
-from encodings.aliases import aliases as codec_dict
-
-import typer
-from rich.console import Console
-from rich.table import Table
 
 from execsql import __version__
+from execsql.cli.dsn import _parse_connection_string
+from execsql.cli.help import _console, _err_console
 from execsql.config import ConfigData, StatObj
 from execsql.exceptions import ConfigError, ErrInfo
 from execsql.script import SubVarSet, current_script_line, read_sqlfile, read_sqlstring, runscripts
 from execsql.utils.fileio import FileWriter, Logger, filewriter_end
 from execsql.utils.gui import gui_connect, gui_console_isrunning, gui_console_off, gui_console_on, gui_console_wait_user
 
-_console = Console()
-_err_console = Console(stderr=True)
-
-# ---------------------------------------------------------------------------
-# Metacommand help text
-# ---------------------------------------------------------------------------
-
-_METACOMMANDS = [
-    ("ASK", '"<question>" SUB <match_string>'),
-    ("AUTOCOMMIT", "ON|OFF"),
-    ("BEGIN BATCH / END BATCH / ROLLBACK BATCH", ""),
-    ("BEGIN SCRIPT / END SCRIPT", ""),
-    ("BEGIN SQL / END SQL", ""),
-    ("CANCEL_HALT", "ON|OFF"),
-    ("CD", "<directory>"),
-    ("CONNECT", "<alias> [AS <alias_name>]"),
-    ("COPY", "<source_file> TO <dest_file>"),
-    ("DEBUG", "ON|OFF"),
-    ("DEFINE SUB", "<variable> [AS] <value>"),
-    ("EXPORT QUERY", "<queryname> [AS <alias>] ..."),
-    ("EXPORT", "<queryname> TO <format> <filename> ..."),
-    ("HALT [ON]", "ERROR|CANCEL"),
-    ("IF <condition>", "/ ELSE / ENDIF"),
-    ("IMPORT FILE", "<filename> [OPTIONS ...]"),
-    ("IMPORT TABLE", "<tablename> FROM FILE <filename> [OPTIONS ...]"),
-    ("LOOP <n> TIMES", "/ END LOOP"),
-    ("LOOP WHILE <condition>", "/ END LOOP"),
-    ("LOOP UNTIL <condition>", "/ END LOOP"),
-    ("ON CANCEL_HALT", "..."),
-    ("ON ERROR_HALT", "..."),
-    ("PAUSE", "[<text>]"),
-    ("PROMPT ACTION", "..."),
-    ("PROMPT ENTRY_FORM", "..."),
-    ("PROMPT MENU", "..."),
-    ("PROMPT OPENFILE", "..."),
-    ("PROMPT SAVEFILE", "..."),
-    ("PROMPT DIRECTORY", "..."),
-    ("PROMPT MAP", "..."),
-    ("RECONNECT", ""),
-    ("ROLLBACK", ""),
-    ("SERVE", "<queryname> ..."),
-    ("SET AUTOCOMMIT", "ON|OFF"),
-    ("SHELL", "(<command>)"),
-    ("SHOW WARNINGS", "ON|OFF"),
-    ("SUB", "<variable> [AS] <value>"),
-    ("SUB_TEMPFILE", "<variable>"),
-    ("SYSTEM_CMD", "(<operating system command line>)"),
-    ("TIMER", "ON|OFF"),
-    ("USE", "<alias_name>"),
-    ("WAIT_UNTIL", "<Boolean_expression> <HALT|CONTINUE> AFTER <n> SECONDS"),
-    ("WRITE", '"<text>" [[TEE] TO <output>]'),
-    ("WRITE CREATE_TABLE FROM", "<filename> [TO <output>]"),
-    ("WRITE SCRIPT", "<script_name> [[APPEND] TO <output_file>]"),
-    ("ZIP", "<filename> [APPEND] TO ZIPFILE <zipfilename>"),
-]
-
-_METACOMMANDS_PLAIN = """\
-Metacommands are embedded in SQL comment lines following the !x! token.
-See the documentation for more complete descriptions of the metacommands.
-   ASK "<question>" SUB <match_string>
-   AUTOCOMMIT ON|OFF
-   BEGIN BATCH / END BATCH / ROLLBACK BATCH
-   BEGIN SCRIPT / END SCRIPT
-   BEGIN SQL / END SQL
-   CANCEL_HALT ON|OFF
-   CD <directory>
-   CONNECT <alias> [AS <alias_name>]
-   COPY <source_file> TO <dest_file>
-   DEBUG ON|OFF
-   DEFINE SUB <variable> [AS] <value>
-   EXPORT QUERY <queryname> [AS <alias>] ...
-   EXPORT <queryname> TO <format> <filename> ...
-   HALT [ON] ERROR|CANCEL
-   IF <condition> / ELSE / ENDIF
-   IMPORT FILE <filename> [OPTIONS ...]
-   IMPORT TABLE <tablename> FROM FILE <filename> [OPTIONS ...]
-   LOOP <n> TIMES / END LOOP
-   LOOP WHILE <condition> / END LOOP
-   LOOP UNTIL <condition> / END LOOP
-   ON CANCEL_HALT ...
-   ON ERROR_HALT ...
-   PAUSE [<text>]
-   PROMPT ACTION ...
-   PROMPT ENTRY_FORM ...
-   PROMPT MENU ...
-   PROMPT OPENFILE ...
-   PROMPT SAVEFILE ...
-   PROMPT DIRECTORY ...
-   PROMPT MAP ...
-   RECONNECT
-   ROLLBACK
-   SERVE <queryname> ...
-   SET AUTOCOMMIT ON|OFF
-   SHELL (<command>)
-   SHOW WARNINGS ON|OFF
-   SUB <variable> [AS] <value>
-   SUB_TEMPFILE <variable>
-   SYSTEM_CMD (<operating system command line>)
-   TIMER ON|OFF
-   USE <alias_name>
-   WAIT_UNTIL <Boolean_expression> <HALT|CONTINUE> AFTER <n> SECONDS
-   WRITE "<text>" [[TEE] TO <output>]
-   WRITE CREATE_TABLE FROM <filename> [TO <output>]
-   WRITE SCRIPT <script_name> [[APPEND] TO <output_file>]
-   ZIP <filename> [APPEND] TO ZIPFILE <zipfilename>"""
-
-
-def _print_metacommands() -> None:
-    """Print the metacommands table using Rich."""
-    table = Table(
-        title="execsql Metacommands",
-        caption="Embed in SQL comment lines following the [bold]!x![/bold] token.",
-        show_header=True,
-        header_style="bold cyan",
-        border_style="dim",
-        expand=False,
-    )
-    table.add_column("Metacommand", style="bold green", no_wrap=True)
-    table.add_column("Syntax", style="white")
-    for name, syntax in _METACOMMANDS:
-        table.add_row(name, syntax)
-    _console.print(table)
-
-
-def _print_encodings() -> None:
-    """Print available encodings using Rich."""
-    enc = sorted(codec_dict.keys())
-    table = Table(
-        title="Available Encodings",
-        show_header=False,
-        border_style="dim",
-        expand=True,
-    )
-    table.add_column("Encoding", style="cyan")
-    # 4 columns
-    cols = 4
-    for i in range(0, len(enc), cols):
-        row = enc[i : i + cols]
-        while len(row) < cols:
-            row.append("")
-        table.add_row(*row)
-    _console.print(table)
-
-
-# ---------------------------------------------------------------------------
-# 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)."
-        ),
-    ),
-    # Named options — grouped to mirror the original argparse interface
-    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].",
-    ),
-    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]",
-    ),
-    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.",
-    ),
-    user_logfile: bool = typer.Option(
-        False,
-        "-l",
-        "--user-logfile",
-        help="Write a log file to [cyan]~/execsql.log[/cyan].",
-    ),
-    metacommands: bool = typer.Option(
-        False,
-        "-m",
-        "--metacommands",
-        help="List metacommands and exit.",
-    ),
-    new_db: bool = typer.Option(
-        False,
-        "-n",
-        "--new-db",
-        help="Create a new SQLite or Postgres database if it does not exist.",
-    ),
-    online_help: bool = typer.Option(
-        False,
-        "-o",
-        "--online-help",
-        help="Open the online documentation in the default browser.",
-    ),
-    port: int | None = typer.Option(
-        None,
-        "-p",
-        "--port",
-        help="Database server port.",
-    ),
-    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]",
-    ),
-    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."
-        ),
-    ),
-    user: str | None = typer.Option(
-        None,
-        "-u",
-        "--user",
-        help="Database user name.",
-    ),
-    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]",
-    ),
-    no_passwd: bool = typer.Option(
-        False,
-        "-w",
-        "--no-passwd",
-        help="Skip password prompt when user is specified.",
-    ),
-    encodings: bool = typer.Option(
-        False,
-        "-y",
-        "--encodings",
-        help="List available encoding names and exit.",
-    ),
-    import_buffer: int | None = typer.Option(
-        None,
-        "-z",
-        "--import-buffer",
-        metavar="KB",
-        help="Import buffer size in KB. [dim]Default: 32[/dim]",
-    ),
-    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."),
-    ),
-    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."
-        ),
-    ),
-    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."
-        ),
-    ),
-    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 online_help:
-        import webbrowser
-
-        webbrowser.open("https://execsql2.readthedocs.io/en/latest/", new=2, autoraise=True)
-        raise typer.Exit()
-
-    positional = args or []
-    if command is not None:
-        script_name = None  # inline mode — no script file
-    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)
-
-    # ------------------------------------------------------------------
-    # 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,
-    )
-
-
-# ---------------------------------------------------------------------------
-# Connection-string parser
-# ---------------------------------------------------------------------------
-
-#: Mapping from URL scheme → execsql db_type code
-_SCHEME_TO_DBTYPE: dict[str, str] = {
-    "postgresql": "p",
-    "postgres": "p",
-    "mysql": "m",
-    "mariadb": "m",
-    "mssql": "s",
-    "sqlserver": "s",
-    "oracle": "o",
-    "oracle+cx_oracle": "o",
-    "firebird": "f",
-    "sqlite": "l",
-    "duckdb": "k",
-}
-
-
-def _parse_connection_string(dsn: str) -> dict:
-    """Parse a database URL into a dict of connection parameters.
-
-    Supports the common form::
-
-        scheme://[user[:password]@][host[:port]]/database
-
-    For file-based databases (SQLite, DuckDB) the path after ``//`` is
-    treated as the database file path::
-
-        sqlite:///path/to/file.db   → db_file = /path/to/file.db
-        duckdb:///path/to/file.db   → db_file = /path/to/file.db
-
-    Returns a dict with keys: ``db_type``, ``server``, ``db``, ``db_file``,
-    ``user``, ``password``, ``port``.  Absent components are ``None``.
-
-    Raises :class:`~execsql.exceptions.ConfigError` for an unrecognised
-    URL scheme or a completely un-parseable string.
-    """
-    from urllib.parse import urlparse
-
-    parsed = urlparse(dsn)
-    scheme = parsed.scheme.lower()
-    if not scheme:
-        raise ConfigError(f"Cannot parse connection string (no scheme): {dsn!r}")
-    if scheme not in _SCHEME_TO_DBTYPE:
-        raise ConfigError(
-            f"Unrecognised connection-string scheme {scheme!r}. "
-            f"Supported schemes: {', '.join(sorted(_SCHEME_TO_DBTYPE))}",
-        )
-
-    db_type = _SCHEME_TO_DBTYPE[scheme]
-    port: int | None = parsed.port
-    server: str | None = parsed.hostname or None
-    user: str | None = parsed.username or None
-    password: str | None = parsed.password or None
-
-    # Database / file path
-    # urlparse puts the path in parsed.path.  For three-slash URIs like
-    # sqlite:///foo.db the path starts with "/"; strip exactly one leading
-    # slash for relative paths (sqlite:///foo.db → foo.db) and leave
-    # absolute paths intact (sqlite:////abs/path → /abs/path).
-    raw_path = parsed.path
-    if db_type in ("l", "k", "a"):
-        # File-based: no server component
-        if raw_path.startswith("/") and not raw_path.startswith("//"):
-            db_file: str | None = raw_path[1:] or None
-        else:
-            db_file = raw_path or None
-        db: str | None = None
-    else:
-        db_file = None
-        # Remove leading "/"
-        db = raw_path.lstrip("/") or None
-
-    return {
-        "db_type": db_type,
-        "server": server,
-        "db": db,
-        "db_file": db_file,
-        "user": user,
-        "password": password,
-        "port": port,
-    }
-
 
 # ---------------------------------------------------------------------------
 # Dry-run helper
@@ -619,6 +73,7 @@ def _run(
     dry_run: bool = False,
     dsn: str | None = None,
     output_dir: str | None = None,
+    progress: bool = False,
 ) -> None:
     """Initialise state, connect to the database, load the script, and run it.
 
@@ -751,6 +206,8 @@ def _run(
         conf.new_db = True
     if output_dir:
         conf.export_output_dir = str(Path(output_dir).resolve())
+    if progress:
+        conf.show_progress = True
 
     # Positional arguments after the script name (or all positionals in inline mode)
     # off=1: script file occupies positional[0]; connection args start at [1]
@@ -1041,14 +498,14 @@ def _connect_initial_db(conf: ConfigData):
     """Create and return the initial database object based on conf.db_type."""
     from execsql.db.factory import (
         db_Access,
+        db_Dsn,
+        db_DuckDB,
+        db_Firebird,
+        db_MySQL,
+        db_Oracle,
         db_Postgres,
         db_SQLite,
         db_SqlServer,
-        db_MySQL,
-        db_DuckDB,
-        db_Oracle,
-        db_Firebird,
-        db_Dsn,
     )
 
     if conf.db_type == "a":
@@ -1132,35 +589,3 @@ def _connect_initial_db(conf: ConfigData):
         from execsql.utils.errors import fatal_error
 
         fatal_error(f"Unknown database type: '{conf.db_type}'")
-
-
-# ---------------------------------------------------------------------------
-# Legacy entry point (kept for backwards compat with pyproject.toml script)
-# ---------------------------------------------------------------------------
-
-
-def _legacy_main() -> None:
-    """Entry point that wraps the Typer app for use as a console_scripts target."""
-    try:
-        app()
-    except SystemExit as exc:
-        raise exc
-    except ErrInfo as exc:
-        from execsql.utils.errors import exit_now
-
-        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}")
-    except Exception:
-        strace = traceback.extract_tb(sys.exc_info()[2])[-1:]
-        lno = strace[0][1]
-        msg = f"{Path(sys.argv[0]).name}: Uncaught exception {sys.exc_info()[0]} ({sys.exc_info()[1]}) on line {lno}"
-        from execsql.utils.errors import exit_now
-
-        exit_now(1, ErrInfo("exception", exception_msg=msg))
-
-
-if __name__ == "__main__":
-    _legacy_main()