execsql2 2.23.0__py3-none-any.whl → 2.24.0__py3-none-any.whl

execsql/format.py

@@ -17,11 +17,11 @@ import re
 from collections.abc import Iterator
 from pathlib import Path
 
-__all__ = ["collect_paths", "format_file", "main", "parse_keyword"]
+__all__ = ["collect_paths", "format_file", "parse_keyword", "run_formatter"]
 
 
 _SQLGLOT_MISSING_MSG = (
-    "execsql-format requires sqlglot for SQL reformatting.\n"
+    "execsql format requires sqlglot for SQL reformatting.\n"
     "  Install with:  pip install execsql2[formatter]\n"
     "  Or skip SQL reformatting with the --no-sql flag."
 )
@@ -122,7 +122,7 @@ CONTINUATION = frozenset({"ANDIF", "ORIF"})  # emit at depth-1, no depth change
 # Inline IF: "IF (cond) { command }" — self-contained, no ENDIF, no depth
 # change. Pattern must accept the same payloads as
 # src/execsql/script/parser.py:_IF_INLINE_RX. Kept as a separate compiled
-# pattern (not an import) so execsql-format doesn't pull in the AST parser
+# pattern (not an import) so the formatter doesn't pull in the AST parser
 # module graph at startup; tests/test_format.py has a drift check that
 # asserts both regexes recognise the same inputs.
 _IF_INLINE_RE = re.compile(r"^\s*IF\s*\(\s*.+\s*\)\s*\{.+\}\s*$", re.I)
@@ -1204,90 +1204,102 @@ def collect_paths(inputs: list[Path]) -> list[Path]:
 
 
 # ---------------------------------------------------------------------------
-# Entry point (execsql-format)
+# Entry point (execsql format)
 # ---------------------------------------------------------------------------
 
 
-def main() -> None:
-    """CLI entry point for the execsql-format console script."""
+def run_formatter(
+    targets: list[Path],
+    *,
+    check: bool = False,
+    in_place: bool = False,
+    no_sql: bool = False,
+    indent: int = 4,
+    leading_comma: bool = False,
+    encoding: str = "utf-8",
+    diff: bool = False,
+) -> int:
+    """Format or check *targets*; return the process exit code.
+
+    The options are declared once, on the ``execsql format`` command, and
+    arrive here as arguments. Previously they lived on a Typer app built
+    inside ``main()``, which meant the command that wrapped it had no options
+    of its own to show and ``execsql format --help`` listed nothing.
+
+    With *diff*, nothing is written: each file that would change is printed
+    as a unified diff, and the exit code is 1 when any would, as for *check*.
+    """
     import sys
 
-    import typer
     from rich.console import Console
 
     _console = Console()
     _err_console = Console(stderr=True)
 
-    app = typer.Typer(
-        name="execsql-format",
-        help="Format execsql scripts: normalize metacommand indentation and uppercase keywords.",
-        rich_markup_mode="rich",
-        no_args_is_help=True,
-        add_completion=False,
-    )
+    use_sql = not no_sql
+    paths = collect_paths(targets)
+    if not paths:
+        _err_console.print("[bold red]Error:[/bold red] No .sql files found.")
+        return 1
+
+    any_changed = False
+    any_errors = False
+    for path in paths:
+        stdin = str(path) == "-"
+        label = "<stdin>" if stdin else str(path)
+        try:
+            source = sys.stdin.buffer.read().decode(encoding) if stdin else path.read_text(encoding=encoding)
+        except OSError as exc:
+            _err_console.print(f"[bold red]Error:[/bold red] reading {label}: {exc}")
+            any_errors = True
+            # Collect read errors instead of short-circuiting so a single
+            # unreadable file doesn't hide the rest of the report.
+            continue
+        except UnicodeDecodeError as exc:
+            _err_console.print(
+                f"[bold red]Error:[/bold red] decoding {label} as {encoding}: {exc}. "
+                f"Try [bold]--script-encoding cp1252[/bold] or another text encoding.",
+            )
+            any_errors = True
+            continue
 
-    @app.command(context_settings={"allow_extra_args": False})
-    def _cmd(
-        targets: list[Path] = typer.Argument(
-            ...,
-            metavar="FILE_OR_DIR",
-            help="Files or directories to format. Directories are searched recursively for *.sql files.",
-        ),
-        check: bool = typer.Option(False, "--check", help="Exit 1 if any file needs changes (don't write)."),
-        in_place: bool = typer.Option(False, "-i", "--in-place", help="Modify files in place."),
-        no_sql: bool = typer.Option(False, "--no-sql", help="Skip SQL formatting via sqlglot."),
-        indent: int = typer.Option(4, "--indent", metavar="N", help="Spaces per indent level."),
-        leading_comma: bool = typer.Option(
-            False,
-            "--leading-comma",
-            help="Place commas at the start of lines instead of the end.",
-        ),
-        encoding: str = typer.Option(
-            "utf-8",
-            "--encoding",
-            metavar="NAME",
-            help="Text encoding used to read and write SQL files (default utf-8).",
-        ),
-    ) -> None:
-        use_sql = not no_sql
-        paths = collect_paths(targets)
-        if not paths:
-            _err_console.print("[bold red]Error:[/bold red] No .sql files found.")
-            raise typer.Exit(code=1)
-
-        any_changed = False
-        any_errors = False
-        for path in paths:
-            try:
-                source = path.read_text(encoding=encoding)
-            except OSError as exc:
-                _err_console.print(f"[bold red]Error:[/bold red] reading {path}: {exc}")
-                any_errors = True
-                # Collect read errors instead of short-circuiting so a single
-                # unreadable file doesn't hide the rest of the report.
-                continue
-            except UnicodeDecodeError as exc:
-                _err_console.print(
-                    f"[bold red]Error:[/bold red] decoding {path} as {encoding}: {exc}. "
-                    f"Try [bold]--encoding cp1252[/bold] or another text encoding.",
-                )
-                any_errors = True
-                continue
+        formatted = format_file(source, indent=indent, use_sql=use_sql, leading_comma=leading_comma)
+
+        if diff:
+            if formatted != source:
+                any_changed = True
+                _write_diff(source, formatted, label)
+        elif check:
+            if formatted != source:
+                _console.print(f"would reformat {label}")
+                any_changed = True
+        elif in_place:
+            if formatted != source:
+                path.write_text(formatted, encoding=encoding)
+                _console.print(f"reformatted {path}")
+        else:
+            sys.stdout.write(formatted)
 
-            formatted = format_file(source, indent=indent, use_sql=use_sql, leading_comma=leading_comma)
+    return 1 if (any_errors or ((check or diff) and any_changed)) else 0
 
-            if check:
-                if formatted != source:
-                    _console.print(f"would reformat {path}")
-                    any_changed = True
-            elif in_place:
-                if formatted != source:
-                    path.write_text(formatted, encoding=encoding)
-                    _console.print(f"reformatted {path}")
-            else:
-                sys.stdout.write(formatted)
 
-        if any_errors or (check and any_changed):
-            raise typer.Exit(code=1)
+def _write_diff(before: str, after: str, label: str) -> None:
+    """Print a unified diff of one file, colored when stdout is a terminal."""
+    import difflib
+    import sys
+
+    from execsql.utils.color import color_disabled_by_env
 
-    app()
+    lines = difflib.unified_diff(
+        before.splitlines(keepends=True),
+        after.splitlines(keepends=True),
+        fromfile=label,
+        tofile=label,
+    )
+    color = sys.stdout.isatty() and not color_disabled_by_env()
+    styles = {"+": "\033[32m", "-": "\033[31m", "@": "\033[36m"}
+    for line in lines:
+        if not line.endswith("\n"):
+            line += "\n\\n"
+        style = styles.get(line[0]) if color and not line.startswith(("+++", "---")) else None
+        sys.stdout.write(f"{style}{line.rstrip(chr(10))}\033[0m\n" if style else line)

execsql/interactive.py

@@ -0,0 +1,232 @@
+"""The engine behind the debug REPL a ``BREAKPOINT`` (or ``run --debug``) opens.
+
+Input runs as the next lines of the paused script
+(:func:`~execsql.script.executor.execute_input`): where the script paused, in
+its variable scope and transaction.
+
+What runs, and how it runs, follows script rules:
+
+- SQL ends with ``;`` and may span lines. Variables are substituted, and each
+  statement is committed unless ``AUTOCOMMIT OFF`` or a batch is in effect.
+  Results print as tables.
+- A metacommand is typed as in a script (``-- !x! EXPORT …``) or without the
+  comment marker (``!x! EXPORT …``).
+- A block (``IF`` … ``ENDIF``, ``LOOP``, ``BEGIN BATCH``, ``BEGIN SCRIPT``)
+  keeps the prompt reading until it is closed, then runs as a whole.
+
+The one difference from a script: an error that would halt the run ends only
+the input that caused it. The prompt reports it and reads the next input.
+``HALT`` still ends the run.
+
+A line starting with ``.`` is a command to the prompt itself. :class:`Prompt`
+holds a prompt's name and its own commands; ``.vars``, ``.set``, ``.scripts``
+and ``.cancel`` are handled here for any prompt.
+
+Display helpers (colors, tables, variable listings) live in
+:mod:`execsql.debug.repl` and are reached through the module, so tests that
+patch them there see every caller.
+"""
+
+from __future__ import annotations
+
+
+import execsql.state as _state
+from execsql.exceptions import ErrInfo
+
+__all__ = ["Prompt", "read_eval_loop", "run_input", "uncommitted"]
+
+
+class Prompt:
+    """What differs between the prompts; subclassed by each.
+
+    Attributes:
+        name: The prompt text before ``>``, e.g. ``execsql``.
+        source: The name input is given in messages and ``$CURRENT_SCRIPT``.
+    """
+
+    name = "execsql"
+    source = "<prompt>"
+
+    def dot_command(self, command: str, argument: str, line: str) -> bool:
+        """Handle a ``.`` command; return ``False`` to leave the prompt.
+
+        *command* is the lowercased word after the dot, *argument* the rest
+        of the line as typed.
+        """
+        if not common_dot_command(command, argument, line):
+            unknown_dot_command(line)
+        return True
+
+
+def uncommitted() -> bool:
+    """Whether SQL run now waits for a commit: ``AUTOCOMMIT OFF`` or an open batch."""
+    status = _state.status
+    if status is not None and status.batch.in_batch():
+        return True
+    dbs = _state.dbs
+    if dbs is None:
+        return False
+    try:
+        db = dbs.current()
+    except Exception:
+        return False
+    return db is not None and not db.autocommit
+
+
+def _prompts(prompt: Prompt) -> tuple[str, str]:
+    """The prompt and continuation-line strings; ``*`` marks uncommitted mode."""
+    first = f"{prompt.name}{'*' if uncommitted() else ''}> "
+    return first, "...> ".rjust(len(first))
+
+
+def _is_metacommand(line: str) -> bool:
+    stripped = line.strip()
+    return stripped.startswith("--") and stripped[2:].lstrip().lower().startswith("!x!")
+
+
+def _complete(line: str) -> bool:
+    """Whether input ending with *line* may be whole: it ends with ``;`` or is a metacommand."""
+    return line.rstrip().endswith(";") or _is_metacommand(line)
+
+
+def _one_line(text: str) -> str:
+    return " ".join(text.split())
+
+
+def describe_error(exc: BaseException) -> str:
+    """One line for a prompt: the driver's or handler's own message, and where it came from."""
+    from execsql.debug import repl as _ui
+
+    label = "Error:"
+    if isinstance(exc, ErrInfo):
+        cause = exc.__cause__
+        if isinstance(cause, Exception) and not isinstance(cause, ErrInfo) and str(cause):
+            message = str(cause)
+        else:
+            message = exc.other or exc.exception or exc.type
+            if exc.command and exc.command not in message:
+                message = f"{message}: {exc.command}"
+        if exc.cmdtype == "sql":
+            label = "SQL error:"
+        source = exc.script_file
+        if source and not (source.startswith("<") and source.endswith(">")) and exc.script_line_no:
+            message = f"{message} (line {exc.script_line_no} of {source})"
+    else:
+        message = str(exc) or type(exc).__name__
+    return f"{_ui._c(_ui._RED, label)} {_one_line(message)}"
+
+
+def _show_result(result: tuple[list[str], list] | None) -> None:
+    """Print a statement's rows as a table, or how many rows it changed."""
+    from execsql.debug import repl as _ui
+
+    if result is not None:
+        _ui._print_table(*result)
+        return
+    count = -1
+    if _state.subvars is not None:
+        try:
+            count = int(_state.subvars.varvalue("$LAST_ROWCOUNT") or -1)
+        except (TypeError, ValueError):
+            count = -1
+    word = "row" if count == 1 else "rows"
+    _ui._write(f"  {_ui._c(_ui._DIM, f'({count} {word} affected)' if count >= 0 else '(statement executed)')}\n")
+
+
+def run_input(text: str, source: str) -> None:
+    """Parse *text* and run it as the next lines of the run; errors are raised."""
+    from execsql.script.executor import execute_input
+    from execsql.script.parser import parse_string
+
+    execute_input(parse_string(text + "\n", source), _show_result)
+
+
+def common_dot_command(command: str, argument: str, line: str) -> bool:
+    """Handle a command both prompts share; return ``False`` if *command* is not one."""
+    from execsql.debug import repl as _ui
+
+    if command in ("vars", "v"):
+        if argument.lower() == "all":
+            _ui._print_all_vars(include_env=True)
+        elif argument:
+            _ui._print_var(argument)
+        else:
+            _ui._print_all_vars()
+    elif command in ("set", "s"):
+        parts = argument.split(None, 1)
+        if not parts:
+            _ui._write(f"  Usage: .{command} VAR VALUE\n")
+        else:
+            _ui._set_var(parts[0], parts[1] if len(parts) > 1 else "")
+    elif command == "scripts":
+        if argument:
+            _ui._print_script_detail(argument)
+        else:
+            _ui._print_scripts()
+    else:
+        return False
+    return True
+
+
+def unknown_dot_command(line: str) -> None:
+    from execsql.debug import repl as _ui
+
+    _ui._write(f"  {_ui._c(_ui._RED, 'Unknown command:')} {line!r}. Type '.help' for available commands.\n")
+
+
+def read_eval_loop(prompt: Prompt) -> None:
+    """Read and run inputs until the prompt's own command ends it, or input ends.
+
+    Lines are read with ``input()`` (line editing, a prompt). Ctrl-D or
+    Ctrl-C discards a half-typed input, and on an empty line leaves the
+    prompt.
+    """
+    from execsql.debug import repl as _ui
+
+    buffer: list[str] = []
+    while True:
+        first, more = _prompts(prompt)
+        try:
+            line = input(more if buffer else first)
+        except (EOFError, KeyboardInterrupt):
+            if buffer:
+                buffer.clear()
+                _ui._write("\n  (input discarded)\n")
+                continue
+            _ui._write("\n")
+            return
+        stripped = line.strip()
+        if not stripped and not buffer:
+            continue
+        if stripped.startswith("."):
+            command, _, argument = stripped[1:].partition(" ")
+            command = command.lower()
+            if command == "cancel":
+                if buffer:
+                    buffer.clear()
+                    _ui._write("  (input discarded)\n")
+                continue
+            try:
+                if not prompt.dot_command(command, argument.strip(), stripped):
+                    return
+            except (SystemExit, KeyboardInterrupt):
+                raise
+            except Exception as exc:
+                _ui._write(f"  {describe_error(exc)}\n")
+            continue
+        if stripped.lower().startswith("!x!"):
+            line = "-- " + stripped
+        buffer.append(line)
+        if not _complete(line):
+            continue
+        try:
+            run_input("\n".join(buffer), prompt.source)
+        except ErrInfo as exc:
+            if "at end of file" in str(exc):
+                continue  # a block is still open; keep reading
+            _ui._write(f"  {describe_error(exc)}\n")
+        except KeyboardInterrupt:
+            _ui._write("\n  (interrupted)\n")
+        except Exception as exc:
+            _ui._write(f"  {describe_error(exc)}\n")
+        buffer.clear()

execsql/manifest.py

@@ -0,0 +1,189 @@
+"""The run manifest: a JSON record of one ``execsql run``, for ``--manifest FILE``.
+
+The manifest says what a run did — the script, the database, how many
+statements ran, the files it read, wrote and deleted, the connections it
+opened, and how it ended — in a form an orchestrator or an audit can read
+without parsing the log. It is written when the run ends, whether it
+succeeded, failed or was cancelled.
+
+Files are recorded as the executor runs each metacommand, after variable
+substitution, so paths are the ones actually used. What a metacommand touches
+is decided by :mod:`execsql.metacommands.effects`. Variable values and passwords are never written:
+the run log hides ``-a`` and ``--var`` values because they can be secrets, and
+the manifest lists only their names.
+
+One recorder is active per run; :func:`current` returns it, or ``None`` when
+no manifest was asked for, so the executor's hooks cost one check. Writing the
+manifest ends the recording, so a later run in the same process starts clean.
+"""
+
+from __future__ import annotations
+
+import atexit
+import datetime
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from execsql import __version__
+
+__all__ = ["RunManifest", "check_writable", "current", "start"]
+
+_current: RunManifest | None = None
+
+
+def current() -> RunManifest | None:
+    """The active manifest recorder, or ``None`` when ``--manifest`` was not given."""
+    return _current
+
+
+def check_writable(path: str) -> str | None:
+    """Why a manifest cannot be written to *path*, or ``None`` if it can.
+
+    Checked before a run starts, so a bad ``--manifest`` path fails before any
+    SQL runs rather than after.
+    """
+    target = Path(path)
+    if target.is_dir():
+        return f"{path} is a directory"
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        fd, probe = tempfile.mkstemp(dir=target.parent, prefix=f".{target.name}.", suffix=".tmp")
+        os.close(fd)
+        os.unlink(probe)
+    except OSError as exc:
+        return exc.strerror or str(exc)
+    return None
+
+
+def start(path: str, script: str | None, variables: list[str]) -> RunManifest:
+    """Begin recording a run; the manifest is written to *path* when it ends.
+
+    If nothing else writes it (``exit_now`` on an error, the end of a run), an
+    ``atexit`` fallback does.
+    """
+    global _current
+    _current = RunManifest(path, script, variables)
+    atexit.register(_current.finish, None)
+    return _current
+
+
+def _now() -> datetime.datetime:
+    return datetime.datetime.now(tz=datetime.timezone.utc)
+
+
+class RunManifest:
+    """Collects what one run does and writes it as JSON when the run ends."""
+
+    def __init__(self, path: str, script: str | None, variables: list[str]) -> None:
+        self.path = Path(path)
+        self.script = script or "<inline>"
+        self.variables = variables
+        self.started = _now()
+        self.config_files: list[str] = []
+        self.database: dict[str, Any] | None = None
+        self.sql_statements = 0
+        self.metacommands = 0
+        self.reads: list[dict[str, Any]] = []
+        self.writes: list[dict[str, Any]] = []
+        self.deletes: list[dict[str, Any]] = []
+        self.connections: list[dict[str, Any]] = []
+        self.errors: list[dict[str, Any]] = []
+        self.written = False
+
+    # -- recording -------------------------------------------------------------
+
+    def set_database(self, db: Any) -> None:
+        """Record the initial connection: DBMS, server, database or file, user — no password."""
+        self.database = {
+            "dbms": db.type.dbms_id if getattr(db, "type", None) else None,
+            "server": getattr(db, "server_name", None),
+            "database": getattr(db, "db_name", None),
+            "user": getattr(db, "user", None),
+        }
+
+    def record_sql(self) -> None:
+        self.sql_statements += 1
+
+    def record_metacommand(self, command: str, source: str, line: int, metacommandlist: Any) -> None:
+        """Count a metacommand that ran, and record the files and connections it touched.
+
+        *command* is the text after substitution, so paths are the ones used.
+        """
+        from execsql.metacommands.effects import effects
+
+        self.metacommands += 1
+        hit = metacommandlist.get_match(command)
+        if hit is None:
+            return
+        mc, m = hit
+        by = mc.description or command.split(None, 1)[0].upper()
+        for effect in effects(mc.exec_fn.__name__, m.groupdict()):
+            entry = {"source": source, "line": line, "by": by}
+            if effect.role in ("connect", "use"):
+                self.connections.append(
+                    {**entry, "by": effect.role.upper(), "target": effect.target, "detail": effect.detail},
+                )
+            else:
+                {"read": self.reads, "write": self.writes, "delete": self.deletes}[effect.role].append(
+                    {**entry, "path": effect.target},
+                )
+
+    def record_include(self, path: str, source: str, line: int) -> None:
+        self.reads.append({"source": source, "line": line, "by": "INCLUDE", "path": path})
+
+    # -- finishing -------------------------------------------------------------
+
+    def finish(self, exit_status: int | None, error: Any = None) -> None:
+        """Write the manifest once. Later calls (the atexit fallback) do nothing."""
+        if self.written:
+            return
+        if error is not None:
+            # str(ErrInfo) is its concise message; errmsg() is the multi-line
+            # console block with a timestamp, which a reader of JSON does not want.
+            self.errors.append(
+                {
+                    "message": " ".join(str(error).split()),
+                    "type": getattr(error, "type", None),
+                    "source": getattr(error, "script_file", None),
+                    "line": getattr(error, "script_line_no", None),
+                    "command": getattr(error, "cmd", None) or getattr(error, "command", None),
+                },
+            )
+        finished = _now()
+        data = {
+            "execsql_version": __version__,
+            "script": self.script,
+            "started": self.started.isoformat(timespec="seconds"),
+            "finished": finished.isoformat(timespec="seconds"),
+            "duration_s": round((finished - self.started).total_seconds(), 3),
+            "exit_status": exit_status,
+            "config_files": self.config_files,
+            "database": self.database,
+            "variables": self.variables,
+            "statements": {"sql": self.sql_statements, "metacommands": self.metacommands},
+            "files_read": self.reads,
+            "files_written": self.writes,
+            "files_deleted": self.deletes,
+            "connections": self.connections,
+            "errors": self.errors,
+        }
+        self.written = True
+        global _current
+        if _current is self:
+            _current = None
+        atexit.unregister(self.finish)
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            # Write beside the target and rename, so a reader never sees half a file.
+            fd, tmp = tempfile.mkstemp(dir=self.path.parent, prefix=f".{self.path.name}.", suffix=".tmp")
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2, default=str)
+                f.write("\n")
+            os.replace(tmp, self.path)
+        except OSError as exc:
+            # The run itself is over; report the lost manifest without a traceback.
+            sys.stderr.write(f"execsql: could not write --manifest {self.path}: {exc.strerror or exc}\n")

execsql/metacommands/conditions.py

@@ -22,7 +22,7 @@ registration time for quoted, unquoted, and bracketed arguments):
   ``xf_row_count_eq``, ``xf_row_count_lt``.
 - Runtime state: ``xf_sqlerror``, ``xf_dialogcanceled``, ``xf_dbms``.
 
-The full list is also surfaced by ``execsql --dump-keywords``.
+The full list is also surfaced by ``execsql list keywords``.
 """
 
 import os

execsql/metacommands/control.py

@@ -77,9 +77,8 @@ def x_assert(**kwargs: Any) -> None:
 def _ast_only_stub(name: str):
     """Return an ErrInfo for a metacommand the AST executor handles structurally.
 
-    These handlers stay registered in the dispatch table so ``--dump-keywords``,
-    the VS Code grammar generator, and ``--list-keywords`` still see the
-    keyword.  The AST parser converts the source form (``IF`` / ``ENDIF`` /
+    These handlers stay registered in the dispatch table so ``execsql list
+    keywords`` and the VS Code grammar generator still see the keyword.  The AST parser converts the source form (``IF`` / ``ENDIF`` /
     ``LOOP`` / ``BEGIN BATCH`` / ``BREAK`` / ``ELSE`` / ``ELSEIF`` / ``ANDIF``
     / ``ORIF``) into structural AST nodes that the executor walks directly —
     none of these dispatch handlers fire for parsed scripts.  Reaching one