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

execsql/cli/application.py

@@ -0,0 +1,309 @@
+"""The execsql Typer app: command group, help rendering, global options.
+
+Every command registers itself on :data:`app` from a module in
+:mod:`execsql.cli.commands`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+
+import typer
+from typer.core import TyperCommand, TyperGroup
+
+from execsql import __version__
+from execsql.cli.help import _console, _err_console
+from execsql.utils.color import color_disabled_by_env
+
+__all__ = ["ExecsqlCommand", "ExecsqlGroup", "ExecsqlSubGroup", "app"]
+
+
+#: Options the app answers about itself rather than about a run, shown under
+#: their own heading. ``--config`` is deliberately not here: only ``run``
+#: reads an execsql config file, so listing it as global would be a lie.
+_GLOBAL_OPTIONS = ("--online-help", "--version")
+
+#: What to type instead of a flag that, used without a command, implies ``run``.
+_REPLACEMENTS = {
+    "-m": "execsql list metacommands",
+    "--metacommands": "execsql list metacommands",
+    "-y": "execsql list encodings",
+    "--encodings": "execsql list encodings",
+    "--list-plugins": "execsql list plugins",
+    "--dump-keywords": "execsql list keywords --output-format json",
+    "--init-config": "execsql config --init",
+    "--ping": "execsql run --ping",
+}
+
+
+def deprecated_bare_form(head: str) -> str:
+    """The warning printed when ``run`` is implied rather than typed; *head* is the first argument."""
+    if head in _REPLACEMENTS:
+        return (
+            f"Deprecated: `execsql {head}` is now `{_REPLACEMENTS[head]}`; the old form stops working in execsql2 3.0."
+        )
+    return (
+        "Deprecated: running a script without the run command. Use `execsql run SCRIPT ...`; "
+        "`execsql SCRIPT ...` stops working in execsql2 3.0."
+    )
+
+
+def _unescape(record: tuple[str, str]) -> tuple[str, str]:
+    """Undo Typer's Rich bracket escaping for plain help output.
+
+    Typer escapes ``[`` as ``\\[`` so Rich does not read ``[required]`` as
+    markup. With Rich rendering off those backslashes are literal text, so
+    every default and required marker would print as ``\\[default: 4]``.
+    """
+    name, help_text = record
+    return name.replace("\\[", "["), help_text.replace("\\[", "[")
+
+
+# Help fills the terminal, as ruff's and uv's do. Click caps it at 80 columns
+# unless told otherwise; piped help still wraps at 80, since there is no
+# terminal to measure. The option column is wide enough for the longest
+# names here ("--gui-framework {tkinter,textual}"), so their descriptions
+# start on the same line instead of the next.
+_HELP_MAX_WIDTH = 10_000
+_OPTION_COLUMN = 36
+
+# Help color follows uv and cargo: headings bold green, names cyan with the
+# option flags bold. Click's echo drops ANSI when stdout is not a terminal,
+# and its column widths ignore escape codes, so styling costs no alignment
+# and never reaches a pipe; NO_COLOR is the one case left to handle here.
+
+
+def _style(text: str, **styles: Any) -> str:
+    if not text or color_disabled_by_env():
+        return text
+    return typer.style(text, **styles)
+
+
+@contextmanager
+def _section(formatter: Any, name: str) -> Iterator[None]:
+    """``formatter.section`` with a colored heading, colon included."""
+    formatter.write_paragraph()
+    formatter.write(f"{'':>{formatter.current_indent}}{_style(name + ':', fg='green', bold=True)}\n")
+    formatter.indent()
+    try:
+        yield
+    finally:
+        formatter.dedent()
+
+
+def _usage_prefix() -> str:
+    return _style("Usage:", fg="green", bold=True) + " "
+
+
+def _styled_record(param: Any, record: tuple[str, str]) -> tuple[str, str]:
+    """Color one help row: the flags bold, any metavar after them plain."""
+    name, help_text = _unescape(record)
+    if param.param_type_name == "argument":
+        return _style(name, fg="cyan"), help_text
+    flags = [*param.opts, *param.secondary_opts]
+    end = max((name.find(flag) + len(flag) for flag in flags if flag in name), default=len(name))
+    return _style(name[:end], fg="cyan", bold=True) + _style(name[end:], fg="cyan"), help_text
+
+
+# Typer 0.26 stopped depending on Click and vendors it as ``typer._click``, so
+# ``click.Context`` is the wrong class on newer Typer and ``click`` may not be
+# installed at all. The overrides below take ``ctx`` and ``formatter`` as
+# ``Any`` because no public import names the right type across the supported
+# Typer range; they rely only on methods both Click lineages provide.
+
+
+class _PlainHelpMixin:
+    """Render option help without Typer's Rich escaping."""
+
+    def format_usage(self, ctx: Any, formatter: Any) -> None:
+        # Every argument here carries an explicit metavar, and it is printed as
+        # written. Typer 0.27 decorates it instead, wrapping required arguments
+        # in braces and optional ones in brackets, so the same command would
+        # print a different usage line depending on the installed Typer.
+        pieces = [self.options_metavar] if self.options_metavar else []  # type: ignore[attr-defined]
+        for param in self.get_params(ctx):  # type: ignore[attr-defined]
+            if param.param_type_name == "argument" and param.metavar:
+                pieces.append(param.metavar)
+            else:
+                pieces.extend(param.get_usage_pieces(ctx))
+        formatter.write_usage(ctx.command_path, " ".join(pieces), prefix=_usage_prefix())
+
+    def format_arguments(self, ctx: Any, formatter: Any) -> None:
+        # Click 8.5 added this step, with its own "Positional arguments"
+        # heading. format_options below already renders the arguments, and a
+        # Typer built on the standalone Click would otherwise list them twice.
+        pass
+
+    def format_options(self, ctx: Any, formatter: Any) -> None:
+        args: list[tuple[str, str]] = []
+        opts: list[tuple[str, str]] = []
+        for param in self.get_params(ctx):  # type: ignore[attr-defined]
+            record = param.get_help_record(ctx)
+            if not record:
+                continue
+            bucket = args if param.param_type_name == "argument" else opts
+            bucket.append(_styled_record(param, record))
+        if args:
+            with _section(formatter, "Arguments"):
+                formatter.write_dl(args, col_max=_OPTION_COLUMN)
+        if opts:
+            with _section(formatter, "Options"):
+                formatter.write_dl(opts, col_max=_OPTION_COLUMN)
+
+
+class ExecsqlCommand(_PlainHelpMixin, TyperCommand):
+    """A command whose help is plain text, brackets and all."""
+
+
+class ExecsqlGroup(TyperGroup):
+    """The top-level command group: default command, dual usage, grouped options.
+
+    Three departures from Click's defaults, each for a reason:
+
+    *Default command, deprecated.* ``execsql script.sql server db`` has been
+    the invocation since upstream v1.130.1 — it is in shell scripts and cron
+    entries — so an argument list carrying no command name still gets ``run``
+    inserted before the parser sees it, with a deprecation warning on stderr;
+    the form stops working in execsql2 3.0. Doing that here rather than in the
+    console-script wrapper means the app behaves the same however it is
+    reached: the entry point, ``python -m execsql``, or a test driving ``app``
+    directly.
+
+    *One usage line.* Help documents one form, ``execsql COMMAND``.
+
+    *Grouped options.* Click lists every option in one block. The four that
+    apply to the whole tool rather than to a run are worth separating from
+    ``--help``.
+    """
+
+    def parse_args(self, ctx: Any, args: list[str]) -> list[str]:
+        from execsql.cli.dispatch import normalize
+
+        if not args:
+            # Running execsql with no arguments is a usage error: the help goes
+            # to stdout, and the status is 2, as for any other usage error.
+            # Upstream exited 0 here; this is a recorded divergence
+            # (docs/about/divergence.md, "CLI Interface"). Click's own
+            # no_args_is_help exits 0 on Click 8.1 and 2 on 8.2+, so the status
+            # is set here rather than left to whichever Click is installed.
+            typer.echo(ctx.get_help(), color=ctx.color)
+            ctx.exit(2)
+        normalized = normalize(args)
+        if normalized is not args:
+            _err_console.print(f"[yellow]{deprecated_bare_form(args[0])}[/yellow]", highlight=False, soft_wrap=True)
+        return super().parse_args(ctx, normalized)
+
+    def list_commands(self, ctx: Any) -> list[str]:
+        # Typer registers command groups (``list``) after plain commands; help
+        # follows the order COMMANDS gives instead.
+        from execsql.cli.dispatch import COMMANDS
+
+        names = super().list_commands(ctx)
+        return sorted(names, key=lambda n: COMMANDS.index(n) if n in COMMANDS else len(COMMANDS))
+
+    def format_usage(self, ctx: Any, formatter: Any) -> None:
+        formatter.write_usage(ctx.command_path, "[OPTIONS] COMMAND [ARGS]...", prefix=_usage_prefix())
+
+    def format_options(self, ctx: Any, formatter: Any) -> None:
+        globals_: list[tuple[str, str]] = []
+        rest: list[tuple[str, str]] = []
+        for param in self.get_params(ctx):
+            record = param.get_help_record(ctx)
+            if not record:
+                continue
+            bucket = globals_ if any(o in param.opts for o in _GLOBAL_OPTIONS) else rest
+            bucket.append(_styled_record(param, record))
+
+        if globals_:
+            with _section(formatter, "Global options"):
+                formatter.write_dl(globals_, col_max=_OPTION_COLUMN)
+        if rest:
+            with _section(formatter, "Options"):
+                formatter.write_dl(rest, col_max=_OPTION_COLUMN)
+        self.format_commands(ctx, formatter)
+
+    def format_commands(self, ctx: Any, formatter: Any) -> None:
+        # Click's own version, with the command names colored.
+        commands = [
+            (name, cmd)
+            for name in self.list_commands(ctx)
+            if (cmd := self.get_command(ctx, name)) is not None and not cmd.hidden
+        ]
+        if not commands:
+            return
+        limit = formatter.width - 6 - max(len(name) for name, _ in commands)
+        with _section(formatter, "Commands"):
+            formatter.write_dl(
+                [(_style(name, fg="cyan", bold=True), cmd.get_short_help_str(limit)) for name, cmd in commands],
+            )
+
+
+class ExecsqlSubGroup(ExecsqlGroup):
+    """A command with commands of its own (``execsql list``).
+
+    The app's help layout, without the app's ``run`` insertion; with no
+    arguments it prints its help and exits 2, as the app does.
+    """
+
+    def parse_args(self, ctx: Any, args: list[str]) -> list[str]:
+        if not args:
+            typer.echo(ctx.get_help(), color=ctx.color)
+            ctx.exit(2)
+        return TyperGroup.parse_args(self, ctx, args)
+
+    def list_commands(self, ctx: Any) -> list[str]:
+        return TyperGroup.list_commands(self, ctx)
+
+
+app = typer.Typer(
+    cls=ExecsqlGroup,
+    name="execsql",
+    # Plain click rendering: no panels, and format_options below can group.
+    rich_markup_mode=None,
+    help="Run, format and lint SQL scripts with metacommands.",
+    add_completion=False,
+    no_args_is_help=True,
+    # Upstream's optparse answered -h as well as --help. Commands inherit this.
+    context_settings={"help_option_names": ["-h", "--help"], "max_content_width": _HELP_MAX_WIDTH},
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        _console.print(f"execsql [bold cyan]{__version__}[/bold cyan]")
+        raise typer.Exit()
+
+
+def _online_help_callback(value: bool) -> None:
+    if value:
+        import webbrowser
+
+        webbrowser.open("https://execsql2.readthedocs.io/en/latest/", new=2, autoraise=True)
+        raise typer.Exit()
+
+
+@app.callback()
+def _global_options(
+    online_help: bool = typer.Option(
+        False,
+        "-o",
+        "--online-help",
+        callback=_online_help_callback,
+        is_eager=True,
+        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:
+    """Options about execsql itself rather than about one run.
+
+    Both are eager and exit on their own, so neither needs to reach a
+    command; the callback body has nothing to do.
+    """

execsql/cli/commands/__init__.py

@@ -0,0 +1,13 @@
+"""execsql's commands, one module each.
+
+Importing this package registers every command on
+:data:`execsql.cli.application.app`. The import order is the order
+``execsql --help`` lists them in.
+"""
+
+from execsql.cli.commands import run  # noqa: F401
+from execsql.cli.commands import format  # noqa: F401, A004
+from execsql.cli.commands import lint  # noqa: F401
+from execsql.cli.commands import config  # noqa: F401
+from execsql.cli.commands import listing  # noqa: F401
+from execsql.cli.commands import init  # noqa: F401

execsql/cli/commands/config.py

@@ -0,0 +1,205 @@
+"""The ``config`` command: list config options, or print the template."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.markup import escape
+
+from execsql.cli.application import ExecsqlCommand, app
+from execsql.cli.help import _console, _err_console, _init_config
+from execsql.cli.options import ConfigFileOpt, OutputFormat, OutputFormatOpt
+
+__all__ = ["config_cmd", "config_rows"]
+
+
+def config_rows(script: str | None, config_file: str | None) -> tuple[list[str], list[dict[str, Any]]]:
+    """Resolve config the way ``execsql run SCRIPT`` would; describe every option.
+
+    Args:
+        script: A script path whose directory is searched for ``execsql.conf``,
+            as a run of that script would; ``None`` searches only the working
+            directory, user and system locations.
+        config_file: An extra file loaded last, as ``--config`` does for a run.
+
+    Returns:
+        The files read, in load order, and one dict per option with ``section``,
+        ``key``, ``type``, ``value``, ``default`` and ``source`` (the file that
+        set it, or ``None`` when the default applies). Password values are
+        replaced by ``"***"``.
+    """
+    from execsql.cli.run import _load_config, _seed_early_subvars
+    from execsql.config import ConfigData
+    from execsql.metacommands.debug import _SENSITIVE_ATTRS  # what DEBUG WRITE CONFIG masks
+
+    conf = _load_config(script, _seed_early_subvars(), config_file)
+    rows: list[dict[str, Any]] = []
+    # Options read inline in ConfigData register after the rest, so group by
+    # section (in first-seen order) to keep each section in one block.
+    sections: dict[str, int] = {}
+    for section, _key, _type in ConfigData._schema.values():
+        sections.setdefault(section, len(sections))
+    ordered = sorted(ConfigData._schema.items(), key=lambda item: sections[item[1][0]])
+    for attr, (section, key, type_label) in ordered:
+        value = getattr(conf, attr, None)
+        default = conf.defaults.get(attr)
+        if attr in _SENSITIVE_ATTRS:
+            value = "***" if value else value
+            default = "***" if default else default
+        rows.append(
+            {
+                "section": section,
+                "key": key,
+                "type": type_label,
+                "value": value,
+                "default": default,
+                "source": conf.sources.get(attr),
+            },
+        )
+    return list(conf.files_read), rows
+
+
+def _shown(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "yes" if value else "no"
+    return str(value)
+
+
+def _print_text(files: list[str], rows: list[dict[str, Any]]) -> None:
+    short = _short
+
+    if files:
+        _console.print("[bold]Config files read, in order:[/bold]")
+        for f in files:
+            _console.print(f"  {short(f)}", highlight=False, soft_wrap=True)
+    else:
+        _console.print("[bold]No config files found;[/bold] every option has its default.")
+    width_key = max(len(r["key"]) for r in rows)
+    width_val = min(40, max(len(_shown(r["value"])) for r in rows))
+    section = None
+    for r in rows:
+        if r["section"] != section:
+            section = r["section"]
+            _console.print(f"\n[bold green]\\[{section}][/bold green]")
+        source = short(r["source"]) if r["source"] else "[dim]default[/dim]"
+        _console.print(
+            f"  [cyan]{r['key']:<{width_key}}[/cyan]  {_shown(r['value']):<{width_val}}  {source}",
+            highlight=False,
+            soft_wrap=True,
+        )
+
+
+def _short(path: str) -> str:
+    home = str(Path.home())
+    return "~" + path[len(home) :] if path.startswith(home + os.sep) else path
+
+
+def _print_problems(files: list[str], problems: list[Any]) -> None:
+    """Problems grouped under each file in line order, then one summary line — the lint layout."""
+    styles = {"error": "bold red", "warning": "yellow"}
+    width = max((len(str(p.line)) for p in problems), default=1)
+    for path in files:
+        mine = [p for p in problems if p.file == path]
+        if not mine:
+            continue
+        _console.print(f"[bold]{_short(path)}[/bold]", highlight=False, soft_wrap=True)
+        for p in mine:
+            line = str(p.line) if p.line else ""
+            style = styles[p.severity]
+            _console.print(
+                f"  {line:>{width}}  [{style}]{p.severity:<7}[/{style}]  {escape(p.message)}",
+                highlight=False,
+                soft_wrap=True,
+            )
+        _console.print()
+    errors = sum(p.severity == "error" for p in problems)
+    warnings = len(problems) - errors
+    checked = f"{len(files)} config file{'s' if len(files) != 1 else ''} checked"
+    if not files:
+        _console.print("No config files found.")
+    elif not problems:
+        _console.print(f"No problems found ({checked}).")
+    else:
+        with_problems = len({p.file for p in problems})
+        parts = [f"{n} {word}{'s' if n != 1 else ''}" for n, word in ((errors, "error"), (warnings, "warning")) if n]
+        _console.print(
+            f"Found {len(problems)} problem{'s' if len(problems) != 1 else ''} in {with_problems} "
+            f"file{'s' if with_problems != 1 else ''}: {', '.join(parts)} ({checked})",
+        )
+
+
+@app.command(cls=ExecsqlCommand, name="config")
+def config_cmd(
+    script: str | None = typer.Argument(
+        None,
+        metavar="[SQL_SCRIPT]",
+        help=(
+            "Resolve config as a run of this script would, including the execsql.conf "
+            "in its directory. Without it, only the working directory, user and system "
+            "files are read."
+        ),
+    ),
+    init: bool = typer.Option(False, "--init", help="Print a default execsql.conf template to stdout and exit."),
+    validate: bool = typer.Option(
+        False,
+        "--validate",
+        help=(
+            "Check every config file a run would read: invalid values and unreadable files "
+            "are errors, unknown sections and keys are warnings. Exits 1 on any error."
+        ),
+    ),
+    config_file: ConfigFileOpt = None,
+    output_format: OutputFormatOpt = OutputFormat.text,
+) -> None:
+    """List config options with their values, defaults and sources.
+
+    Config files are read from the same places a run reads them. Passwords
+    are never shown.
+    """
+    if init and validate:
+        raise typer.BadParameter("--init and --validate cannot be combined.", param_hint="'--validate'")
+    if init:
+        _init_config()
+        raise typer.Exit()
+    if config_file and not Path(config_file).is_file():
+        _err_console.print(f"[bold red]Error:[/bold red] Config file {config_file!r} does not exist.")
+        raise typer.Exit(code=2)
+    if script and not Path(script).is_file():
+        _err_console.print(f'[bold red]Error:[/bold red] SQL script file "{script}" does not exist.')
+        raise typer.Exit(code=2)
+
+    if validate:
+        raise typer.Exit(code=_validate(script, config_file, output_format))
+
+    files, rows = config_rows(script, config_file)
+    if output_format is OutputFormat.json:
+        sys.stdout.write(json.dumps({"files_read": files, "options": rows}, indent=2, default=str) + "\n")
+    else:
+        _print_text(files, rows)
+
+
+def _validate(script: str | None, config_file: str | None, output_format: OutputFormat) -> int:
+    """Run ``--validate``; return the exit code."""
+    from execsql.cli.run import _seed_early_subvars
+    from execsql.config_validation import validate_config
+
+    script_path = str(Path(script).resolve().parent) if script else os.getcwd()
+    files, problems = validate_config(script_path, _seed_early_subvars(), config_file)
+    if output_format is OutputFormat.json:
+        payload = {
+            "files_checked": files,
+            "problems": [
+                {"file": p.file, "line": p.line or None, "severity": p.severity, "message": p.message} for p in problems
+            ],
+        }
+        sys.stdout.write(json.dumps(payload, indent=2) + "\n")
+    else:
+        _print_problems(files, problems)
+    return 1 if any(p.severity == "error" for p in problems) else 0

execsql/cli/commands/format.py

@@ -0,0 +1,100 @@
+"""The ``format`` command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from execsql.cli.application import ExecsqlCommand, app
+from execsql.cli.help import _err_console
+from execsql.cli.options import ConfigFileOpt, ScriptEncodingOpt
+
+__all__ = ["format_cmd"]
+
+
+def format_cmd(
+    targets: list[Path] = typer.Argument(
+        ...,
+        metavar="FILE_OR_DIR...",
+        help=(
+            "Files or directories to format. Directories are searched recursively for *.sql files. "
+            "- reads one script from stdin and writes the result to stdout."
+        ),
+    ),
+    check: bool = typer.Option(False, "--check", help="Exit 1 if any file needs changes; write nothing."),
+    diff: bool = typer.Option(
+        False,
+        "--diff",
+        help="Print a unified diff of each file that would change; write nothing. Exits 1 if any would.",
+    ),
+    in_place: bool = typer.Option(False, "-i", "--in-place", help="Modify files in place."),
+    # The three layout options default to None — "not given" — so that
+    # [format] in a config file applies unless the command line says otherwise,
+    # in either direction.
+    sql: bool | None = typer.Option(
+        None,
+        "--sql/--no-sql",
+        help="Reformat SQL with sqlglot, or only metacommands. Default: [format] sql, else --sql.",
+        show_default=False,
+    ),
+    indent: int | None = typer.Option(
+        None,
+        "--indent",
+        metavar="N",
+        help="Spaces per indent level. Default: [format] indent, else 4.",
+        show_default=False,
+    ),
+    leading_comma: bool | None = typer.Option(
+        None,
+        "--leading-comma/--no-leading-comma",
+        help="Commas at the start of lines instead of the end. Default: [format] leading_comma, else off.",
+        show_default=False,
+    ),
+    script_encoding: ScriptEncodingOpt = None,
+    # The old spelling of --script-encoding, kept working but out of --help.
+    encoding: str | None = typer.Option(None, "--encoding", metavar="NAME", hidden=True),
+    config_file: ConfigFileOpt = None,
+) -> None:
+    """Normalize metacommand keywords, block indentation, and SQL layout.
+
+    SQL reformatting needs the [formatter] extra; --no-sql works without it.
+    Layout options not given here come from [format] in a config file.
+    """
+    from execsql.cli.run import _configured_script_encoding, _tool_config
+    from execsql.format import _require_sqlglot, run_formatter
+
+    if Path("-") in targets:
+        if len(targets) > 1:
+            raise typer.BadParameter("- (stdin) cannot be combined with other paths.", param_hint="FILE_OR_DIR")
+        if in_place:
+            raise typer.BadParameter("stdin cannot be formatted in place; drop -i.", param_hint="'-i'")
+    if diff and in_place:
+        raise typer.BadParameter("--diff writes nothing, so it cannot be combined with -i.", param_hint="'--diff'")
+    if config_file and not Path(config_file).is_file():
+        _err_console.print(f"[bold red]Error:[/bold red] Config file {config_file!r} does not exist.")
+        raise typer.Exit(code=2)
+
+    conf = _tool_config(config_file)
+    no_sql = not (conf.format_sql if sql is None else sql)
+    if not no_sql:
+        try:
+            _require_sqlglot()
+        except ImportError as exc:
+            _err_console.print(f"[bold red]Error:[/bold red] {exc}", highlight=False)
+            raise typer.Exit(code=1) from exc
+    raise typer.Exit(
+        code=run_formatter(
+            targets,
+            check=check,
+            diff=diff,
+            in_place=in_place,
+            no_sql=no_sql,
+            indent=conf.format_indent if indent is None else indent,
+            leading_comma=conf.format_leading_comma if leading_comma is None else leading_comma,
+            encoding=script_encoding or encoding or _configured_script_encoding(conf) or "utf-8",
+        ),
+    )
+
+
+app.command(cls=ExecsqlCommand, name="format")(format_cmd)