sqlty 0.1.0__cp315-cp315-win_amd64.whl

sqlty/__init__.py

@@ -0,0 +1,99 @@
+"""SQLTy - Type-safe SQL queries for Python."""
+
+import sys
+from string.templatelib import Template
+from typing import get_args, overload
+
+if sys.version_info >= (3, 15):
+    from typing import TypeForm
+else:
+    from typing_extensions import Sentinel as sentinel
+    from typing_extensions import TypeForm
+
+
+def __getattr__(name: str) -> str:
+    # ``__version__`` is looked up lazily: importlib.metadata costs ~10 ms to import.
+    if name == "__version__":
+        import importlib.metadata
+
+        try:
+            version = importlib.metadata.version(__name__)
+        except importlib.metadata.PackageNotFoundError:
+            version = "0.0.0"  # Fallback for development mode
+        globals()["__version__"] = version
+        return version
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = ["SQL", "UNTYPED", "SQLTemplate", "row_form"]
+
+
+class SQL[T](str):
+    pass
+
+
+class SQLTemplate[T]:
+    """A t-string query, ``SQLTemplate[T](t"--sql\\n...")``, whose rows are ``T``.
+
+    ``string.templatelib.Template`` cannot be subclassed, so the template is kept in
+    ``template``: pass that to a driver that runs templates (psycopg >= 3.3), or the
+    whole query to the ``sqlty.drivers.psycopg`` helpers. ``row_form`` reads ``T``.
+
+    Example:
+        >>> user_id = 1
+        >>> query = SQLTemplate[tuple[int]](t"--sql\\nSELECT id::INTEGER FROM users WHERE id = {user_id}")
+        >>> query.template.values
+        (1,)
+        >>> row_form(query)
+        tuple[int]
+    """
+
+    __slots__ = ("__orig_class__", "template")
+
+    def __init__(self, template: Template, /) -> None:
+        self.template = template
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.template!r})"
+
+
+UNTYPED = sentinel("UNTYPED")
+"""Row type of a query sqlty could not infer: ``SQL[UNTYPED]``.
+
+Unlike ``Any``, type checkers reject using an ``UNTYPED`` row as a concrete
+type. ``sqlty rewrite --untyped sentinel`` emits it; ``sqlty check`` flags it
+(``untyped-query``) until casts or a schema make the row type known.
+"""
+
+
+_MISSING: object = object()
+
+
+@overload
+def row_form[T](query: SQL[T] | SQLTemplate[T], /) -> TypeForm[T]: ...
+
+
+@overload
+def row_form[T, D](query: SQL[T] | SQLTemplate[T], default: D, /) -> TypeForm[T] | D: ...
+
+
+def row_form(query: object, default: object = _MISSING, /) -> object:
+    """Return the row type ``T`` a ``SQL[T](...)`` instance was built with.
+
+    The type is read from ``__orig_class__``, so it exists only for queries
+    constructed as ``SQL[T](...)``. Plain strings, annotation-only
+    ``q: SQL[T] = "..."`` and stripped sources carry no runtime type: these
+    raise ``TypeError`` unless a ``default`` is given.
+
+    Example:
+        >>> row_form(SQL[tuple[int, str]]("--sql\\nSELECT 1, 'a'"))
+        tuple[int, str]
+        >>> row_form(SQL("--sql\\nSELECT 1"), None) is None
+        True
+    """
+    orig = getattr(query, "__orig_class__", None)
+    if orig is not None and (args := get_args(orig)):
+        return args[0]
+    if default is not _MISSING:
+        return default
+    raise TypeError(f"{type(query).__name__} has no runtime row type; construct it as SQL[T](...)")

sqlty/__main__.py

@@ -0,0 +1,5 @@
+"""Enable running sqlty as a module: python -m sqlty"""
+
+from sqlty._cli import main
+
+main()

sqlty/_breaking.py

@@ -0,0 +1,191 @@
+"""``sqlty breaking``: the queries and schema of two git revisions, checked across.
+
+During a rolling deploy the code of one revision runs against the schema of another.
+``--against`` names the baseline ``A``; ``--head`` (the working tree by default) names
+``B``. The backward check reads the queries of ``A`` against the schema of ``B`` (migrate
+first), the forward check the queries of ``B`` against the schema of ``A`` (deploy
+first). Each reports only what the other schema breaks: diagnostics a query does not
+already get against its own schema.
+
+Every revision but the working tree is checked out with ``git worktree add --detach``
+into a temporary directory, removed afterwards, so the working tree is never touched.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import shutil
+import subprocess
+import sys
+import tempfile
+from collections.abc import Generator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    import argparse
+
+    from sqlty._cli import Settings, SettingsResolver
+    from sqlty._lint import Diagnostic
+
+Direction = Literal["backward", "forward", "both"]
+
+
+class GitError(Exception):
+    """A git command failed: not a repository, or an unknown revision."""
+
+
+@dataclass
+class Revision:
+    """A checkout of the project at one revision, read as ``sqlty check`` reads it."""
+
+    label: str
+    root: Path
+    resolver: SettingsResolver
+    files: list[Path]
+
+    def settings(self, relative: Path) -> Settings:
+        return self.resolver.for_file(self.root / relative)
+
+
+@dataclass(frozen=True)
+class Finding:
+    direction: Literal["backward", "forward"]
+    path: Path
+    diagnostic: Diagnostic
+
+
+def run(args: argparse.Namespace) -> list[Finding]:
+    """The findings of ``sqlty breaking``, for the paths and revisions ``args`` name."""
+    root = Path(_git(Path.cwd(), "rev-parse", "--show-toplevel")).resolve()
+    paths = [Path(p).resolve().relative_to(root) for p in (args.paths or [Path.cwd()])]
+    with contextlib.ExitStack() as stack:
+        against = _revision(args.against, stack.enter_context(_worktree(root, args.against)), paths)
+        head_root = stack.enter_context(_worktree(root, args.head)) if args.head else root
+        head = _revision(args.head or "the working tree", head_root, paths)
+        findings: list[Finding] = []
+        if args.direction in ("backward", "both"):
+            findings += _compare("backward", queries=against, schema=head)
+        if args.direction in ("forward", "both"):
+            findings += _compare("forward", queries=head, schema=against)
+        return findings
+
+
+def report(
+    findings: list[Finding],
+    against: str,
+    head: str | None,
+    quiet: bool,
+    output_format: Literal["text", "json", "github"] = "text",
+) -> None:
+    """Print each finding: ``path:line: [rule] message (direction)``, a JSON array with a
+    ``direction`` per finding, or GitHub Actions annotations, all errors."""
+    import json
+
+    from sqlty._cli import github_annotation
+
+    if quiet:
+        return
+    head = head or "the working tree"
+    titles = {
+        "backward": f"the queries of {against} against the schema of {head}",
+        "forward": f"the queries of {head} against the schema of {against}",
+    }
+    if output_format == "json":
+        rows = [{"file": str(f.path), **f.diagnostic, "direction": f.direction} for f in findings]
+        print(json.dumps(rows, indent=2))
+        return
+    for finding in findings:
+        d = finding.diagnostic
+        message = f"{d['message']} ({finding.direction}: {titles[finding.direction]})"
+        if output_format == "github":
+            print(github_annotation(finding.path, {**d, "message": message, "severity": "error"}))
+        else:
+            print(f"{finding.path}:{d.get('line', '')}: [{d['rule']}] {message}")
+    if findings and output_format == "text":
+        print(f"Found {len(findings)} breaking change(s)")
+
+
+def _compare(
+    direction: Literal["backward", "forward"], *, queries: Revision, schema: Revision
+) -> list[Finding]:
+    from sqlty._cli import _module_names, read_source
+    from sqlty._source import ParsedSource
+    from sqlty.core import breaking_source
+
+    findings: list[Finding] = []
+    roots = [queries.root]
+    for path in queries.files:
+        relative = path.relative_to(queries.root)
+        own = queries.settings(relative)
+        other = schema.settings(relative)
+        module = _module_names(queries.resolver.resolve(path), roots)[0]
+        text = read_source(path)
+        if text is None:
+            continue
+        parsed = ParsedSource(text, module)
+        for diagnostic in breaking_source(
+            parsed,
+            schema_sql=own.schema,
+            against_sql=other.schema,
+            dialect=own.dialect,
+            rules=own.rules,
+            import_style=own.import_style,
+            untyped=own.untyped,
+            type_modules=own.type_modules,
+        ):
+            findings.append(Finding(direction, relative, diagnostic))
+    return findings
+
+
+def _revision(label: str, root: Path, paths: list[Path]) -> Revision:
+    from sqlty._cli import SettingsResolver, _collect_python_files, build_parser
+
+    args = build_parser().parse_args(["check", *(str(root / p) for p in paths)])
+    with contextlib.chdir(root):
+        resolver = SettingsResolver(args)
+    files = _collect_python_files([root / p for p in paths], resolver.source)
+    return Revision(label, root, resolver, [f.resolve() for f in files])
+
+
+@contextlib.contextmanager
+def _worktree(root: Path, ref: str) -> Generator[Path]:
+    """``ref`` checked out into a temporary worktree, removed on exit."""
+    _git(root, "rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}")
+    directory = Path(tempfile.mkdtemp(prefix="sqlty-breaking-"))
+    try:
+        _git(root, "worktree", "add", "--detach", "--quiet", str(directory), ref)
+        yield directory.resolve()
+    finally:
+        with contextlib.suppress(GitError):
+            _git(root, "worktree", "remove", "--force", str(directory))
+        shutil.rmtree(directory, ignore_errors=True)
+        with contextlib.suppress(GitError):
+            _git(root, "worktree", "prune")
+
+
+def _git(cwd: Path, *args: str) -> str:
+    try:
+        done = subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True, check=False)
+    except FileNotFoundError as exc:
+        raise GitError("git is not installed") from exc
+    if done.returncode != 0:
+        message = done.stderr.strip() or f"git {' '.join(args)} failed"
+        if args[:2] == ("rev-parse", "--verify"):
+            message = f"unknown revision {args[-1].removesuffix('^{commit}')!r}"
+        raise GitError(message)
+    return done.stdout.strip()
+
+
+def main(args: argparse.Namespace) -> None:
+    from sqlty._cli import EXIT_FOUND
+    from sqlty._config import ConfigError
+
+    try:
+        findings = run(args)
+    except GitError as exc:
+        raise ConfigError(str(exc)) from exc
+    report(findings, args.against, args.head, args.quiet, args.output_format)
+    if findings:
+        sys.exit(EXIT_FOUND)