singularitysql 0.1.0__py3-none-any.whl

singularity/__init__.py

@@ -0,0 +1,18 @@
+"""Singularity — SQL Server stored procedure introspection and Pydantic model generation."""
+
+from singularity.exceptions import SingularityError, SpNotFoundError
+from singularity.introspector import SQLServerIntrospector
+from singularity.model_generator import generate_model
+from singularity.types import ColumnInfo, Parameter, SPMetadata
+from singularity.version import ServerVersion
+
+__all__ = [
+    "SQLServerIntrospector",
+    "generate_model",
+    "SPMetadata",
+    "ColumnInfo",
+    "Parameter",
+    "ServerVersion",
+    "SingularityError",
+    "SpNotFoundError",
+]

singularity/cli/__init__.py

@@ -0,0 +1,8 @@
+"""Singularity CLI — Typer app and commands."""
+
+from singularity.cli._app import _main, app
+
+__all__ = ["app", "main"]
+
+# main is an alias for _main for entry point consistency
+main = _main

singularity/cli/_app.py

@@ -0,0 +1,25 @@
+"""Singularity Typer app instance — isolated to avoid circular imports."""
+
+import sys
+
+import typer
+
+
+def _main() -> None:
+    """Entry point with UTF-8 encoding support for Windows consoles."""
+    if sys.platform == "win32":
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+    app()
+
+
+app = typer.Typer(
+    name="singularity",
+    help="SQL Server stored procedure introspection and Pydantic model generator.",
+    no_args_is_help=True,
+    invoke_without_command=True,
+)
+
+# Register commands — import triggers @app.command() decorators
+import singularity.cli.docs_generate  # noqa: E402, F401 — registers docs command
+import singularity.cli.generate  # noqa: E402, F401 — registers generate command

singularity/cli/config.py

@@ -0,0 +1,142 @@
+"""TOML configuration loading and Pydantic config models."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, field_validator
+
+
+class ConnectionConfig(BaseModel):
+    """SQL Server connection settings."""
+
+    server: str
+    """Server hostname or IP address (required)."""
+
+    database: str
+    """Database name (required)."""
+
+    driver: str = "ODBC Driver 18 for SQL Server"
+    """ODBC driver name."""
+
+    trusted_connection: bool = True
+    """Use Windows Authentication when True."""
+
+    username: str | None = None
+    """SQL Server login username (used when trusted_connection is False)."""
+
+    password: str | None = None
+    """SQL Server login password (used when trusted_connection is False)."""
+
+    def build_connection_string(self) -> str:
+        """Build a pyodbc-compatible connection string from the config.
+
+        Returns:
+            A DRIVER=SERVER=DATABASE=... connection string.
+        """
+        parts = [
+            f"DRIVER={{{self.driver}}}",
+            f"SERVER={self.server}",
+            f"DATABASE={self.database}",
+        ]
+        if self.trusted_connection:
+            parts.append("Trusted_Connection=yes")
+        else:
+            if self.username:
+                parts.append(f"UID={self.username}")
+            if self.password:
+                parts.append(f"PWD={self.password}")
+        return ";".join(parts)
+
+
+class SpSelectionConfig(BaseModel):
+    """Stored procedure selection criteria."""
+
+    procedures: list[str] | None = None
+    """Explicit list of stored procedure names to introspect."""
+
+    pattern: str | None = None
+    """Wildcard pattern (e.g. 'usp_%') to resolve against the database."""
+
+    @field_validator("procedures", "pattern")
+    @classmethod
+    def _at_least_one(cls, v: list[str] | str | None) -> list[str] | str | None:
+        return v
+
+
+class OutputConfig(BaseModel):
+    """Output preferences for generated models."""
+
+    directory: str = "."
+    """Output directory for generated files."""
+
+    mode: Literal["dynamic", "source"] = "source"
+    """Generation mode: 'dynamic' for runtime models, 'source' for .py files."""
+
+    file_naming: str = "{sp_name}.py"
+    """File naming template with {sp_name}, {schema}, {database} variables."""
+
+    naming_convention: Literal["snake_case", "camelCase", "PascalCase"] = "snake_case"
+    """Field naming convention for generated models."""
+
+    docs_directory: str | None = None
+    """Output directory for generated Markdown documentation.
+    If set, ``singularity docs`` writes docs here. Defaults to ``docs/``."""
+
+    @field_validator("mode")
+    @classmethod
+    def _validate_mode(cls, v: str) -> str:
+        allowed = {"dynamic", "source"}
+        if v not in allowed:
+            raise ValueError(f"mode must be one of {allowed}, got '{v}'")
+        return v
+
+    @field_validator("naming_convention")
+    @classmethod
+    def _validate_convention(cls, v: str) -> str:
+        allowed = {"snake_case", "camelCase", "PascalCase"}
+        if v not in allowed:
+            raise ValueError(
+                f"naming_convention must be one of {allowed}, got '{v}'"
+            )
+        return v
+
+
+class SingularityConfig(BaseModel):
+    """Top-level configuration model."""
+
+    connection: ConnectionConfig
+    """SQL Server connection settings."""
+
+    sp_selection: SpSelectionConfig
+    """Stored procedure selection criteria."""
+
+    output: OutputConfig = OutputConfig()
+    """Output preferences (defaults apply if section omitted)."""
+
+
+def load_config(path: str | Path) -> SingularityConfig:
+    """Load and validate a TOML configuration file.
+
+    Args:
+        path: Path to the TOML config file.
+
+    Returns:
+        A validated SingularityConfig instance.
+
+    Raises:
+        FileNotFoundError: If the config file does not exist.
+        pydantic.ValidationError: If the config is invalid.
+    """
+    import tomli
+
+    path = Path(path)
+
+    if not path.exists():
+        raise FileNotFoundError(f"Config file not found: {path}")
+
+    raw = path.read_text(encoding="utf-8")
+    data = tomli.loads(raw)
+
+    return SingularityConfig(**data)

singularity/cli/docs_generate.py

@@ -0,0 +1,196 @@
+"""CLI docs command — generates Markdown documentation for stored procedures."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from singularity.cli._app import app
+from singularity.cli.config import load_config
+from singularity.introspector import SQLServerIntrospector
+from singularity.model_generator import _generate_source
+from singularity.types import SPMetadata
+
+console = Console()
+
+
+@app.command()
+def docs(
+    config: str = typer.Option(
+        ...,
+        "--config",
+        "-c",
+        help="Path to TOML configuration file.",
+    ),
+    output: str | None = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output directory for documentation. Overrides config.",
+    ),
+) -> None:
+    """Generate Markdown documentation for stored procedures.
+
+    Introspects the configured stored procedures and writes a Markdown
+    file per SP with parameter tables, result set columns, descriptions
+    (from ``sys.extended_properties``), and the generated Pydantic model
+    source code.
+    """
+    # --- Load config -------------------------------------------------------
+    cfg_path = Path(config)
+    if not cfg_path.exists():
+        console.print(f"[red]Error:[/red] Config file not found: [bold]{cfg_path}[/bold]")
+        raise typer.Exit(code=1)
+
+    try:
+        cfg = load_config(str(cfg_path))
+    except Exception as exc:
+        console.print(f"[red]Error loading config:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+    # --- Resolve output directory ------------------------------------------
+    docs_dir: Path
+    if output:
+        docs_dir = Path(output)
+    elif cfg.output.docs_directory:
+        docs_dir = Path(cfg.output.docs_directory)
+    else:
+        docs_dir = Path("docs")
+
+    docs_dir.mkdir(parents=True, exist_ok=True)
+
+    # --- Connect to SQL Server ---------------------------------------------
+    conn_str = cfg.connection.build_connection_string()
+    introspector = SQLServerIntrospector(conn_str)
+
+    try:
+        introspector.connect()
+        version = introspector.detect_version()
+        console.print(f"[green]Connected.[/green] Detected version: [bold]{version.value}[/bold]")
+    except Exception as exc:
+        console.print(f"[red]Error connecting to SQL Server:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+    # --- Resolve SPs -------------------------------------------------------
+    sp_names: list[str] = []
+
+    if cfg.sp_selection.procedures:
+        sp_names.extend(cfg.sp_selection.procedures)
+
+    if cfg.sp_selection.pattern:
+        try:
+            cursor = introspector._connection.cursor()  # type: ignore[union-attr]
+            cursor.execute(
+                """
+                SELECT ROUTINE_NAME
+                FROM INFORMATION_SCHEMA.ROUTINES
+                WHERE ROUTINE_TYPE = 'PROCEDURE'
+                  AND ROUTINE_NAME LIKE ?
+                """,
+                (cfg.sp_selection.pattern,),
+            )
+            sp_names.extend(row[0] for row in cursor.fetchall())
+        except Exception as exc:
+            console.print(
+                f"[yellow]Error resolving SP pattern '{cfg.sp_selection.pattern}':[/yellow] {exc}"
+            )
+
+    if not sp_names:
+        console.print(
+            "[yellow]No stored procedures selected.[/yellow] "
+            "Check your [bold][sp_selection][/bold] config."
+        )
+        raise typer.Exit(code=0)
+
+    # --- Generate docs -----------------------------------------------------
+    success_count = 0
+    error_count = 0
+
+    for sp_name in sp_names:
+        try:
+            meta = introspector.introspect(sp_name)
+            doc_content = _render_doc(meta)
+            doc_path = docs_dir / f"{sp_name}.md"
+            doc_path.write_text(doc_content, encoding="utf-8")
+            console.print(f"  [green]✓[/green] {sp_name} → {doc_path}")
+            success_count += 1
+        except Exception as exc:
+            console.print(f"  [red]✗[/red] {sp_name}: {exc}")
+            error_count += 1
+
+    console.print(
+        f"\nDone. [green]{success_count} docs generated[/green], "
+        f"[red]{error_count} failed[/red]."
+    )
+    if error_count > 0:
+        raise typer.Exit(code=1)
+
+
+def _render_doc(meta: SPMetadata) -> str:
+    """Render a stored procedure's documentation as Markdown.
+
+    Args:
+        meta: Fully introspected SP metadata (includes descriptions).
+
+    Returns:
+        A Markdown string suitable for writing to a .md file.
+    """
+    lines: list[str] = []
+    lines.append(f"# {meta.name}")
+    lines.append("")
+
+    # Schema
+    schema = meta.name.split(".")[0] if "." in meta.name else "dbo"
+    lines.append(f"**Schema:** {schema}")
+    lines.append("")
+
+    # --- Parameters table --------------------------------------------------
+    if meta.parameters:
+        lines.append("## Parameters")
+        lines.append("")
+        lines.append("| Name | Type | Direction | Default | Nullable | Description |")
+        lines.append("|------|------|-----------|---------|----------|-------------|")
+        for p in meta.parameters:
+            name = p.name
+            sql_type = p.sql_type
+            direction = p.direction
+            default = p.default or "—"
+            nullable = "YES" if p.nullable else "NO"
+            desc = p.description or "—"
+            lines.append(
+                f"| {name} | {sql_type} | {direction} | {default} | {nullable} | {desc} |"
+            )
+        lines.append("")
+
+    # --- Result set(s) table -----------------------------------------------
+    if meta.columns:
+        lines.append("## Result Set")
+        lines.append("")
+        lines.append("| Column | Type | Nullable | Description |")
+        lines.append("|--------|------|----------|-------------|")
+        for col in meta.columns:
+            name = col.name
+            sql_type = col.sql_type
+            nullable = "YES" if col.nullable else "NO"
+            desc = col.description or "—"
+            lines.append(f"| {name} | {sql_type} | {nullable} | {desc} |")
+        lines.append("")
+
+    # --- Generated model ---------------------------------------------------
+    try:
+        source_code = _generate_source(meta)
+        lines.append("## Generated Model")
+        lines.append("")
+        lines.append("```python")
+        lines.append(source_code.rstrip("\n"))
+        lines.append("```")
+        lines.append("")
+    except Exception:
+        lines.append("## Generated Model")
+        lines.append("")
+        lines.append("*Model generation failed for this stored procedure.*")
+        lines.append("")
+
+    return "\n".join(lines) + "\n"

singularity/cli/generate.py

@@ -0,0 +1,210 @@
+"""CLI generate command — orchestrates the full pipeline.
+
+Delegates all introspection and model generation to the library.
+Never reimplements library logic.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.progress import (
+    Progress,
+    SpinnerColumn,
+    TextColumn,
+)
+from rich.table import Table
+
+from singularity.cli._app import app
+from singularity.cli.config import load_config
+from singularity.introspector import SQLServerIntrospector
+from singularity.model_generator import generate_model
+
+console = Console()
+
+
+@app.command()
+def generate(
+    config: str = typer.Option(
+        ...,
+        "--config",
+        "-c",
+        help="Path to TOML configuration file.",
+    ),
+) -> None:
+    """Introspect stored procedures and generate Pydantic models.
+
+    Reads configuration from a TOML file, connects to SQL Server,
+    introspects the specified stored procedures, and writes the
+    generated models to the output directory.
+    """
+    # --- Load config -------------------------------------------------------
+    cfg_path = Path(config)
+    if not cfg_path.exists():
+        console.print(f"[red]Error:[/red] Config file not found: [bold]{cfg_path}[/bold]")
+        raise typer.Exit(code=1)
+
+    try:
+        cfg = load_config(str(cfg_path))
+    except Exception as exc:
+        console.print(f"[red]Error loading config:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+    # --- Connect to SQL Server ---------------------------------------------
+    conn_str = cfg.connection.build_connection_string()
+    introspector = SQLServerIntrospector(conn_str)
+
+    try:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console,
+        ) as progress:
+            progress.add_task("Connecting to SQL Server...", total=None)
+            introspector.connect()
+            version = introspector.detect_version()
+        console.print(f"[green]Connected.[/green] Detected version: [bold]{version.value}[/bold]")
+    except Exception as exc:
+        console.print(f"[red]Error connecting to SQL Server:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+    # --- Resolve SPs to introspect -----------------------------------------
+    sp_names: list[str] = []
+
+    if cfg.sp_selection.procedures:
+        sp_names.extend(cfg.sp_selection.procedures)
+
+    if cfg.sp_selection.pattern:
+        try:
+            cursor = introspector._connection.cursor()  # type: ignore[union-attr]
+            cursor.execute(
+                """
+                SELECT ROUTINE_NAME
+                FROM INFORMATION_SCHEMA.ROUTINES
+                WHERE ROUTINE_TYPE = 'PROCEDURE'
+                  AND ROUTINE_NAME LIKE ?
+                """,
+                (cfg.sp_selection.pattern,),
+            )
+            sp_names.extend(row[0] for row in cursor.fetchall())
+        except Exception as exc:
+            console.print(
+                f"[yellow]Error resolving SP pattern '{cfg.sp_selection.pattern}':[/yellow] {exc}"
+            )
+
+    if not sp_names:
+        console.print(
+            "[yellow]No stored procedures selected.[/yellow] "
+            "Check your [bold][sp_selection][/bold] config."
+        )
+        raise typer.Exit(code=0)
+
+    # --- Introspect each SP and generate models ----------------------------
+    out_dir = Path(cfg.output.directory)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    naming_convention = cfg.output.naming_convention
+    mode = cfg.output.mode
+    file_naming = cfg.output.file_naming
+
+    summary_data: list[dict[str, str | int]] = []
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        console=console,
+    ) as progress:
+        task = progress.add_task(
+            f"Introspecting [bold]{len(sp_names)}[/bold] stored procedure(s)...",
+            total=len(sp_names),
+        )
+
+        for sp_name in sp_names:
+            try:
+                meta = introspector.introspect(sp_name)
+
+                result = generate_model(
+                    meta,
+                    mode=mode,
+                    naming_convention=naming_convention,
+                )
+
+                if mode == "source":
+                    parts = sp_name.split(".")
+                    schema = parts[0] if len(parts) > 1 else "dbo"
+                    filename = file_naming.format(
+                        sp_name=sp_name,
+                        schema=schema,
+                        database=cfg.connection.database,
+                    )
+                    filepath = out_dir / filename
+
+                    if isinstance(result, str):
+                        filepath.write_text(result, encoding="utf-8")
+                    else:
+                        console.print(
+                            f"[red]  {sp_name}:[/red] unexpected type returned"
+                        )
+                        summary_data.append({
+                            "sp_name": sp_name,
+                            "params": len(meta.parameters),
+                            "columns": len(meta.columns),
+                            "status": "ERROR",
+                        })
+                        progress.advance(task)
+                        continue
+                else:
+                    pass  # dynamic mode
+
+                summary_data.append({
+                    "sp_name": sp_name,
+                    "params": len(meta.parameters),
+                    "columns": len(meta.columns),
+                    "status": "OK",
+                })
+
+            except Exception as exc:
+                console.print(f"[red]  Error processing {sp_name}:[/red] {exc}")
+                summary_data.append({
+                    "sp_name": sp_name,
+                    "params": 0,
+                    "columns": 0,
+                    "status": "ERROR",
+                })
+
+            progress.advance(task)
+
+    # --- Summary table -----------------------------------------------------
+    table = Table(title="Generation Summary")
+    table.add_column("SP Name", style="cyan")
+    table.add_column("Params", justify="right")
+    table.add_column("Columns", justify="right")
+    table.add_column("Status")
+
+    success_count = 0
+    error_count = 0
+    for row in summary_data:
+        status = row["status"]
+        if status == "OK":
+            status_style = "[green]OK[/green]"
+            success_count += 1
+        else:
+            status_style = "[red]ERROR[/red]"
+            error_count += 1
+        table.add_row(
+            str(row["sp_name"]),
+            str(row["params"]),
+            str(row["columns"]),
+            status_style,
+        )
+
+    console.print(table)
+    console.print(
+        f"\nDone. [green]{success_count} succeeded[/green], "
+        f"[red]{error_count} failed[/red]."
+    )
+
+    if error_count > 0:
+        raise typer.Exit(code=1)

singularity/exceptions.py

@@ -0,0 +1,13 @@
+"""Custom exception hierarchy for Singularity."""
+
+
+class SingularityError(Exception):
+    """Base exception for all Singularity errors."""
+
+
+class SpNotFoundError(SingularityError):
+    """Raised when a requested stored procedure does not exist."""
+
+    def __init__(self, sp_name: str) -> None:
+        self.sp_name = sp_name
+        super().__init__(f"Stored procedure '{sp_name}' not found in the database.")