sql-glider 0.1.2__py3-none-any.whl

sqlglider/templating/registry.py

@@ -0,0 +1,124 @@
+"""Templater registry with plugin discovery via entry points.
+
+This module handles discovering and instantiating templaters from
+Python entry points, allowing third-party packages to register
+custom templaters.
+"""
+
+import sys
+from typing import Dict, List, Type
+
+from sqlglider.templating.base import Templater, TemplaterError
+
+# Cache for discovered templaters
+_templater_cache: Dict[str, Type[Templater]] = {}
+_discovery_done: bool = False
+
+
+def _discover_templaters() -> None:
+    """Discover templaters from entry points.
+
+    Uses importlib.metadata to find all registered templaters
+    in the 'sqlglider.templaters' entry point group.
+    """
+    global _discovery_done, _templater_cache
+
+    if _discovery_done:
+        return
+
+    if sys.version_info >= (3, 10):
+        from importlib.metadata import entry_points
+
+        eps = entry_points(group="sqlglider.templaters")
+    else:
+        from importlib.metadata import entry_points
+
+        all_eps = entry_points()
+        eps = all_eps.get("sqlglider.templaters", [])
+
+    for ep in eps:
+        try:
+            templater_class = ep.load()
+            if isinstance(templater_class, type) and issubclass(
+                templater_class, Templater
+            ):
+                _templater_cache[ep.name] = templater_class
+        except Exception:
+            # Skip templaters that fail to load
+            # This allows graceful handling of missing optional dependencies
+            pass
+
+    _discovery_done = True
+
+
+def get_templater(name: str) -> Templater:
+    """Get a templater instance by name.
+
+    Args:
+        name: The name of the templater (e.g., "jinja", "none").
+
+    Returns:
+        An instance of the requested templater.
+
+    Raises:
+        TemplaterError: If the templater is not found.
+
+    Example:
+        >>> templater = get_templater("jinja")
+        >>> rendered = templater.render("SELECT * FROM {{ table }}", {"table": "users"})
+    """
+    _discover_templaters()
+
+    if name not in _templater_cache:
+        available = ", ".join(sorted(_templater_cache.keys()))
+        raise TemplaterError(
+            f"Unknown templater '{name}'. Available templaters: {available or 'none'}"
+        )
+
+    return _templater_cache[name]()
+
+
+def list_templaters() -> List[str]:
+    """List all available templater names.
+
+    Returns:
+        A sorted list of available templater names.
+
+    Example:
+        >>> templaters = list_templaters()
+        >>> print(templaters)
+        ['jinja', 'none']
+    """
+    _discover_templaters()
+    return sorted(_templater_cache.keys())
+
+
+def register_templater(name: str, templater_class: Type[Templater]) -> None:
+    """Register a templater programmatically.
+
+    This is primarily useful for testing or for registering templaters
+    that aren't installed via entry points.
+
+    Args:
+        name: The name to register the templater under.
+        templater_class: The templater class to register.
+
+    Raises:
+        ValueError: If templater_class is not a subclass of Templater.
+    """
+    if not isinstance(templater_class, type) or not issubclass(
+        templater_class, Templater
+    ):
+        raise ValueError(f"{templater_class} must be a subclass of Templater")
+
+    _templater_cache[name] = templater_class
+
+
+def clear_registry() -> None:
+    """Clear the templater registry.
+
+    This is primarily useful for testing.
+    """
+    global _discovery_done, _templater_cache
+    _templater_cache.clear()
+    _discovery_done = False

sqlglider/templating/variables.py

@@ -0,0 +1,295 @@
+"""Variable loading utilities for SQL templating.
+
+This module provides functions for loading template variables from
+multiple sources with a defined priority order:
+1. CLI arguments (highest priority)
+2. Variables file (JSON/YAML/TOML)
+3. Config file inline variables
+4. Environment variables (lowest priority)
+"""
+
+import json
+import os
+import tomllib
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from rich.console import Console
+
+console = Console(stderr=True)
+
+
+def load_variables_file(path: Path) -> Dict[str, Any]:
+    """Load variables from a JSON, YAML, or TOML file.
+
+    Args:
+        path: Path to the variables file. Must have .json, .yaml, .yml, or .toml extension.
+
+    Returns:
+        A dictionary of variables loaded from the file.
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        ValueError: If the file format is not supported or cannot be parsed.
+    """
+    if not path.exists():
+        raise FileNotFoundError(f"Variables file not found: {path}")
+
+    suffix = path.suffix.lower()
+
+    if suffix == ".json":
+        return _load_json_file(path)
+    elif suffix in (".yaml", ".yml"):
+        return _load_yaml_file(path)
+    elif suffix == ".toml":
+        return _load_toml_file(path)
+    else:
+        raise ValueError(
+            f"Unsupported variables file format: {suffix}. "
+            "Use .json, .yaml, .yml, or .toml"
+        )
+
+
+def _load_json_file(path: Path) -> Dict[str, Any]:
+    """Load variables from a JSON file."""
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        if not isinstance(data, dict):
+            raise ValueError(
+                f"Variables file {path} must contain a JSON object, "
+                f"got {type(data).__name__}"
+            )
+
+        return data
+
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Invalid JSON in {path}: {e}") from e
+
+
+def _load_yaml_file(path: Path) -> Dict[str, Any]:
+    """Load variables from a YAML file.
+
+    Requires PyYAML to be installed.
+    """
+    try:
+        import yaml
+    except ImportError:
+        raise ValueError(
+            f"Cannot load YAML file {path}: PyYAML is not installed. "
+            "Install it with: uv add pyyaml"
+        )
+
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+
+        if data is None:
+            return {}
+
+        if not isinstance(data, dict):
+            raise ValueError(
+                f"Variables file {path} must contain a YAML mapping, "
+                f"got {type(data).__name__}"
+            )
+
+        return data
+
+    except yaml.YAMLError as e:
+        raise ValueError(f"Invalid YAML in {path}: {e}") from e
+
+
+def _load_toml_file(path: Path) -> Dict[str, Any]:
+    """Load variables from a TOML file.
+
+    Uses Python 3.11+ built-in tomllib.
+    """
+    try:
+        with open(path, "rb") as f:
+            data = tomllib.load(f)
+
+        if not isinstance(data, dict):
+            raise ValueError(
+                f"Variables file {path} must contain a TOML table, "
+                f"got {type(data).__name__}"
+            )
+
+        return data
+
+    except tomllib.TOMLDecodeError as e:
+        raise ValueError(f"Invalid TOML in {path}: {e}") from e
+
+
+def parse_cli_variables(var_args: Optional[List[str]]) -> Dict[str, Any]:
+    """Parse CLI variable arguments in key=value format.
+
+    Supports basic type inference:
+    - Integers: 123
+    - Floats: 12.34
+    - Booleans: true, false (case-insensitive)
+    - Strings: everything else
+
+    Args:
+        var_args: List of variable strings in "key=value" format.
+
+    Returns:
+        A dictionary of parsed variables.
+
+    Raises:
+        ValueError: If a variable string is not in key=value format.
+    """
+    if not var_args:
+        return {}
+
+    variables: Dict[str, Any] = {}
+
+    for var_str in var_args:
+        if "=" not in var_str:
+            raise ValueError(
+                f"Invalid variable format: '{var_str}'. Expected 'key=value'"
+            )
+
+        key, value = var_str.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+
+        if not key:
+            raise ValueError(f"Empty variable name in: '{var_str}'")
+
+        variables[key] = _infer_type(value)
+
+    return variables
+
+
+def _infer_type(value: str) -> Any:
+    """Infer the type of a string value.
+
+    Args:
+        value: The string value to parse.
+
+    Returns:
+        The value converted to the inferred type.
+    """
+    # Check for boolean
+    if value.lower() == "true":
+        return True
+    if value.lower() == "false":
+        return False
+
+    # Check for integer
+    try:
+        return int(value)
+    except ValueError:
+        pass
+
+    # Check for float
+    try:
+        return float(value)
+    except ValueError:
+        pass
+
+    # Default to string
+    return value
+
+
+def load_env_variables(prefix: str = "SQLGLIDER_VAR_") -> Dict[str, Any]:
+    """Load variables from environment variables.
+
+    Environment variables with the specified prefix are loaded and the
+    prefix is stripped from the key. For example, SQLGLIDER_VAR_SCHEMA
+    becomes the variable "schema" (lowercased).
+
+    Args:
+        prefix: The prefix to look for in environment variable names.
+
+    Returns:
+        A dictionary of variables from environment variables.
+    """
+    variables: Dict[str, Any] = {}
+
+    for key, value in os.environ.items():
+        if key.startswith(prefix):
+            # Remove prefix and lowercase the key
+            var_name = key[len(prefix) :].lower()
+            if var_name:
+                variables[var_name] = _infer_type(value)
+
+    return variables
+
+
+def merge_variables(*sources: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    """Merge variables from multiple sources with priority.
+
+    Later sources in the argument list have higher priority and will
+    override values from earlier sources.
+
+    Args:
+        *sources: Variable dictionaries to merge, from lowest to highest priority.
+                 None values are skipped.
+
+    Returns:
+        A merged dictionary of variables.
+
+    Example:
+        >>> env_vars = {"schema": "default", "table": "users"}
+        >>> config_vars = {"schema": "config_schema"}
+        >>> cli_vars = {"schema": "cli_schema", "column": "id"}
+        >>> merged = merge_variables(env_vars, config_vars, cli_vars)
+        >>> print(merged)
+        {"schema": "cli_schema", "table": "users", "column": "id"}
+    """
+    result: Dict[str, Any] = {}
+
+    for source in sources:
+        if source is not None:
+            result.update(source)
+
+    return result
+
+
+def load_all_variables(
+    cli_vars: Optional[List[str]] = None,
+    vars_file: Optional[Path] = None,
+    config_vars: Optional[Dict[str, Any]] = None,
+    use_env: bool = True,
+) -> Dict[str, Any]:
+    """Load and merge variables from all sources.
+
+    Priority order (highest to lowest):
+    1. CLI arguments
+    2. Variables file
+    3. Config file inline variables
+    4. Environment variables
+
+    Args:
+        cli_vars: List of CLI variable strings in "key=value" format.
+        vars_file: Path to a variables file (JSON, YAML, or TOML).
+        config_vars: Variables from the configuration file.
+        use_env: Whether to load environment variables.
+
+    Returns:
+        A merged dictionary of variables from all sources.
+    """
+    sources: List[Optional[Dict[str, Any]]] = []
+
+    # Load in priority order (lowest first)
+    if use_env:
+        sources.append(load_env_variables())
+
+    if config_vars:
+        sources.append(config_vars)
+
+    if vars_file:
+        try:
+            sources.append(load_variables_file(vars_file))
+        except (FileNotFoundError, ValueError) as e:
+            console.print(f"[yellow]Warning:[/yellow] {e}")
+
+    if cli_vars:
+        try:
+            sources.append(parse_cli_variables(cli_vars))
+        except ValueError as e:
+            console.print(f"[yellow]Warning:[/yellow] {e}")
+
+    return merge_variables(*sources)

sqlglider/utils/__init__.py

@@ -0,0 +1,11 @@
+"""Utility functions for SQL Glider."""
+
+from sqlglider.utils.config import ConfigSettings, find_config_file, load_config
+from sqlglider.utils.file_utils import read_sql_file
+
+__all__ = [
+    "ConfigSettings",
+    "find_config_file",
+    "load_config",
+    "read_sql_file",
+]

sqlglider/utils/config.py

@@ -0,0 +1,130 @@
+"""Configuration management for SQL Glider.
+
+Loads configuration from sqlglider.toml in the current working directory.
+"""
+
+import tomllib
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel
+from rich.console import Console
+
+console = Console(stderr=True)
+
+
+class TemplatingConfig(BaseModel):
+    """Configuration for the templating system.
+
+    All fields are optional.
+    """
+
+    variables_file: Optional[str] = None
+    variables: Optional[Dict[str, Any]] = None
+
+
+class ConfigSettings(BaseModel):
+    """Configuration settings for SQL Glider.
+
+    All fields are optional. None values indicate the setting was not
+    specified in the config file.
+    """
+
+    dialect: Optional[str] = None
+    level: Optional[str] = None
+    output_format: Optional[str] = None
+    templater: Optional[str] = None
+    templating: Optional[TemplatingConfig] = None
+
+
+def find_config_file(start_path: Optional[Path] = None) -> Optional[Path]:
+    """Find sqlglider.toml in the current working directory.
+
+    Args:
+        start_path: Starting directory to search for config file.
+                   Defaults to current working directory.
+
+    Returns:
+        Path to config file if found, None otherwise.
+    """
+    if start_path is None:
+        start_path = Path.cwd()
+
+    config_path = start_path / "sqlglider.toml"
+
+    if config_path.exists() and config_path.is_file():
+        return config_path
+
+    return None
+
+
+def load_config(config_path: Optional[Path] = None) -> ConfigSettings:
+    """Load configuration from sqlglider.toml.
+
+    Priority order:
+    1. Explicit config_path parameter
+    2. sqlglider.toml in current working directory
+    3. Empty ConfigSettings (all None)
+
+    Args:
+        config_path: Optional explicit path to config file.
+                    If not provided, searches current working directory.
+
+    Returns:
+        ConfigSettings with values from TOML file or None for unset fields.
+        Always returns a valid ConfigSettings object, even on errors.
+
+    Error Handling:
+        - Missing file: Returns empty ConfigSettings (silent)
+        - Malformed TOML: Warns user and returns empty ConfigSettings
+        - Invalid values: Warns user and sets affected fields to None
+        - Unknown keys: Ignored (forward compatibility)
+    """
+    # Find config file
+    if config_path is None:
+        config_path = find_config_file()
+
+    # No config file found - return empty settings
+    if config_path is None:
+        return ConfigSettings()
+
+    try:
+        # Read and parse TOML file
+        with open(config_path, "rb") as f:
+            toml_data = tomllib.load(f)
+
+        # Extract sqlglider section
+        sqlglider_config = toml_data.get("sqlglider", {})
+
+        # Validate and create ConfigSettings
+        # Pydantic will validate types and ignore unknown fields
+        try:
+            return ConfigSettings(**sqlglider_config)
+        except Exception as e:
+            console.print(
+                f"[yellow]Warning:[/yellow] Invalid configuration in {config_path}: {e}",
+            )
+            console.print("[yellow]Using default settings[/yellow]")
+            return ConfigSettings()
+
+    except tomllib.TOMLDecodeError as e:
+        console.print(
+            f"[yellow]Warning:[/yellow] Failed to parse {config_path}: {e}",
+        )
+        console.print("[yellow]Using default settings[/yellow]")
+        return ConfigSettings()
+
+    except (OSError, IOError) as e:
+        console.print(
+            f"[yellow]Warning:[/yellow] Could not read {config_path}: {e}",
+        )
+        console.print("[yellow]Using default settings[/yellow]")
+        return ConfigSettings()
+
+    except Exception as e:
+        # Catch-all for unexpected errors
+        console.print(
+            f"[yellow]Warning:[/yellow] Unexpected error loading config: {e}",
+        )
+        console.print("[yellow]Using default settings[/yellow]")
+        return ConfigSettings()

sqlglider/utils/file_utils.py

@@ -0,0 +1,38 @@
+"""File utility functions for SQL Glider."""
+
+from pathlib import Path
+
+
+def read_sql_file(file_path: Path) -> str:
+    """
+    Read a SQL file and return its contents as a string.
+
+    Args:
+        file_path: Path to the SQL file to read
+
+    Returns:
+        The contents of the SQL file as a string
+
+    Raises:
+        FileNotFoundError: If the file does not exist
+        PermissionError: If the file cannot be read
+        UnicodeDecodeError: If the file encoding is not UTF-8
+    """
+    if not file_path.exists():
+        raise FileNotFoundError(f"SQL file not found: {file_path}")
+
+    if not file_path.is_file():
+        raise ValueError(f"Path is not a file: {file_path}")
+
+    try:
+        return file_path.read_text(encoding="utf-8")
+    except PermissionError as e:
+        raise PermissionError(f"Cannot read file {file_path}: {e}") from e
+    except UnicodeDecodeError as e:
+        raise UnicodeDecodeError(
+            e.encoding,
+            e.object,
+            e.start,
+            e.end,
+            f"File {file_path} is not valid UTF-8: {e.reason}",
+        ) from e