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

execsql/cli/commands/init.py

@@ -0,0 +1,135 @@
+"""The ``init`` command: set up execsql in a project directory."""
+
+from __future__ import annotations
+
+import datetime
+import importlib.resources
+import re
+from pathlib import Path
+
+import typer
+from rich.markup import escape
+
+from execsql import __version__
+from execsql.cli.application import ExecsqlCommand, app
+from execsql.cli.help import _console
+
+__all__ = ["init_cmd", "pre_commit_snippet", "script_header"]
+
+_HOOKS_REPO = "https://github.com/geocoug/execsql"
+
+
+def script_header(name: str, today: datetime.date | None = None) -> str:
+    """The header a new script starts with: purpose, notes, project, authors and history."""
+    today = today or datetime.date.today()
+    text = importlib.resources.files("execsql.data").joinpath("script_header.sql").read_text(encoding="utf-8")
+    return text.replace("{name}", name).replace("{date}", today.isoformat()).replace("{year}", str(today.year))
+
+
+def pre_commit_snippet(indent: str = "  ") -> str:
+    """The ``repos:`` entry for the execsql-format and execsql-lint hooks, at *indent*."""
+    return (
+        f"{indent}- repo: {_HOOKS_REPO}\n"
+        f"{indent}  rev: v{__version__}\n"
+        f"{indent}  hooks:\n"
+        f"{indent}    - id: execsql-format\n"
+        f"{indent}    - id: execsql-lint\n"
+    )
+
+
+def _add_hooks(path: Path) -> tuple[str, str]:
+    """Add the execsql hooks to a pre-commit config; return (action, detail).
+
+    A new file is written whole. An existing one is only appended to, and only
+    when ``repos:`` is its last top-level key, so its comments and layout are
+    untouched; anything else is reported with the snippet to add by hand.
+    """
+    if not path.exists():
+        path.write_text("repos:\n" + pre_commit_snippet(), encoding="utf-8")
+        return "created", ""
+    text = path.read_text(encoding="utf-8")
+    if _HOOKS_REPO in text or "geocoug/execsql" in text:
+        return "skipped", "already has the execsql hooks"
+    top_level = re.findall(r"^([A-Za-z_][\w-]*)\s*:", text, flags=re.M)
+    if not top_level or top_level[-1] != "repos":
+        return "manual", "repos: is not the last key"
+    item = re.search(r"^(\s*)- repo:", text, flags=re.M)
+    indent = item.group(1) if item else "  "
+    path.write_text(text.rstrip("\n") + "\n" + pre_commit_snippet(indent), encoding="utf-8")
+    return "added", "the execsql-format and execsql-lint hooks"
+
+
+def _write(path: Path, content: str, force: bool) -> str:
+    if path.exists() and not force:
+        return "skipped"
+    existed = path.exists()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return "overwrote" if existed else "created"
+
+
+@app.command(cls=ExecsqlCommand, name="init")
+def init_cmd(
+    directory: Path = typer.Argument(
+        Path("."),
+        metavar="[DIR]",
+        help="Project directory; created if missing. Default: the current directory.",
+        show_default=False,
+    ),
+    script: str = typer.Option(
+        "main.sql",
+        "--script",
+        metavar="NAME",
+        help="Name of the script to create, relative to DIR. .sql is added if missing.",
+    ),
+    no_script: bool = typer.Option(False, "--no-script", help="Do not create a script."),
+    no_config: bool = typer.Option(False, "--no-config", help="Do not create execsql.conf."),
+    no_pre_commit: bool = typer.Option(
+        False,
+        "--no-pre-commit",
+        help="Do not create or change .pre-commit-config.yaml.",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        help="Overwrite an existing execsql.conf or script. .pre-commit-config.yaml is never overwritten.",
+    ),
+) -> None:
+    """Set up execsql in a project: a config file, a script with a header, and pre-commit hooks.
+
+    Existing files are left alone unless --force is given. Run it again in an
+    existing project with --no-config --no-pre-commit --script NAME to add a
+    script.
+    """
+    from execsql.cli.help import _init_config_text
+
+    directory.mkdir(parents=True, exist_ok=True)
+    report: list[tuple[str, str, str]] = []
+
+    if not no_config:
+        path = directory / "execsql.conf"
+        report.append((_write(path, _init_config_text(), force), str(path), ""))
+
+    if not no_script:
+        name = script if Path(script).suffix else f"{script}.sql"
+        path = directory / name
+        report.append((_write(path, script_header(Path(name).name), force), str(path), ""))
+
+    if not no_pre_commit:
+        path = directory / ".pre-commit-config.yaml"
+        action, detail = _add_hooks(path)
+        report.append((action, str(path), detail))
+
+    styles = {"created": "green", "added": "green", "overwrote": "yellow", "skipped": "dim", "manual": "yellow"}
+    for action, path_text, detail in report:
+        style = styles[action]
+        label = "add by hand" if action == "manual" else action
+        note = f" ({escape(detail)})" if detail else ""
+        if action == "skipped" and not detail:
+            note = " (exists; --force to overwrite)"
+        _console.print(f"  [{style}]{label:<11}[/{style}] {escape(path_text)}{note}", highlight=False, soft_wrap=True)
+        if action == "manual":
+            _console.print("\n  Add this under repos: in that file:\n", highlight=False)
+            _console.print(escape(pre_commit_snippet("    ")), highlight=False, soft_wrap=True)
+    if not report:
+        _console.print("Nothing to do: --no-config, --no-script and --no-pre-commit were all given.")

execsql/cli/commands/lint.py

@@ -0,0 +1,233 @@
+"""The ``lint`` command: check scripts for problems without connecting."""
+
+from __future__ import annotations
+
+import sys
+from enum import Enum
+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__ = ["LintFormat", "lint_cmd", "lint_paths", "sql_files"]
+
+
+def sql_files(targets: list[str]) -> list[Path]:
+    """Every ``.sql`` file named by *targets*, directories walked recursively."""
+    found: list[Path] = []
+    for raw in targets:
+        p = Path(raw)
+        if p.is_dir():
+            found.extend(sorted(q for q in p.rglob("*.sql")))
+        else:
+            found.append(p)
+    return found
+
+
+def lint_paths(
+    targets: list[str],
+    *,
+    select: tuple[str, ...] = (),
+    ignore: tuple[str, ...] = (),
+    output_format: str = "text",
+    statistics: bool = False,
+    encoding: str = "utf-8",
+    strict: bool = False,
+) -> int:
+    """Lint every script named by *targets*; return the process exit code.
+
+    Directories are searched recursively, so one call checks a whole script
+    library.
+
+    Args:
+        targets: Files and directories; directories are searched for ``*.sql``.
+            ``-`` reads one script from stdin, reported as ``<stdin>``.
+        select: Rule-code prefixes to report (empty means all), already
+            validated by :func:`execsql.cli.lint.resolve_selectors`.
+        ignore: Rule-code prefixes to drop; wins over *select*.
+        output_format: ``"text"`` (grouped by file), ``"concise"`` (one line
+            per issue), ``"github"`` (GitHub Actions workflow commands) or ``"json"``. JSON writes one array to stdout and
+            nothing else.
+        statistics: Report a count per rule instead of each issue.
+        encoding: Character encoding every script is read with. A script that
+            does not decode is reported as a parse error (``P001``).
+        strict: Warnings fail too: exit ``1`` when any issue is reported.
+
+    Returns:
+        ``1`` when any reported issue is an error or no ``.sql`` file was
+        found, otherwise ``0``.
+    """
+    import json
+
+    from execsql.cli.help import _err_console
+    from execsql.cli.lint import (
+        Issue,
+        _issue,
+        exit_code,
+        filter_issues,
+        lint as _lint_script,
+        parse_error,
+        print_concise,
+        render_github,
+        print_statistics,
+        print_text,
+        render_json,
+        rule_counts,
+    )
+    from execsql.exceptions import ErrInfo
+    from execsql.script.parser import parse_string
+
+    paths = sql_files(targets)
+    if not paths:
+        _err_console.print("[bold red]Error:[/bold red] no .sql files found in the given paths.")
+        return 1
+
+    per_file: list[tuple[str, list[Issue]]] = []
+    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 UnicodeDecodeError as exc:
+            found = [_issue("P001", label, 0, f"cannot decode as {encoding} ({exc.reason}); set -f/--script-encoding")]
+        except OSError as exc:
+            found = [_issue("P001", label, 0, f"cannot read: {exc.strerror or exc}")]
+        else:
+            try:
+                tree = parse_string(source, label)
+            except ErrInfo as exc:
+                found = [parse_error(label, exc)]
+            else:
+                found = _lint_script(tree, script_path=None if stdin else label)
+        per_file.append((label, sorted(filter_issues(found, select, ignore), key=lambda i: (i.line, i.code))))
+
+    reported = [issue for _, issues in per_file for issue in issues]
+
+    if output_format == "json":
+        if statistics:
+            rows = [
+                {"code": rule.code, "rule": rule.name, "severity": rule.severity, "count": n}
+                for rule, n in rule_counts(reported)
+            ]
+            sys.stdout.write(json.dumps(rows, indent=2) + "\n")
+        else:
+            sys.stdout.write(render_json(reported) + "\n")
+        return exit_code(reported, strict=strict)
+
+    if statistics:
+        print_statistics(per_file, len(paths))
+    elif output_format == "concise":
+        print_concise(per_file, len(paths))
+    elif output_format == "github":
+        # Workflow commands only: any other line in the step's log is noise.
+        annotations = render_github(per_file)
+        if annotations:
+            sys.stdout.write(annotations + "\n")
+    else:
+        print_text(per_file, len(paths))
+    return exit_code(reported, strict=strict)
+
+
+class LintFormat(str, Enum):
+    """Output formats for ``execsql lint``."""
+
+    text = "text"
+    concise = "concise"
+    json = "json"
+    github = "github"
+
+
+@app.command(
+    cls=ExecsqlCommand,
+    name="lint",
+    help=(
+        "Statically check scripts for problems. No database connection is made.\n\n"
+        "Every issue names its rule code, which --select and --ignore accept, as a full "
+        "code (V001) or a prefix (V). Parse errors (P001) are always reported. Exits 1 "
+        "when any error is found; warnings alone exit 0 unless --strict is given.\n\n"
+        "Rules: https://execsql2.readthedocs.io/en/latest/reference/lint/"
+    ),
+)
+def lint_cmd(
+    targets: list[str] = typer.Argument(
+        ...,
+        metavar="FILE_OR_DIR...",
+        help=(
+            "Files or directories to check. Directories are searched recursively for *.sql files. "
+            "- reads one script from stdin."
+        ),
+    ),
+    select: list[str] | None = typer.Option(
+        None,
+        "--select",
+        metavar="CODES",
+        help="Report only these rules: codes or prefixes, comma-separated (e.g. V001,F). Repeatable.",
+    ),
+    ignore: list[str] | None = typer.Option(
+        None,
+        "--ignore",
+        metavar="CODES",
+        help="Do not report these rules: codes or prefixes, comma-separated. Wins over --select. Repeatable.",
+    ),
+    output_format: LintFormat = typer.Option(
+        LintFormat.text,
+        "--output-format",
+        help=(
+            "text groups issues by file; concise is one path:line line per issue; json is for tools; "
+            "github prints GitHub Actions annotations."
+        ),
+    ),
+    statistics: bool = typer.Option(
+        False,
+        "--statistics",
+        help="Show how many times each rule fired instead of listing every issue.",
+    ),
+    strict: bool | None = typer.Option(
+        None,
+        "--strict/--no-strict",
+        help="Exit 1 on warnings too, not only on errors. Default: [lint] strict, else off.",
+        show_default=False,
+    ),
+    script_encoding: ScriptEncodingOpt = None,
+    config_file: ConfigFileOpt = None,
+) -> None:
+    """The ``lint`` command; its user-facing help is the decorator's ``help``."""
+    from execsql.cli.lint import resolve_selectors
+    from execsql.cli.run import _configured_script_encoding, _tool_config
+
+    if "-" in targets and len(targets) > 1:
+        raise typer.BadParameter("- (stdin) cannot be combined with other paths.", param_hint="FILE_OR_DIR")
+    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)
+    # A flag replaces the [lint] setting rather than adding to it, as in ruff.
+    try:
+        selected = resolve_selectors(select)
+        ignored = resolve_selectors(ignore)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+    try:
+        if not select and conf.lint_select:
+            selected = resolve_selectors([conf.lint_select])
+        if not ignore and conf.lint_ignore:
+            ignored = resolve_selectors([conf.lint_ignore])
+    except ValueError as exc:
+        _err_console.print(f"[bold red]Error:[/bold red] \\[lint] in config: {exc}", highlight=False)
+        raise typer.Exit(code=2) from exc
+
+    raise typer.Exit(
+        code=lint_paths(
+            targets,
+            select=selected,
+            ignore=ignored,
+            output_format=output_format.value,
+            statistics=statistics,
+            encoding=script_encoding or _configured_script_encoding(conf) or "utf-8",
+            strict=conf.lint_strict if strict is None else strict,
+        ),
+    )

execsql/cli/commands/listing.py

@@ -0,0 +1,81 @@
+"""The ``list`` command: reference lists, one subcommand each.
+
+``execsql list metacommands|encodings|plugins|keywords``. Each list is its own
+command so it can take options of its own. The module is not named ``list``
+so importing it never shadows the builtin.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import typer
+
+from execsql.cli.application import ExecsqlCommand, ExecsqlSubGroup, app
+from execsql.cli.help import (
+    _encoding_names,
+    _metacommand_rows,
+    _plugins_data,
+    _print_encodings,
+    _print_keywords_json,
+    _print_keywords_text,
+    _print_metacommands,
+    _print_plugins,
+)
+from execsql.cli.options import OutputFormat, OutputFormatOpt
+
+__all__ = ["list_app"]
+
+list_app = typer.Typer(
+    cls=ExecsqlSubGroup,
+    name="list",
+    help="List metacommands, encodings, plugins or keywords.",
+    rich_markup_mode=None,
+    add_completion=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+app.add_typer(list_app, name="list")
+
+
+def _json(data: object) -> None:
+    sys.stdout.write(json.dumps(data, indent=2) + "\n")
+
+
+@list_app.command(cls=ExecsqlCommand, name="metacommands")
+def metacommands_cmd(output_format: OutputFormatOpt = OutputFormat.text) -> None:
+    """Every metacommand and its syntax."""
+    if output_format is OutputFormat.json:
+        _json([{"name": name, "syntax": syntax} for name, syntax in _metacommand_rows()])
+    else:
+        _print_metacommands()
+
+
+@list_app.command(cls=ExecsqlCommand, name="encodings")
+def encodings_cmd(output_format: OutputFormatOpt = OutputFormat.text) -> None:
+    """Every character encoding name -e, -f, -g and -i accept."""
+    if output_format is OutputFormat.json:
+        _json(_encoding_names())
+    else:
+        _print_encodings()
+
+
+@list_app.command(cls=ExecsqlCommand, name="plugins")
+def plugins_cmd(output_format: OutputFormatOpt = OutputFormat.text) -> None:
+    """Installed plugins: metacommands, exporters, importers."""
+    if output_format is OutputFormat.json:
+        _json(_plugins_data())
+    else:
+        _print_plugins()
+
+
+@list_app.command(cls=ExecsqlCommand, name="keywords")
+def keywords_cmd(output_format: OutputFormatOpt = OutputFormat.text) -> None:
+    """The full vocabulary: metacommands by category, conditions, CONFIG options,
+    export formats, database types, variable patterns. Its JSON is what editor
+    tooling reads.
+    """
+    if output_format is OutputFormat.json:
+        _print_keywords_json()
+    else:
+        _print_keywords_text()