singularitysql 0.1.0__py3-none-any.whl

singularity/version/_azure.py

@@ -0,0 +1,122 @@
+"""Introspection strategy for Azure SQL Database.
+
+Uses sys.parameters for parameter metadata and
+sys.dm_exec_describe_first_result_set for result set column metadata.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from singularity.exceptions import SpNotFoundError
+from singularity.types import ColumnInfo, Parameter, SPMetadata
+from singularity.version._base import VersionIntrospector
+
+
+class AzureIntrospector(VersionIntrospector):
+    """Strategy for Azure SQL Database: sys.parameters + sys.dm_exec_describe_first_result_set."""
+
+    def introspect(self, sp_name: str, cursor: Any) -> SPMetadata:
+        """Introspect a stored procedure on Azure SQL Database.
+
+        Args:
+            sp_name: The stored procedure name.
+            cursor: An active pyodbc Cursor.
+
+        Returns:
+            SPMetadata with parameters and result set columns.
+
+        Raises:
+            SpNotFoundError: If the procedure does not exist.
+        """
+        simple_name = sp_name.split(".")[-1] if "." in sp_name else sp_name
+
+        # Verify the procedure exists
+        cursor.execute(
+            """
+            SELECT COUNT(*)
+            FROM sys.objects
+            WHERE type = 'P'
+              AND name = ?
+            """,
+            (simple_name,),
+        )
+        if cursor.fetchone()[0] == 0:
+            raise SpNotFoundError(sp_name)
+
+        # Fetch parameter metadata from sys.parameters
+        cursor.execute(
+            """
+            SELECT
+                p.name,
+                tp.name AS data_type,
+                CASE
+                    WHEN p.is_output = 1 THEN 'OUT'
+                    ELSE 'IN'
+                END AS param_mode,
+                p.has_default_value,
+                p.is_nullable
+            FROM sys.parameters p
+            JOIN sys.types tp ON p.user_type_id = tp.user_type_id
+            JOIN sys.objects o ON p.object_id = o.object_id
+            WHERE o.type = 'P'
+              AND o.name = ?
+            ORDER BY p.parameter_id
+            """,
+            (simple_name,),
+        )
+
+        parameters: list[Parameter] = []
+        for row in cursor.fetchall():
+            raw_name: str = row[0]
+            sql_type: str = row[1]
+            direction: str = row[2]
+            has_default: bool = row[3] or False
+            nullable: bool = row[4] or False
+
+            parameters.append(
+                Parameter(
+                    name=raw_name,
+                    sql_type=sql_type.upper(),
+                    direction=direction,  # type: ignore[arg-type]
+                    default=None if not has_default else "(default)",
+                    nullable=nullable,
+                )
+            )
+
+        # Fetch result sets using Azure's DMV (first result set only)
+        result_sets: list[list[ColumnInfo]] = []
+        try:
+            cursor.execute(
+                """
+                SELECT
+                    name,
+                    system_type_name,
+                    is_nullable
+                FROM sys.dm_exec_describe_first_result_set(
+                    N'EXEC ' + QUOTENAME(?), NULL, 0
+                )
+                """,
+                (simple_name,),
+            )
+            columns = [
+                ColumnInfo(
+                    name=row[0],  # name
+                    sql_type=(row[1] or "UNKNOWN").upper(),  # system_type_name
+                    nullable=bool(row[2]),  # is_nullable
+                )
+                for row in cursor.fetchall()
+                if row[0] is not None
+            ]
+            if columns:
+                result_sets.append(columns)
+        except Exception:
+            pass
+
+        # Enrich with column descriptions from extended properties
+        for rs in result_sets:
+            descriptions = self._fetch_column_descriptions(sp_name, cursor, rs)
+            for col in rs:
+                col.description = descriptions.get(col.name)
+
+        return SPMetadata(name=sp_name, parameters=parameters, result_sets=result_sets)

singularity/version/_base.py

@@ -0,0 +1,73 @@
+"""Abstract base class for version-specific introspection strategies."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from singularity.types import SPMetadata
+
+
+class VersionIntrospector(ABC):
+    """Strategy for introspecting stored procedure metadata for a specific
+    SQL Server version or platform.
+
+    Each concrete implementation knows the correct system views, functions,
+    and DMVs to query for parameter and result set metadata.
+    """
+
+    @abstractmethod
+    def introspect(self, sp_name: str, cursor: Any) -> SPMetadata:
+        """Introspect a stored procedure and return its metadata.
+
+        Args:
+            sp_name: The stored procedure name (with or without schema).
+            cursor: An active pyodbc Cursor connected to the database.
+
+        Returns:
+            SPMetadata containing parameters and result set column info.
+
+        Raises:
+            SpNotFoundError: If the stored procedure does not exist.
+        """
+        ...
+
+    def _fetch_column_descriptions(
+        self, sp_name: str, cursor: Any, columns: list[Any],
+    ) -> dict[str, str]:
+        """Query sys.extended_properties for column descriptions.
+
+        Args:
+            sp_name: The stored procedure name (schema-qualified if available).
+            cursor: An active pyodbc Cursor.
+            columns: List of ColumnInfo objects to look up descriptions for.
+
+        Returns:
+            A dict mapping column names to their descriptions.
+        """
+        if not columns:
+            return {}
+
+        descriptions: dict[str, str] = {}
+
+        try:
+            for col in columns:
+                cursor.execute(
+                    """
+                    SELECT CAST(ep.value AS NVARCHAR(MAX))
+                    FROM sys.extended_properties ep
+                    WHERE ep.class = 1
+                      AND ep.major_id = OBJECT_ID(?)
+                      AND ep.minor_id = COLUMNPROPERTY(OBJECT_ID(?), ?, 'ColumnId')
+                      AND ep.name = 'MS_Description'
+                    """,
+                    (sp_name, sp_name, col.name),
+                )
+                row = cursor.fetchone()
+                if row and row[0] is not None:
+                    descriptions[col.name] = str(row[0])
+        except Exception:
+            # Extended properties are optional — silently skip on failure
+            pass
+
+        return descriptions

singularity/version/_legacy.py

@@ -0,0 +1,150 @@
+"""Introspection strategy for SQL Server 2008–2014.
+
+Uses sys.parameters for parameter metadata and falls back to
+sys.columns + sys.objects for result set columns when
+sp_describe_first_result_set is unavailable.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from singularity.exceptions import SpNotFoundError
+from singularity.types import ColumnInfo, Parameter, SPMetadata
+from singularity.version._base import VersionIntrospector
+
+
+class LegacyIntrospector(VersionIntrospector):
+    """Strategy for SQL Server 2008–2014 using sys.parameters + sys.columns/sys.objects fallback."""
+
+    def introspect(self, sp_name: str, cursor: Any) -> SPMetadata:
+        """Introspect a stored procedure using legacy SQL Server system views.
+
+        Args:
+            sp_name: The stored procedure name.
+            cursor: An active pyodbc Cursor.
+
+        Returns:
+            SPMetadata with parameters and result set columns.
+
+        Raises:
+            SpNotFoundError: If the procedure does not exist.
+        """
+        simple_name = sp_name.split(".")[-1] if "." in sp_name else sp_name
+
+        # Verify the procedure exists via sys.objects
+        cursor.execute(
+            """
+            SELECT COUNT(*)
+            FROM sys.objects
+            WHERE type = 'P'
+              AND name = ?
+            """,
+            (simple_name,),
+        )
+        if cursor.fetchone()[0] == 0:
+            raise SpNotFoundError(sp_name)
+
+        # Fetch parameter metadata from sys.parameters
+        cursor.execute(
+            """
+            SELECT
+                p.name,
+                tp.name AS data_type,
+                CASE
+                    WHEN p.is_output = 1 THEN 'OUT'
+                    ELSE 'IN'
+                END AS param_mode,
+                p.has_default_value,
+                p.is_nullable
+            FROM sys.parameters p
+            JOIN sys.types tp ON p.user_type_id = tp.user_type_id
+            JOIN sys.objects o ON p.object_id = o.object_id
+            WHERE o.type = 'P'
+              AND o.name = ?
+            ORDER BY p.parameter_id
+            """,
+            (simple_name,),
+        )
+
+        parameters: list[Parameter] = []
+        for row in cursor.fetchall():
+            raw_name: str = row[0]  # e.g. "@OrderId"
+            sql_type: str = row[1]
+            direction: str = row[2]
+            has_default: bool = row[3] or False
+            nullable: bool = row[4] or False
+
+            parameters.append(
+                Parameter(
+                    name=raw_name,
+                    sql_type=sql_type.upper(),
+                    direction=direction,  # type: ignore[arg-type]
+                    default=None if not has_default else "(default)",
+                    nullable=nullable,
+                )
+            )
+
+        # First result set: try sp_describe_first_result_set;
+        # fall back to sys.columns + sys.objects join.
+        result_sets: list[list[ColumnInfo]] = []
+
+        try:
+            tsql = f"EXEC {sp_name}"
+            for idx in range(10):
+                cursor.execute(
+                    "{CALL sp_describe_first_result_set(?, NULL, ?)}",
+                    (tsql, idx),
+                )
+                rows = cursor.fetchall()
+                columns = [
+                    ColumnInfo(
+                        name=row[2],  # name (index 2)
+                        sql_type=(row[5] or "UNKNOWN").upper(),  # system_type_name (index 5)
+                        nullable=bool(row[3]),  # is_nullable (index 3)
+                    )
+                    for row in rows
+                    if row[2] is not None
+                ]
+                if not columns:
+                    break
+                result_sets.append(columns)
+        except Exception:
+            # Fallback: query sys.columns through sys.objects for the SP
+            try:
+                cursor.execute(
+                    """
+                    SELECT
+                        c.name,
+                        tp.name AS data_type,
+                        c.is_nullable
+                    FROM sys.columns c
+                    JOIN sys.objects o ON c.object_id = o.object_id
+                    JOIN sys.types tp ON c.user_type_id = tp.user_type_id
+                    WHERE o.type = 'P'
+                      AND o.name = ?
+                    ORDER BY c.column_id
+                    """,
+                    (simple_name,),
+                )
+                columns = [
+                    ColumnInfo(
+                        name=row[0],
+                        sql_type=row[1].upper(),
+                        nullable=row[2] or False,
+                    )
+                    for row in cursor.fetchall()
+                ]
+                if columns:
+                    result_sets.append(columns)
+            except Exception:
+                # If everything fails, return empty result sets gracefully
+                pass
+
+        # Enrich with column descriptions from extended properties
+        for rs in result_sets:
+            descriptions = self._fetch_column_descriptions(sp_name, cursor, rs)
+            for col in rs:
+                col.description = descriptions.get(col.name)
+
+        return SPMetadata(name=sp_name, parameters=parameters, result_sets=result_sets)

singularity/version/_modern.py

@@ -0,0 +1,122 @@
+"""Introspection strategy for SQL Server 2016 and later.
+
+Uses INFORMATION_SCHEMA.PARAMETERS for parameter metadata and
+sp_describe_first_result_set for result set column metadata.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from singularity.exceptions import SpNotFoundError
+from singularity.types import ColumnInfo, Parameter, SPMetadata
+from singularity.version._base import VersionIntrospector
+
+
+class ModernIntrospector(VersionIntrospector):
+    """Strategy for SQL Server 2016+ using INFORMATION_SCHEMA + sp_describe_first_result_set."""
+
+    def introspect(self, sp_name: str, cursor: Any) -> SPMetadata:
+        """Introspect a stored procedure using modern SQL Server system views.
+
+        Args:
+            sp_name: The stored procedure name.
+            cursor: An active pyodbc Cursor.
+
+        Returns:
+            SPMetadata with parameters and result set columns.
+
+        Raises:
+            SpNotFoundError: If the procedure does not exist.
+        """
+        # Strip schema prefix for lookup if present
+        simple_name = sp_name.split(".")[-1] if "." in sp_name else sp_name
+
+        # Verify the procedure exists
+        cursor.execute(
+            """
+            SELECT COUNT(*)
+            FROM INFORMATION_SCHEMA.ROUTINES
+            WHERE ROUTINE_TYPE = 'PROCEDURE'
+              AND ROUTINE_NAME = ?
+            """,
+            (simple_name,),
+        )
+        if cursor.fetchone()[0] == 0:
+            raise SpNotFoundError(sp_name)
+
+        # Fetch parameter metadata from sys.parameters
+        cursor.execute(
+            """
+            SELECT
+                p.name,
+                tp.name AS data_type,
+                CASE
+                    WHEN p.is_output = 1 THEN 'OUT'
+                    WHEN p.is_output = 0 AND p.is_readonly = 0 THEN 'IN'
+                    ELSE 'INOUT'
+                END AS param_mode,
+                p.has_default_value,
+                p.is_nullable
+            FROM sys.parameters p
+            JOIN sys.types tp ON p.user_type_id = tp.user_type_id
+            JOIN sys.objects o ON p.object_id = o.object_id
+            WHERE o.type = 'P'
+              AND o.name = ?
+            ORDER BY p.parameter_id
+            """,
+            (simple_name,),
+        )
+
+        parameters: list[Parameter] = []
+        for row in cursor.fetchall():
+            raw_name: str = row[0]  # e.g. "@OrderId"
+            sql_type: str = row[1]
+            direction: str = row[2]
+            has_default: bool = row[3] or False
+            nullable: bool = row[4] or False
+
+            parameters.append(
+                Parameter(
+                    name=raw_name,
+                    sql_type=sql_type.upper(),
+                    direction=direction,  # type: ignore[arg-type]
+                    default=None if not has_default else "(default)",
+                    nullable=nullable,
+                )
+            )
+
+        # Fetch all result sets via sp_describe_first_result_set
+        result_sets: list[list[ColumnInfo]] = []
+        try:
+            tsql = f"EXEC {sp_name}"
+            for idx in range(10):
+                cursor.execute(
+                    "{CALL sp_describe_first_result_set(?, NULL, ?)}",
+                    (tsql, idx),
+                )
+                rows = cursor.fetchall()
+                columns = [
+                    ColumnInfo(
+                        name=row[2],  # name (index 2)
+                        sql_type=(row[5] or "UNKNOWN").upper(),  # system_type_name (index 5)
+                        nullable=bool(row[3]),  # is_nullable (index 3)
+                    )
+                    for row in rows
+                    if row[2] is not None  # skip unnamed columns
+                ]
+                if not columns:
+                    break
+                result_sets.append(columns)
+        except Exception:
+            # If sp_describe_first_result_set fails (e.g. dynamic SQL),
+            # return empty result sets rather than crashing.
+            pass
+
+        # Enrich with column descriptions from extended properties
+        for rs in result_sets:
+            descriptions = self._fetch_column_descriptions(sp_name, cursor, rs)
+            for col in rs:
+                col.description = descriptions.get(col.name)
+
+        return SPMetadata(name=sp_name, parameters=parameters, result_sets=result_sets)

singularitysql-0.1.0.dist-info/METADATA

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: singularitysql
+Version: 0.1.0
+Summary: SQL Server stored procedure introspection and Pydantic model generator
+Author: Samuel Urrego
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyodbc>=5.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typer>=0.9
+Requires-Dist: tomli>=2.0
+Requires-Dist: rich>=15.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.14; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="assets/logo.png" alt="Singularity" width="400">
+</p>
+
+> SQL Server → Pydantic v2. Automatically.
+
+[![CI](https://github.com/Samuel-Urrego/Singularity/actions/workflows/ci.yml/badge.svg)](https://github.com/Samuel-Urrego/Singularity/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/pypi/pyversions/singularity.svg)](https://pypi.org/project/singularity/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+Singularity bridges the gap between SQL Server and Python. Connect to your database, point at a stored procedure, and get a **Pydantic v2 model** — as a runtime class or a `.py` file you can commit.
+
+```bash
+singularity --config config.toml
+```
+
+```python
+from singularity import SQLServerIntrospector, generate_model
+
+introspector = SQLServerIntrospector("DRIVER={ODBC Driver 17};SERVER=...;DATABASE=...")
+meta = introspector.introspect("usp_GetOrders")
+model = generate_model(meta, mode="dynamic")
+# <class 'pydantic.main.UspGetOrders'>
+```
+
+## Why Singularity?
+
+**The problem**: You have dozens of complex stored procedures in SQL Server. Calling them from Python means manually writing Pydantic models for every parameter and result set. One typo, and you get a runtime error.
+
+**The solution**: Singularity reads SQL Server's system catalog (`sys.parameters`, `sp_describe_first_result_set`) and generates the models for you. Zero manual mapping.
+
+| Approach | Lines of code | Maintainable | Type-safe |
+|---|---|---|---|
+| Manual Pydantic models | 100s–1000s | ❌ | ⚠️ (manual) |
+| Raw dicts / tuples | Fewer | ❌ | ❌ |
+| **Singularity** | **Zero** | ✅ | ✅ |
+
+## Features
+
+- 🔌 **Auto-connect** — pyodbc connection with `@@VERSION` detection
+- 🧠 **Version-aware** — Modern (2016+), Legacy (2008–2014), and Azure SQL strategies
+- 📦 **Two output modes**:
+  - `"dynamic"` — `create_model()` at runtime, usable immediately
+  - `"source"` — `.py` files you can commit and review
+- 🏷️ **Full type mapping** — `INT`→`int`, `VARCHAR`→`str`, `DATETIME`→`datetime`, `BIT`→`bool`, etc.
+- 🎨 **Configurable naming** — snake_case, camelCase, PascalCase for field names
+- 🗂️ **File naming templates** — `{schema}_{sp_name}.py`, `{database}_{sp_name}.py`, etc.
+- 🛡️ **Nullable awareness** — `Optional[T]` for nullable columns
+- ⚡ **UV-first** — fast dependency management
+
+## Installation
+
+```bash
+uv add singularity
+# or
+pip install singularity
+```
+
+**Prerequisite**: [ODBC Driver for SQL Server](https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server) (17 or 18).
+
+## Quick Start
+
+### 1. Create a config file
+
+```toml
+# config.toml
+[connection]
+server = "localhost"
+database = "AdventureWorks"
+driver = "ODBC Driver 18 for SQL Server"
+trusted_connection = true
+
+[sp_selection]
+pattern = "usp_%"
+
+[output]
+directory = "generated_models"
+mode = "source"
+file_naming = "{schema}_{sp_name}.py"
+naming_convention = "snake_case"
+```
+
+### 2. Generate models
+
+```bash
+singularity --config config.toml
+```
+
+```
+Connected. Detected version: modern
+  Introspecting usp_GetOrders... → generated_models/dbo_usp_GetOrders.py
+  Introspecting usp_GetCustomers... → generated_models/dbo_usp_GetCustomers.py
+
+Done. 2 succeeded, 0 failed.
+```
+
+### 3. Use the generated models
+
+```python
+from generated_models.dbo_usp_GetOrders import UspGetOrders
+
+order = UspGetOrders(id=1, customer_name="Acme Corp", total=99.99)
+```
+
+## Library Usage
+
+```python
+from singularity import SQLServerIntrospector, generate_model
+
+# Connect and introspect
+introspector = SQLServerIntrospector(conn_str)
+introspector.connect()
+version = introspector.detect_version()  # ServerVersion.MODERN
+metadata = introspector.introspect("usp_GetOrders")
+
+# Runtime model
+DynamicModel = generate_model(metadata, mode="dynamic")
+instance = DynamicModel(id=1, customer_name="Acme")
+
+# Source code string
+source_code = generate_model(metadata, mode="source")
+with open("models/usp_GetOrders.py", "w") as f:
+    f.write(source_code)
+```
+
+## Configuration Reference
+
+### `[connection]`
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `server` | ✅ | — | Server hostname or IP |
+| `database` | ✅ | — | Database name |
+| `driver` | ❌ | `ODBC Driver 18 for SQL Server` | ODBC driver name |
+| `trusted_connection` | ❌ | `true` | Use Windows auth |
+| `username` | ❌ | — | SQL auth username |
+| `password` | ❌ | — | SQL auth password |
+
+### `[sp_selection]`
+
+| Field | Required | Description |
+|---|---|---|
+| `procedures` | ❌ | Explicit list of SP names |
+| `pattern` | ❌ | Wildcard pattern (e.g. `usp_%`) |
+
+At least one of `procedures` or `pattern` must be specified.
+
+### `[output]`
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `directory` | ❌ | `.` | Output directory |
+| `mode` | ❌ | `source` | `source` or `dynamic` |
+| `file_naming` | ❌ | `{sp_name}.py` | Template with `{schema}`, `{database}`, `{sp_name}` |
+| `naming_convention` | ❌ | `snake_case` | `snake_case`, `camelCase`, or `PascalCase` |
+
+## Supported SQL Server Versions
+
+| Version | Strategy | Parameter introspection | Result set metadata |
+|---|---|---|---|
+| 2016+ | Modern | `sys.parameters` | `sp_describe_first_result_set` |
+| 2008–2014 | Legacy | `sys.parameters` | `sp_describe_first_result_set` + `sys.columns` fallback |
+| Azure SQL | Azure | `sys.parameters` | `sys.dm_exec_describe_first_result_set` |
+
+## Type Mapping
+
+| SQL Server | Python | Pydantic |
+|---|---|---|
+| `INT`, `BIGINT`, `SMALLINT`, `TINYINT` | `int` | `int` |
+| `VARCHAR`, `NVARCHAR`, `CHAR`, `NCHAR`, `TEXT` | `str` | `str` |
+| `DATETIME`, `DATETIME2`, `DATE`, `SMALLDATETIME` | `datetime` | `datetime` |
+| `BIT` | `bool` | `bool` |
+| `DECIMAL`, `NUMERIC`, `FLOAT`, `REAL`, `MONEY` | `float` | `float` |
+| `UNIQUEIDENTIFIER` | `str` | `str` |
+| Unknown types | `str` + warning | `str` |
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/Samuel-Urrego/Singularity
+cd singularity
+uv sync
+
+# Run tests
+uv run pytest
+
+# Lint and type-check
+uv run ruff check .
+uv run mypy singularity/
+
+# Install pre-commit hooks
+uv run pre-commit install
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.