sql-glider 0.1.8__py3-none-any.whl

sqlglider/lineage/formatters.py

@@ -0,0 +1,335 @@
+"""Output formatters for lineage results."""
+
+import csv
+import json
+from io import StringIO
+from pathlib import Path
+from typing import List, Optional
+
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from sqlglider.lineage.analyzer import QueryLineageResult, QueryTablesResult
+
+
+class TextFormatter:
+    """Format lineage results as Rich tables for terminal display."""
+
+    @staticmethod
+    def format(results: List[QueryLineageResult], console: Console) -> None:
+        """
+        Format and print lineage results as Rich tables.
+
+        Creates a styled table for each query showing output columns and their sources.
+        For column-level lineage, shows Output Column and Source Column.
+        For table-level lineage, shows Output Table and Source Table.
+
+        Args:
+            results: List of QueryLineageResult objects
+            console: Rich Console instance for output
+        """
+        if not results:
+            console.print("[yellow]No lineage results found.[/yellow]")
+            return
+
+        for i, result in enumerate(results):
+            # Add spacing between tables (except for first)
+            if i > 0:
+                console.print()
+
+            # Determine column headers based on level
+            if result.level == "column":
+                output_header = "Output Column"
+                source_header = "Source Column"
+            else:
+                output_header = "Output Table"
+                source_header = "Source Table"
+
+            # Create table with query info as title
+            title = (
+                f"Query {result.metadata.query_index}: {result.metadata.query_preview}"
+            )
+            table = Table(title=title, title_style="bold")
+
+            table.add_column(output_header, style="cyan")
+            table.add_column(source_header, style="green")
+
+            # Group lineage items by output_name
+            output_groups: dict[str, list[str]] = {}
+            for item in result.lineage_items:
+                if item.output_name not in output_groups:
+                    output_groups[item.output_name] = []
+                if item.source_name:  # Skip empty sources
+                    output_groups[item.output_name].append(item.source_name)
+
+            # Add rows to table
+            row_count = 0
+            for output_name in sorted(output_groups.keys()):
+                sources = sorted(output_groups[output_name])
+                if sources:
+                    # First source gets the output name
+                    table.add_row(output_name, sources[0])
+                    row_count += 1
+                    # Additional sources get empty output column
+                    for source in sources[1:]:
+                        table.add_row("", source)
+                        row_count += 1
+                else:
+                    # No sources found for this output
+                    table.add_row(output_name, Text("(no sources)", style="dim"))
+                    row_count += 1
+
+            console.print(table)
+            console.print(f"[dim]Total: {row_count} row(s)[/dim]")
+
+
+class JsonFormatter:
+    """Format lineage results as JSON."""
+
+    @staticmethod
+    def format(results: List[QueryLineageResult]) -> str:
+        """
+        Format lineage results as JSON.
+
+        Output format:
+        {
+          "queries": [
+            {
+              "query_index": 0,
+              "query_preview": "SELECT ...",
+              "level": "column",
+              "lineage": [
+                {"output_name": "table.col_a", "source_name": "src.col_x"},
+                {"output_name": "table.col_a", "source_name": "src.col_y"}
+              ]
+            }
+          ]
+        }
+
+        Args:
+            results: List of QueryLineageResult objects
+
+        Returns:
+            JSON-formatted string
+        """
+        queries = []
+        for result in results:
+            query_data = {
+                "query_index": result.metadata.query_index,
+                "query_preview": result.metadata.query_preview,
+                "level": result.level,
+                "lineage": [
+                    {
+                        "output_name": item.output_name,
+                        "source_name": item.source_name,
+                    }
+                    for item in result.lineage_items
+                ],
+            }
+            queries.append(query_data)
+
+        return json.dumps({"queries": queries}, indent=2)
+
+
+class CsvFormatter:
+    """Format lineage results as CSV."""
+
+    @staticmethod
+    def format(results: List[QueryLineageResult]) -> str:
+        """
+        Format lineage results as CSV.
+
+        Column-level output format:
+        query_index,output_column,source_column
+        0,table.column_a,source_table.column_x
+        0,table.column_a,source_table.column_y
+        0,table.column_b,source_table2.column_z
+
+        Table-level output format:
+        query_index,output_table,source_table
+        0,query_result,customers
+        0,query_result,orders
+
+        Args:
+            results: List of QueryLineageResult objects
+
+        Returns:
+            CSV-formatted string
+        """
+        if not results:
+            return ""
+
+        output = StringIO()
+
+        # Determine column headers based on level
+        level = results[0].level if results else "column"
+
+        if level == "column":
+            headers = ["query_index", "output_column", "source_column"]
+        else:  # table
+            headers = ["query_index", "output_table", "source_table"]
+
+        writer = csv.writer(output)
+        writer.writerow(headers)
+
+        # Write data rows
+        for result in results:
+            query_index = result.metadata.query_index
+            for item in result.lineage_items:
+                writer.writerow([query_index, item.output_name, item.source_name])
+
+        return output.getvalue()
+
+
+class OutputWriter:
+    """Write formatted output to file or stdout."""
+
+    @staticmethod
+    def write(content: str, output_file: Optional[Path] = None) -> None:
+        """
+        Write content to file or stdout.
+
+        Args:
+            content: The content to write
+            output_file: Optional file path. If None, writes to stdout.
+        """
+        if output_file:
+            output_file.write_text(content, encoding="utf-8")
+        else:
+            print(content)
+
+
+class TableTextFormatter:
+    """Format table analysis results as Rich tables for terminal display."""
+
+    @staticmethod
+    def format(results: List[QueryTablesResult], console: Console) -> None:
+        """
+        Format and print table analysis results as Rich tables.
+
+        Creates a styled table for each query showing table names, usage, and types.
+
+        Args:
+            results: List of QueryTablesResult objects
+            console: Rich Console instance for output
+        """
+        if not results:
+            console.print("[yellow]No tables found.[/yellow]")
+            return
+
+        for i, result in enumerate(results):
+            # Add spacing between tables (except for first)
+            if i > 0:
+                console.print()
+
+            # Create table with query info as title
+            title = (
+                f"Query {result.metadata.query_index}: {result.metadata.query_preview}"
+            )
+            table = Table(title=title, title_style="bold")
+
+            table.add_column("Table Name", style="cyan")
+            table.add_column("Usage", style="green")
+            table.add_column("Type", style="yellow")
+
+            # Add rows
+            for table_info in result.tables:
+                table.add_row(
+                    table_info.name,
+                    table_info.usage.value,
+                    table_info.object_type.value,
+                )
+
+            console.print(table)
+            console.print(f"[dim]Total: {len(result.tables)} table(s)[/dim]")
+
+
+class TableJsonFormatter:
+    """Format table analysis results as JSON."""
+
+    @staticmethod
+    def format(results: List[QueryTablesResult]) -> str:
+        """
+        Format table analysis results as JSON.
+
+        Output format:
+        {
+          "queries": [
+            {
+              "query_index": 0,
+              "query_preview": "SELECT ...",
+              "tables": [
+                {"name": "schema.table", "usage": "INPUT", "object_type": "UNKNOWN"}
+              ]
+            }
+          ]
+        }
+
+        Args:
+            results: List of QueryTablesResult objects
+
+        Returns:
+            JSON-formatted string
+        """
+        queries = []
+        for result in results:
+            query_data = {
+                "query_index": result.metadata.query_index,
+                "query_preview": result.metadata.query_preview,
+                "tables": [
+                    {
+                        "name": table_info.name,
+                        "usage": table_info.usage.value,
+                        "object_type": table_info.object_type.value,
+                    }
+                    for table_info in result.tables
+                ],
+            }
+            queries.append(query_data)
+
+        return json.dumps({"queries": queries}, indent=2)
+
+
+class TableCsvFormatter:
+    """Format table analysis results as CSV."""
+
+    @staticmethod
+    def format(results: List[QueryTablesResult]) -> str:
+        """
+        Format table analysis results as CSV.
+
+        Output format:
+        query_index,table_name,usage,object_type
+        0,schema.table,INPUT,UNKNOWN
+        0,schema.other_table,OUTPUT,TABLE
+
+        Args:
+            results: List of QueryTablesResult objects
+
+        Returns:
+            CSV-formatted string
+        """
+        if not results:
+            return ""
+
+        output = StringIO()
+        headers = ["query_index", "table_name", "usage", "object_type"]
+
+        writer = csv.writer(output)
+        writer.writerow(headers)
+
+        # Write data rows
+        for result in results:
+            query_index = result.metadata.query_index
+            for table_info in result.tables:
+                writer.writerow(
+                    [
+                        query_index,
+                        table_info.name,
+                        table_info.usage.value,
+                        table_info.object_type.value,
+                    ]
+                )
+
+        return output.getvalue()

sqlglider/templating/__init__.py

@@ -0,0 +1,51 @@
+"""SQL templating system for SQL Glider.
+
+This package provides a plugin-based templating system for processing
+SQL templates before analysis. It supports multiple templating engines
+through a plugin architecture based on Python entry points.
+
+Built-in templaters:
+- `none`: No-op templater that passes SQL through unchanged
+- `jinja`: Jinja2-based templater with full template syntax support
+
+Example:
+    >>> from sqlglider.templating import get_templater
+    >>> templater = get_templater("jinja")
+    >>> sql = "SELECT * FROM {{ schema }}.{{ table }}"
+    >>> rendered = templater.render(sql, {"schema": "public", "table": "users"})
+    >>> print(rendered)
+    SELECT * FROM public.users
+"""
+
+from sqlglider.templating.base import NoOpTemplater, Templater, TemplaterError
+from sqlglider.templating.registry import (
+    clear_registry,
+    get_templater,
+    list_templaters,
+    register_templater,
+)
+from sqlglider.templating.variables import (
+    load_all_variables,
+    load_env_variables,
+    load_variables_file,
+    merge_variables,
+    parse_cli_variables,
+)
+
+__all__ = [
+    # Base classes
+    "Templater",
+    "TemplaterError",
+    "NoOpTemplater",
+    # Registry functions
+    "get_templater",
+    "list_templaters",
+    "register_templater",
+    "clear_registry",
+    # Variable loading
+    "load_all_variables",
+    "load_variables_file",
+    "parse_cli_variables",
+    "load_env_variables",
+    "merge_variables",
+]

sqlglider/templating/base.py

@@ -0,0 +1,103 @@
+"""Base classes for SQL templating system.
+
+This module defines the abstract interface for templaters and provides
+a no-op implementation that passes SQL through unchanged.
+"""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+class TemplaterError(Exception):
+    """Exception raised when templating fails."""
+
+    pass
+
+
+class Templater(ABC):
+    """Abstract base class for SQL templaters.
+
+    All templater implementations must inherit from this class and implement
+    the required methods. Templaters are discovered via entry points and
+    can be used to process SQL files before analysis.
+
+    Example:
+        >>> class MyTemplater(Templater):
+        ...     @property
+        ...     def name(self) -> str:
+        ...         return "my-templater"
+        ...
+        ...     def render(self, sql, variables=None, source_path=None):
+        ...         # Custom templating logic
+        ...         return processed_sql
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return the templater name.
+
+        This name is used to identify the templater in configuration
+        and CLI options.
+
+        Returns:
+            The unique name of this templater.
+        """
+        pass
+
+    @abstractmethod
+    def render(
+        self,
+        sql: str,
+        variables: Optional[Dict[str, Any]] = None,
+        source_path: Optional[Path] = None,
+    ) -> str:
+        """Render a SQL template string.
+
+        Args:
+            sql: The SQL template string to render.
+            variables: Template variables to substitute. Keys are variable
+                      names, values can be any type supported by the templater.
+            source_path: Optional path to the source file. Used for resolving
+                        relative paths in includes/extends directives.
+
+        Returns:
+            The rendered SQL string with all template expressions evaluated.
+
+        Raises:
+            TemplaterError: If templating fails due to syntax errors,
+                           missing variables, or other issues.
+        """
+        pass
+
+
+class NoOpTemplater(Templater):
+    """A templater that passes SQL through unchanged.
+
+    This is the default templater when no templating is needed.
+    It simply returns the input SQL without any processing.
+    """
+
+    @property
+    def name(self) -> str:
+        """Return the templater name."""
+        return "none"
+
+    def render(
+        self,
+        sql: str,
+        variables: Optional[Dict[str, Any]] = None,
+        source_path: Optional[Path] = None,
+    ) -> str:
+        """Pass SQL through unchanged.
+
+        Args:
+            sql: The SQL string.
+            variables: Ignored for no-op templater.
+            source_path: Ignored for no-op templater.
+
+        Returns:
+            The input SQL unchanged.
+        """
+        return sql

sqlglider/templating/jinja.py

@@ -0,0 +1,163 @@
+"""Jinja2-based SQL templater.
+
+This module provides a Jinja2 implementation of the Templater interface,
+supporting full Jinja2 template syntax including variables, conditionals,
+loops, and includes.
+"""
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from jinja2 import (
+    BaseLoader,
+    Environment,
+    StrictUndefined,
+    TemplateError,
+    TemplateNotFound,
+    UndefinedError,
+)
+
+from sqlglider.templating.base import Templater, TemplaterError
+
+
+class RelativeFileSystemLoader(BaseLoader):
+    """A Jinja2 loader that resolves paths relative to the source file.
+
+    This loader allows templates to include other templates using paths
+    relative to the including file's location.
+    """
+
+    def __init__(self, base_path: Optional[Path] = None):
+        """Initialize the loader.
+
+        Args:
+            base_path: The base path for resolving relative includes.
+                      If None, includes will not work.
+        """
+        self.base_path = base_path
+
+    def get_source(self, environment, template):
+        """Load a template from the file system.
+
+        Args:
+            environment: The Jinja2 environment.
+            template: The template name/path to load.
+
+        Returns:
+            A tuple of (source, filename, uptodate_func).
+
+        Raises:
+            TemplateNotFound: If the template cannot be found.
+        """
+        if self.base_path is None:
+            raise TemplateNotFound(template)
+
+        # Resolve the template path relative to base_path
+        template_path = self.base_path / template
+
+        if not template_path.exists():
+            raise TemplateNotFound(template)
+
+        try:
+            source = template_path.read_text(encoding="utf-8")
+            # Return source, filename, and a function that returns whether
+            # the template is still up to date
+            return source, str(template_path), lambda: True
+        except (OSError, IOError) as e:
+            raise TemplateNotFound(template) from e
+
+
+class JinjaTemplater(Templater):
+    """Jinja2-based SQL templater.
+
+    Supports the full Jinja2 template syntax:
+    - Variable substitution: {{ variable }}
+    - Conditionals: {% if condition %}...{% endif %}
+    - Loops: {% for item in items %}...{% endfor %}
+    - Includes: {% include 'other.sql' %}
+    - Filters: {{ value | upper }}
+    - Comments: {# comment #}
+
+    Example:
+        >>> templater = JinjaTemplater()
+        >>> sql = '''
+        ... SELECT
+        ...     {{ column }},
+        ...     {% if include_total %}SUM(amount) as total{% endif %}
+        ... FROM {{ schema }}.{{ table }}
+        ... {% if conditions %}WHERE {{ conditions }}{% endif %}
+        ... '''
+        >>> variables = {
+        ...     "column": "customer_id",
+        ...     "include_total": True,
+        ...     "schema": "sales",
+        ...     "table": "orders",
+        ...     "conditions": "status = 'active'"
+        ... }
+        >>> print(templater.render(sql, variables))
+    """
+
+    @property
+    def name(self) -> str:
+        """Return the templater name."""
+        return "jinja"
+
+    def render(
+        self,
+        sql: str,
+        variables: Optional[Dict[str, Any]] = None,
+        source_path: Optional[Path] = None,
+    ) -> str:
+        """Render a SQL template using Jinja2.
+
+        Args:
+            sql: The SQL template string with Jinja2 syntax.
+            variables: Template variables to substitute. If None, an empty
+                      dict is used.
+            source_path: Optional path to the source file. If provided,
+                        enables {% include %} directives relative to this path.
+
+        Returns:
+            The rendered SQL string.
+
+        Raises:
+            TemplaterError: If the template has syntax errors or references
+                           undefined variables.
+        """
+        variables = variables or {}
+
+        # Set up the Jinja2 environment
+        if source_path is not None:
+            # Use a loader that resolves includes relative to the source file
+            base_path = source_path.parent if source_path.is_file() else source_path
+            loader = RelativeFileSystemLoader(base_path)
+        else:
+            loader = None
+
+        env = Environment(
+            loader=loader,
+            # Keep whitespace to preserve SQL formatting
+            trim_blocks=False,
+            lstrip_blocks=False,
+            # Enable autoescape for safety (though less relevant for SQL)
+            autoescape=False,
+            # Undefined variables should raise an error by default
+            undefined=StrictUndefined,
+        )
+
+        try:
+            # Compile and render the template
+            template = env.from_string(sql)
+            return template.render(**variables)
+
+        except UndefinedError as e:
+            raise TemplaterError(f"Undefined variable in template: {e}") from e
+
+        except TemplateNotFound as e:
+            raise TemplaterError(f"Template include not found: {e}") from e
+
+        except TemplateError as e:
+            raise TemplaterError(f"Template error: {e}") from e
+
+        except Exception as e:
+            raise TemplaterError(f"Failed to render template: {e}") from e