sqlfluff-tstring 0.1.0__tar.gz

sqlfluff_tstring-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: sqlfluff-tstring
+Version: 0.1.0
+Summary: Auto-format SQL inside Python t-strings using sqlfluff
+Keywords: formatter,linter,sql,sqlfluff,t-string
+Author: Krzysztof Żuraw
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Dist: sqlfluff>=4.0.4
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/kzuraw/sqlfluff-tstring
+Project-URL: Issues, https://github.com/kzuraw/sqlfluff-tstring/issues
+Project-URL: Repository, https://github.com/kzuraw/sqlfluff-tstring
+Description-Content-Type: text/markdown
+
+# sqlfluff-tstring
+
+Auto-format SQL inside Python t-strings using [sqlfluff](https://sqlfluff.com/).
+
+Finds `sql(t"...")` calls in `.py` files and formats the embedded SQL, preserving interpolations and respecting your `.sqlfluff` config.
+
+Requires Python 3.14+ (PEP 750 t-strings).
+
+## Installation
+
+```bash
+pip install sqlfluff-tstring
+```
+
+## Usage
+
+```bash
+# Format files in-place
+sqlfluff-tstring src/
+
+# Check mode (exit 1 if changes needed, for CI)
+sqlfluff-tstring --check src/
+
+# Show diff without writing
+sqlfluff-tstring --diff src/
+
+# Override SQL dialect
+sqlfluff-tstring --dialect postgres src/
+
+# Use a specific .sqlfluff config file
+sqlfluff-tstring --config path/to/.sqlfluff src/
+```
+
+## What it does
+
+Given a file like:
+
+```python
+from sql_tstring import sql
+
+query = sql(t"select   *   from   users   where   id = {uid}   and   name = {name}")
+```
+
+Running `sqlfluff-tstring` produces:
+
+```python
+from sql_tstring import sql
+
+query = sql(t"""
+select * from users
+where id = {uid} and name = {name}
+""")
+```
+
+- Interpolations (`{uid}`, `{name!r}`, `{val:.2f}`) are preserved through formatting
+- Single quotes auto-upgrade to triple quotes when sqlfluff introduces newlines
+- Multiline content in triple-quoted t-strings is wrapped with leading/trailing newlines
+- Supports `sql(t"...")` and `obj.sql(t"...")` call patterns
+- Respects your `.sqlfluff` configuration for dialect and rules
+
+## CLI options
+
+```
+sqlfluff-tstring [OPTIONS] [PATHS...]
+
+positional arguments:
+  paths              Files or directories to format (default: .)
+
+options:
+  --check            Exit 1 if changes needed (CI mode)
+  --diff             Show diff, don't write changes
+  --config PATH      Path to .sqlfluff config file
+  --dialect DIALECT  Override SQL dialect
+  -v, --verbose      Show unchanged files
+  -q, --quiet        Suppress all output
+```
+
+Exit codes: `0` = success/no changes, `1` = changes needed (check mode).
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check src/ tests/
+uv run ty check src/
+```

sqlfluff_tstring-0.1.0/README.md

@@ -0,0 +1,87 @@
+# sqlfluff-tstring
+
+Auto-format SQL inside Python t-strings using [sqlfluff](https://sqlfluff.com/).
+
+Finds `sql(t"...")` calls in `.py` files and formats the embedded SQL, preserving interpolations and respecting your `.sqlfluff` config.
+
+Requires Python 3.14+ (PEP 750 t-strings).
+
+## Installation
+
+```bash
+pip install sqlfluff-tstring
+```
+
+## Usage
+
+```bash
+# Format files in-place
+sqlfluff-tstring src/
+
+# Check mode (exit 1 if changes needed, for CI)
+sqlfluff-tstring --check src/
+
+# Show diff without writing
+sqlfluff-tstring --diff src/
+
+# Override SQL dialect
+sqlfluff-tstring --dialect postgres src/
+
+# Use a specific .sqlfluff config file
+sqlfluff-tstring --config path/to/.sqlfluff src/
+```
+
+## What it does
+
+Given a file like:
+
+```python
+from sql_tstring import sql
+
+query = sql(t"select   *   from   users   where   id = {uid}   and   name = {name}")
+```
+
+Running `sqlfluff-tstring` produces:
+
+```python
+from sql_tstring import sql
+
+query = sql(t"""
+select * from users
+where id = {uid} and name = {name}
+""")
+```
+
+- Interpolations (`{uid}`, `{name!r}`, `{val:.2f}`) are preserved through formatting
+- Single quotes auto-upgrade to triple quotes when sqlfluff introduces newlines
+- Multiline content in triple-quoted t-strings is wrapped with leading/trailing newlines
+- Supports `sql(t"...")` and `obj.sql(t"...")` call patterns
+- Respects your `.sqlfluff` configuration for dialect and rules
+
+## CLI options
+
+```
+sqlfluff-tstring [OPTIONS] [PATHS...]
+
+positional arguments:
+  paths              Files or directories to format (default: .)
+
+options:
+  --check            Exit 1 if changes needed (CI mode)
+  --diff             Show diff, don't write changes
+  --config PATH      Path to .sqlfluff config file
+  --dialect DIALECT  Override SQL dialect
+  -v, --verbose      Show unchanged files
+  -q, --quiet        Suppress all output
+```
+
+Exit codes: `0` = success/no changes, `1` = changes needed (check mode).
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check src/ tests/
+uv run ty check src/
+```

sqlfluff_tstring-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+build-backend = "uv_build"
+requires = [ "uv-build>=0.7.5,<0.8" ]
+
+[project]
+name = "sqlfluff-tstring"
+version = "0.1.0"
+description = "Auto-format SQL inside Python t-strings using sqlfluff"
+readme = "README.md"
+keywords = [ "formatter", "linter", "sql", "sqlfluff", "t-string" ]
+license = "MIT"
+authors = [ { name = "Krzysztof Żuraw" } ]
+requires-python = ">=3.14"
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [ "sqlfluff>=4.0.4" ]
+
+urls.Homepage = "https://github.com/kzuraw/sqlfluff-tstring"
+urls.Issues = "https://github.com/kzuraw/sqlfluff-tstring/issues"
+urls.Repository = "https://github.com/kzuraw/sqlfluff-tstring"
+scripts.sqlfluff-tstring = "sqlfluff_tstring.cli:main"
+
+[dependency-groups]
+dev = [
+  "pre-commit>=4.5.1",
+  "pytest>=9.0.2",
+  "ruff>=0.15.5",
+  "syrupy>=5.1",
+  "ty>=0.0.21",
+]
+
+[tool.uv]
+required-version = ">=0.10.7"
+
+[tool.uv.build-backend]
+module-name = "sqlfluff_tstring"
+
+[tool.ruff]
+extend-exclude = [ "tests/fixtures" ]
+
+[tool.ty.src]
+exclude = [ "tests/fixtures" ]

sqlfluff_tstring-0.1.0/src/sqlfluff_tstring/__main__.py

@@ -0,0 +1,8 @@
+import sys
+
+from sqlfluff_tstring.cli import main
+
+try:
+    main()
+except KeyboardInterrupt:
+    sys.exit(130)

sqlfluff_tstring-0.1.0/src/sqlfluff_tstring/cli.py

@@ -0,0 +1,82 @@
+import argparse
+import difflib
+import sys
+from pathlib import Path
+
+from sqlfluff_tstring.pipeline import process_file
+
+SKIP_DIRS = {"__pycache__", ".venv", ".git", "node_modules", ".tox", ".mypy_cache"}
+
+
+def _collect_files(paths: list[Path]) -> list[Path]:
+    files: list[Path] = []
+    for path in paths:
+        if not path.exists():
+            print(f"Error: path not found: {path}", file=sys.stderr)
+            sys.exit(2)
+        if path.is_file():
+            if path.suffix == ".py":
+                files.append(path)
+            else:
+                print(f"Warning: skipping non-Python file: {path}", file=sys.stderr)
+        elif path.is_dir():
+            for py_file in sorted(path.rglob("*.py")):
+                if not any(part in SKIP_DIRS for part in py_file.parts):
+                    files.append(py_file)
+    return files
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="sqlfluff-tstring",
+        description="Format SQL inside Python t-strings using sqlfluff",
+    )
+    parser.add_argument("paths", nargs="*", type=Path, default=[Path(".")])
+    parser.add_argument(
+        "--check", action="store_true", help="Exit 1 if changes needed (CI mode)"
+    )
+    parser.add_argument(
+        "--diff", action="store_true", help="Show diff, don't write changes"
+    )
+    parser.add_argument("--config", help="Path to .sqlfluff config file")
+    parser.add_argument("--dialect", help="Override SQL dialect")
+    parser.add_argument("-v", "--verbose", action="store_true")
+    parser.add_argument("-q", "--quiet", action="store_true")
+
+    args = parser.parse_args(argv)
+    check_only = args.check or args.diff
+
+    files = _collect_files(args.paths)
+    if not files and not args.quiet:
+        print("No Python files found.", file=sys.stderr)
+        sys.exit(0)
+
+    any_changed = False
+    for path in files:
+        result = process_file(
+            path, check_only=check_only, dialect=args.dialect, config_path=args.config
+        )
+
+        if result.changed:
+            any_changed = True
+            if not args.quiet:
+                print(f"{'Would reformat' if check_only else 'Reformatted'}: {path}")
+
+            if args.diff:
+                diff = difflib.unified_diff(
+                    result.original.splitlines(keepends=True),
+                    result.formatted.splitlines(keepends=True),
+                    fromfile=str(path),
+                    tofile=str(path),
+                )
+                sys.stdout.writelines(diff)
+
+        elif args.verbose and not args.quiet:
+            print(f"Unchanged: {path}")
+
+        for error in result.errors:
+            if not args.quiet:
+                print(f"Warning: {error}", file=sys.stderr)
+
+    if args.check and any_changed:
+        sys.exit(1)

sqlfluff_tstring-0.1.0/src/sqlfluff_tstring/extractor.py

@@ -0,0 +1,82 @@
+import ast
+from dataclasses import dataclass
+from typing import cast
+
+
+@dataclass
+class PlaceholderMapping:
+    index: int
+    placeholder: str
+    original_expr: str
+    conversion: int
+    format_spec: str | None
+
+
+def extract_sql(
+    tstring_node: ast.TemplateStr,
+) -> tuple[str, list[PlaceholderMapping]]:
+    sql_parts: list[str] = []
+    mappings: list[PlaceholderMapping] = []
+    placeholder_index = 0
+
+    for value in tstring_node.values:
+        if isinstance(value, ast.Constant):
+            sql_parts.append(cast(str, value.value))
+        elif isinstance(value, ast.Interpolation):
+            placeholder = f"{{_var{placeholder_index}}}"
+            sql_parts.append(placeholder)
+
+            format_spec: str | None = None
+            if value.format_spec is not None:
+                # format_spec is a JoinedStr with Constant values
+                spec_parts: list[str] = []
+                for part in cast(ast.JoinedStr, value.format_spec).values:
+                    if isinstance(part, ast.Constant):
+                        spec_parts.append(cast(str, part.value))
+                format_spec = "".join(spec_parts)
+
+            mappings.append(
+                PlaceholderMapping(
+                    index=placeholder_index,
+                    placeholder=placeholder,
+                    original_expr=value.str,
+                    conversion=value.conversion,
+                    format_spec=format_spec,
+                )
+            )
+            placeholder_index += 1
+
+    return "".join(sql_parts), mappings
+
+
+def build_context(mappings: list[PlaceholderMapping]) -> dict[str, str]:
+    return {f"_var{m.index}": f"SQLFLUFF_VAR_{m.index}" for m in mappings}
+
+
+def restore_interpolations(
+    formatted_sql: str, mappings: list[PlaceholderMapping]
+) -> str:
+    result = formatted_sql
+    for mapping in mappings:
+        expr = mapping.original_expr
+        suffix = ""
+        if mapping.conversion != -1:
+            suffix += f"!{chr(mapping.conversion)}"
+        if mapping.format_spec is not None:
+            suffix += f":{mapping.format_spec}"
+        replacement = "{" + expr + suffix + "}"
+        count = result.count(mapping.placeholder)
+        if count == 0:
+            raise ValueError(
+                f"Placeholder {mapping.placeholder} not found in formatted SQL. "
+                f"sqlfluff may have removed or restructured the placeholder. "
+                f"Original expression: {mapping.original_expr}"
+            )
+        if count > 1:
+            raise ValueError(
+                f"Placeholder {mapping.placeholder} appears {count} times in formatted SQL. "
+                f"sqlfluff may have duplicated the placeholder. "
+                f"Original expression: {mapping.original_expr}"
+            )
+        result = result.replace(mapping.placeholder, replacement)
+    return result

sqlfluff_tstring-0.1.0/src/sqlfluff_tstring/finder.py

@@ -0,0 +1,35 @@
+import ast
+from dataclasses import dataclass
+
+
+@dataclass
+class SqlTStringMatch:
+    tstring_node: ast.TemplateStr
+    call_node: ast.Call
+
+
+class SqlTStringFinder(ast.NodeVisitor):
+    def __init__(self) -> None:
+        self.matches: list[SqlTStringMatch] = []
+
+    def visit_Call(self, node: ast.Call) -> None:
+        if self._is_sql_call(node) and node.args:
+            first_arg = node.args[0]
+            if isinstance(first_arg, ast.TemplateStr):
+                self.matches.append(SqlTStringMatch(first_arg, node))
+        self.generic_visit(node)
+
+    def _is_sql_call(self, node: ast.Call) -> bool:
+        func = node.func
+        if isinstance(func, ast.Name) and func.id == "sql":
+            return True
+        if isinstance(func, ast.Attribute) and func.attr == "sql":
+            return True
+        return False
+
+
+def find_sql_tstrings(source: str) -> list[SqlTStringMatch]:
+    tree = ast.parse(source)
+    finder = SqlTStringFinder()
+    finder.visit(tree)
+    return finder.matches

sqlfluff_tstring-0.1.0/src/sqlfluff_tstring/formatter.py

@@ -0,0 +1,21 @@
+import sqlfluff
+from sqlfluff.core import FluffConfig
+
+
+def format_sql(
+    sql: str,
+    config_path: str | None = None,
+    dialect: str | None = None,
+    context: dict[str, str] | None = None,
+) -> str:
+    overrides = {"templater": "python", "dialect": dialect or "ansi"}
+
+    config = FluffConfig(
+        extra_config_path=config_path,
+        overrides=overrides,
+        configs={"templater": {"python": {"context": context or {}}}},
+        require_dialect=False,
+    )
+
+    result = sqlfluff.fix(sql, config=config)
+    return result.rstrip("\n")

sqlfluff_tstring-0.1.0/src/sqlfluff_tstring/pipeline.py

@@ -0,0 +1,87 @@
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from sqlfluff.core.errors import SQLBaseError, SQLFluffSkipFile
+
+from sqlfluff_tstring.extractor import (
+    build_context,
+    extract_sql,
+    restore_interpolations,
+)
+from sqlfluff_tstring.finder import find_sql_tstrings
+from sqlfluff_tstring.formatter import format_sql
+from sqlfluff_tstring.rewriter import Replacement, apply_replacements
+
+
+@dataclass
+class FileResult:
+    path: Path
+    original: str = ""
+    formatted: str = ""
+    errors: list[str] = field(default_factory=list)
+
+    @property
+    def changed(self) -> bool:
+        return self.original != self.formatted
+
+
+def process_file(
+    path: Path,
+    check_only: bool = False,
+    dialect: str | None = None,
+    config_path: str | None = None,
+) -> FileResult:
+    try:
+        source = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as e:
+        return FileResult(path=path, errors=[f"Could not read {path}: {e}"])
+
+    result = FileResult(path=path, original=source, formatted=source)
+
+    try:
+        matches = find_sql_tstrings(source)
+    except SyntaxError as e:
+        result.errors.append(f"Syntax error: {e}")
+        return result
+
+    if not matches:
+        return result
+
+    replacements: list[Replacement] = []
+    for match in matches:
+        sql, mappings = extract_sql(match.tstring_node)
+        if not sql.strip():
+            continue
+
+        context = build_context(mappings)
+        try:
+            formatted = format_sql(
+                sql, dialect=dialect, config_path=config_path, context=context
+            )
+        except (SQLBaseError, SQLFluffSkipFile) as e:
+            result.errors.append(
+                f"sqlfluff error in {path}:{match.tstring_node.lineno}: {e}"
+            )
+            continue
+
+        try:
+            restored = restore_interpolations(formatted, mappings)
+        except ValueError as e:
+            result.errors.append(
+                f"Restore error in {path}:{match.tstring_node.lineno}: {e}"
+            )
+            continue
+        replacements.append(Replacement(match.tstring_node, restored))
+
+    if replacements:
+        new_source = apply_replacements(source, replacements)
+        if new_source != source:
+            result.formatted = new_source
+            if not check_only:
+                try:
+                    path.write_text(new_source, encoding="utf-8")
+                except OSError as e:
+                    result.formatted = source
+                    result.errors.append(f"Could not write {path}: {e}")
+
+    return result

sqlfluff_tstring-0.1.0/src/sqlfluff_tstring/rewriter.py

@@ -0,0 +1,57 @@
+import ast
+from dataclasses import dataclass
+
+
+@dataclass
+class Replacement:
+    tstring_node: ast.TemplateStr
+    new_content: str
+
+
+def _detect_quote_style(source: str, tstring_node: ast.TemplateStr) -> str:
+    lines = source.splitlines(keepends=True)
+    line = lines[tstring_node.lineno - 1]
+    # Skip past any prefix characters and the 't' to find the quote
+    col = tstring_node.col_offset
+    while col < len(line) and line[col] in "rRbBtT":
+        col += 1
+    if line[col : col + 3] in ('"""', "'''"):
+        return line[col : col + 3]
+    return line[col]
+
+
+def _get_source_range(source: str, node: ast.TemplateStr) -> tuple[int, int]:
+    """Return (start_offset, end_offset) as character positions in source."""
+    lines = source.splitlines(keepends=True)
+    start = sum(len(lines[i]) for i in range(node.lineno - 1)) + node.col_offset
+    if node.end_lineno is None or node.end_col_offset is None:
+        raise ValueError(
+            f"AST node at line {node.lineno} is missing end position metadata"
+        )
+    end = sum(len(lines[i]) for i in range(node.end_lineno - 1)) + node.end_col_offset
+    return start, end
+
+
+def apply_replacements(source: str, replacements: list[Replacement]) -> str:
+    # Sort by position in reverse order so earlier replacements don't shift offsets
+    sorted_replacements = sorted(
+        replacements,
+        key=lambda r: (r.tstring_node.lineno, r.tstring_node.col_offset),
+        reverse=True,
+    )
+
+    result = source
+    for replacement in sorted_replacements:
+        start, end = _get_source_range(result, replacement.tstring_node)
+        quote = _detect_quote_style(result, replacement.tstring_node)
+        # Upgrade to triple quotes if content has newlines
+        if "\n" in replacement.new_content and len(quote) == 1:
+            quote = quote * 3
+        # Wrap multiline content with leading/trailing newlines in triple-quoted strings
+        content = replacement.new_content
+        if len(quote) == 3 and "\n" in content:
+            content = f"\n{content}\n"
+        new_tstring = f"t{quote}{content}{quote}"
+        result = result[:start] + new_tstring + result[end:]
+
+    return result