sqlspec 0.9.0__tar.gz → 0.9.1__tar.gz

{sqlspec-0.9.0 → sqlspec-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlspec
-Version: 0.9.0
+Version: 0.9.1
 Summary: SQL Experiments in Python
 Author-email: Cody Fincher <cody@litestar.dev>
 Maintainer-email: Litestar Developers <hello@litestar.dev>
@@ -83,6 +83,145 @@ SQLSpec is an experimental Python library designed to streamline and modernize y
 
 SQLSpec is a work in progress. While it offers a solid foundation for modern SQL interactions, it does not yet include every feature you might find in a mature ORM or database toolkit. The focus is on building a robust, flexible core that can be extended over time.
 
+## Examples
+
+We've talked about what SQLSpec is not, so let's look at what it can do.
+
+These are just a few of the examples that demonstrate SQLSpec's flexibility and each of the bundled adapters offer the same config and driver interfaces.
+
+### DuckDB LLM
+
+This is a quick implementation using some of the built in Secret and Extension management features of SQLSpec's DuckDB integration.
+
+It allows you to communicate with any compatible OpenAPI conversations endpoint (such as Ollama).  This examples:
+
+- auto installs the `open_prompt` DuckDB extensions
+- automatically creates the correct `open_prompt` comptaible secret required to use the extension
+
+```py
+# /// script
+# dependencies = [
+#   "sqlspec[duckdb,performance]",
+# ]
+# ///
+import os
+
+from sqlspec import SQLSpec
+from sqlspec.adapters.duckdb import DuckDBConfig
+from pydantic import BaseModel
+
+class ChatMessage(BaseModel):
+    message: str
+
+sql = SQLSpec()
+etl_config = sql.add_config(
+    DuckDBConfig(
+        extensions=[{"name": "open_prompt"}],
+        secrets=[
+            {
+                "secret_type": "open_prompt",
+                "name": "open_prompt",
+                "value": {
+                    "api_url": "http://127.0.0.1:11434/v1/chat/completions",
+                    "model_name": "gemma3:1b",
+                    "api_timeout": "120",
+                },
+            }
+        ],
+    )
+)
+with sql.provide_session(etl_config) as session:
+    result = session.select_one("SELECT open_prompt(?)", data.message, schema_type=ChatMessage)
+    print(result) # result is a ChatMessage pydantic model
+```
+
+### DuckDB Gemini Embeddings
+
+In this example, we are again using DuckDB.  However, we are going to use the built in to call the Google Gemini embeddings service directly from the database.
+
+This example will
+
+- auto installs the `http_client` and `vss` (vector similarity search) DuckDB extensions
+- when a connection is created, it ensures that the `generate_embeddings` macro exists in the DuckDB database.
+- Execute a simple query to call the Google API
+
+```py
+# /// script
+# dependencies = [
+#   "sqlspec[duckdb,performance]",
+# ]
+# ///
+import os
+
+from sqlspec import SQLSpec
+from sqlspec.adapters.duckdb import DuckDBConfig
+
+EMBEDDING_MODEL = "gemini-embedding-exp-03-07"
+GOOGLE_API_KEY = os.environ.get("GOOGLE_API_KEY")
+API_URL = (
+    f"https://generativelanguage.googleapis.com/v1beta/models/{EMBEDDING_MODEL}:embedContent?key=${GOOGLE_API_KEY}"
+)
+
+sql = SQLSpec()
+etl_config = sql.add_config(
+    DuckDBConfig(
+        extensions=[{"name": "vss"}, {"name": "http_client"}],
+        on_connection_create=lambda connection: connection.execute(f"""
+            CREATE IF NOT EXISTS MACRO generate_embedding(q) AS (
+                WITH  __request AS (
+                    SELECT http_post(
+                        '{API_URL}',
+                        headers => MAP {{
+                            'accept': 'application/json',
+                        }},
+                        params => MAP {{
+                            'model': 'models/{EMBEDDING_MODEL}',
+                            'parts': [{{ 'text': q }}],
+                            'taskType': 'SEMANTIC_SIMILARITY'
+                        }}
+                    ) AS response
+                )
+                SELECT *
+                FROM __request,
+            );
+        """),
+    )
+)
+with sql.provide_session(etl_config) as session:
+    result = session.select_one("SELECT generate_embedding('example text')")
+    print(result) # result is a dictionary when `schema_type` is omitted.
+```
+
+### Basic Litestar Integration
+
+In this example we are going to demonstrate how to create a basic configuration that integrates into Litestar.
+
+```py
+# /// script
+# dependencies = [
+#   "sqlspec[aiosqlite]",
+#   "litestar[standard]",
+# ]
+# ///
+
+from aiosqlite import Connection
+from litestar import Litestar, get
+
+from sqlspec.adapters.aiosqlite import AiosqliteConfig, AiosqliteDriver
+from sqlspec.extensions.litestar import SQLSpec
+
+
+@get("/")
+async def simple_sqlite(db_session: AiosqliteDriver) -> dict[str, str]:
+    return await db_session.select_one("SELECT 'Hello, world!' AS greeting")
+
+
+sqlspec = SQLSpec(config=DatabaseConfig(
+    config=[AiosqliteConfig(), commit_mode="autocommit")],
+)
+app = Litestar(route_handlers=[simple_sqlite], plugins=[sqlspec])
+```
+
 ## Inspiration and Future Direction
 
 SQLSpec originally drew inspiration from features found in the `aiosql` library.  This is a great library for working with and executed SQL stored in files.  It's unclear how much of an overlap there will be between the two libraries, but it's possible that some features will be contributed back to `aiosql` where appropriate.
@@ -121,7 +260,7 @@ This list is not final. If you have a driver you'd like to see added, please ope
 - `sqlspec/`:
     - `adapters/`: Contains all database drivers and associated configuration.
     - `extensions/`:
-        - `litestar/`: Future home of `litestar` integration.
+        - `litestar/`: Litestar framework integration ✅
         - `fastapi/`: Future home of `fastapi` integration.
         - `flask/`: Future home of `flask` integration.
         - `*/`: Future home of your favorite framework integration 🔌 ✨

{sqlspec-0.9.0 → sqlspec-0.9.1}/README.md

@@ -22,6 +22,145 @@ SQLSpec is an experimental Python library designed to streamline and modernize y
 
 SQLSpec is a work in progress. While it offers a solid foundation for modern SQL interactions, it does not yet include every feature you might find in a mature ORM or database toolkit. The focus is on building a robust, flexible core that can be extended over time.
 
+## Examples
+
+We've talked about what SQLSpec is not, so let's look at what it can do.
+
+These are just a few of the examples that demonstrate SQLSpec's flexibility and each of the bundled adapters offer the same config and driver interfaces.
+
+### DuckDB LLM
+
+This is a quick implementation using some of the built in Secret and Extension management features of SQLSpec's DuckDB integration.
+
+It allows you to communicate with any compatible OpenAPI conversations endpoint (such as Ollama).  This examples:
+
+- auto installs the `open_prompt` DuckDB extensions
+- automatically creates the correct `open_prompt` comptaible secret required to use the extension
+
+```py
+# /// script
+# dependencies = [
+#   "sqlspec[duckdb,performance]",
+# ]
+# ///
+import os
+
+from sqlspec import SQLSpec
+from sqlspec.adapters.duckdb import DuckDBConfig
+from pydantic import BaseModel
+
+class ChatMessage(BaseModel):
+    message: str
+
+sql = SQLSpec()
+etl_config = sql.add_config(
+    DuckDBConfig(
+        extensions=[{"name": "open_prompt"}],
+        secrets=[
+            {
+                "secret_type": "open_prompt",
+                "name": "open_prompt",
+                "value": {
+                    "api_url": "http://127.0.0.1:11434/v1/chat/completions",
+                    "model_name": "gemma3:1b",
+                    "api_timeout": "120",
+                },
+            }
+        ],
+    )
+)
+with sql.provide_session(etl_config) as session:
+    result = session.select_one("SELECT open_prompt(?)", data.message, schema_type=ChatMessage)
+    print(result) # result is a ChatMessage pydantic model
+```
+
+### DuckDB Gemini Embeddings
+
+In this example, we are again using DuckDB.  However, we are going to use the built in to call the Google Gemini embeddings service directly from the database.
+
+This example will
+
+- auto installs the `http_client` and `vss` (vector similarity search) DuckDB extensions
+- when a connection is created, it ensures that the `generate_embeddings` macro exists in the DuckDB database.
+- Execute a simple query to call the Google API
+
+```py
+# /// script
+# dependencies = [
+#   "sqlspec[duckdb,performance]",
+# ]
+# ///
+import os
+
+from sqlspec import SQLSpec
+from sqlspec.adapters.duckdb import DuckDBConfig
+
+EMBEDDING_MODEL = "gemini-embedding-exp-03-07"
+GOOGLE_API_KEY = os.environ.get("GOOGLE_API_KEY")
+API_URL = (
+    f"https://generativelanguage.googleapis.com/v1beta/models/{EMBEDDING_MODEL}:embedContent?key=${GOOGLE_API_KEY}"
+)
+
+sql = SQLSpec()
+etl_config = sql.add_config(
+    DuckDBConfig(
+        extensions=[{"name": "vss"}, {"name": "http_client"}],
+        on_connection_create=lambda connection: connection.execute(f"""
+            CREATE IF NOT EXISTS MACRO generate_embedding(q) AS (
+                WITH  __request AS (
+                    SELECT http_post(
+                        '{API_URL}',
+                        headers => MAP {{
+                            'accept': 'application/json',
+                        }},
+                        params => MAP {{
+                            'model': 'models/{EMBEDDING_MODEL}',
+                            'parts': [{{ 'text': q }}],
+                            'taskType': 'SEMANTIC_SIMILARITY'
+                        }}
+                    ) AS response
+                )
+                SELECT *
+                FROM __request,
+            );
+        """),
+    )
+)
+with sql.provide_session(etl_config) as session:
+    result = session.select_one("SELECT generate_embedding('example text')")
+    print(result) # result is a dictionary when `schema_type` is omitted.
+```
+
+### Basic Litestar Integration
+
+In this example we are going to demonstrate how to create a basic configuration that integrates into Litestar.
+
+```py
+# /// script
+# dependencies = [
+#   "sqlspec[aiosqlite]",
+#   "litestar[standard]",
+# ]
+# ///
+
+from aiosqlite import Connection
+from litestar import Litestar, get
+
+from sqlspec.adapters.aiosqlite import AiosqliteConfig, AiosqliteDriver
+from sqlspec.extensions.litestar import SQLSpec
+
+
+@get("/")
+async def simple_sqlite(db_session: AiosqliteDriver) -> dict[str, str]:
+    return await db_session.select_one("SELECT 'Hello, world!' AS greeting")
+
+
+sqlspec = SQLSpec(config=DatabaseConfig(
+    config=[AiosqliteConfig(), commit_mode="autocommit")],
+)
+app = Litestar(route_handlers=[simple_sqlite], plugins=[sqlspec])
+```
+
 ## Inspiration and Future Direction
 
 SQLSpec originally drew inspiration from features found in the `aiosql` library.  This is a great library for working with and executed SQL stored in files.  It's unclear how much of an overlap there will be between the two libraries, but it's possible that some features will be contributed back to `aiosql` where appropriate.
@@ -60,7 +199,7 @@ This list is not final. If you have a driver you'd like to see added, please ope
 - `sqlspec/`:
     - `adapters/`: Contains all database drivers and associated configuration.
     - `extensions/`:
-        - `litestar/`: Future home of `litestar` integration.
+        - `litestar/`: Litestar framework integration ✅
         - `fastapi/`: Future home of `fastapi` integration.
         - `flask/`: Future home of `flask` integration.
         - `*/`: Future home of your favorite framework integration 🔌 ✨

{sqlspec-0.9.0 → sqlspec-0.9.1}/pyproject.toml

@@ -7,7 +7,7 @@ maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
 name = "sqlspec"
 readme = "README.md"
 requires-python = ">=3.9, <4.0"
-version = "0.9.0"
+version = "0.9.1"
 
 [project.optional-dependencies]
 adbc = ["adbc_driver_manager", "pyarrow"]
@@ -109,7 +109,7 @@ packages = ["sqlspec"]
 allow_dirty = true
 commit = false
 commit_args = "--no-verify"
-current_version = "0.9.0"
+current_version = "0.9.1"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"

{sqlspec-0.9.0 → sqlspec-0.9.1}/sqlspec/adapters/adbc/driver.py

@@ -1,9 +1,9 @@
 import contextlib
 import logging
 import re
-from collections.abc import Generator
+from collections.abc import Generator, Sequence
 from contextlib import contextmanager
-from typing import TYPE_CHECKING, Any, ClassVar, Optional, Union, cast
+from typing import TYPE_CHECKING, Any, ClassVar, Optional, Union, cast, overload
 
 from adbc_driver_manager.dbapi import Connection, Cursor
 
@@ -160,6 +160,28 @@ class AdbcDriver(SyncArrowBulkOperationsMixin["Connection"], SyncDriverAdapterPr
         stmt = SQLStatement(sql=sql, parameters=parameters, dialect=self.dialect, kwargs=kwargs or None)
         return stmt.process()
 
+    @overload
+    def select(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[Connection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Sequence[dict[str, Any]]": ...
+    @overload
+    def select(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[Connection]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "Sequence[ModelDTOT]": ...
     def select(
         self,
         sql: str,
@@ -169,7 +191,7 @@ class AdbcDriver(SyncArrowBulkOperationsMixin["Connection"], SyncDriverAdapterPr
         connection: Optional["Connection"] = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
-    ) -> "list[Union[ModelDTOT, dict[str, Any]]]":
+    ) -> "Sequence[Union[ModelDTOT, dict[str, Any]]]":
         """Fetch data from the database.
 
         Returns:
@@ -189,6 +211,28 @@ class AdbcDriver(SyncArrowBulkOperationsMixin["Connection"], SyncDriverAdapterPr
                 return [cast("ModelDTOT", schema_type(**dict(zip(column_names, row)))) for row in results]  # pyright: ignore[reportUnknownArgumentType,reportUnknownVariableType]
             return [dict(zip(column_names, row)) for row in results]  # pyright: ignore[reportUnknownArgumentType,reportUnknownVariableType]
 
+    @overload
+    def select_one(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[Connection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "dict[str, Any]": ...
+    @overload
+    def select_one(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[Connection]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "ModelDTOT": ...
     def select_one(
         self,
         sql: str,
@@ -215,6 +259,28 @@ class AdbcDriver(SyncArrowBulkOperationsMixin["Connection"], SyncDriverAdapterPr
                 return dict(zip(column_names, result))  # pyright: ignore[reportUnknownArgumentType, reportUnknownVariableType]
             return schema_type(**dict(zip(column_names, result)))  # type: ignore[return-value]
 
+    @overload
+    def select_one_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[Connection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Optional[dict[str, Any]]": ...
+    @overload
+    def select_one_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[Connection]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "Optional[ModelDTOT]": ...
     def select_one_or_none(
         self,
         sql: str,
@@ -242,6 +308,28 @@ class AdbcDriver(SyncArrowBulkOperationsMixin["Connection"], SyncDriverAdapterPr
                 return dict(zip(column_names, result))  # pyright: ignore[reportUnknownArgumentType, reportUnknownVariableType]
             return schema_type(**dict(zip(column_names, result)))  # type: ignore[return-value]
 
+    @overload
+    def select_value(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[Connection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Any": ...
+    @overload
+    def select_value(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[Connection]" = None,
+        schema_type: "type[T]",
+        **kwargs: Any,
+    ) -> "T": ...
     def select_value(
         self,
         sql: str,
@@ -267,6 +355,28 @@ class AdbcDriver(SyncArrowBulkOperationsMixin["Connection"], SyncDriverAdapterPr
                 return result[0]  # pyright: ignore[reportUnknownVariableType]
             return schema_type(result[0])  # type: ignore[call-arg]
 
+    @overload
+    def select_value_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[Connection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Optional[Any]": ...
+    @overload
+    def select_value_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[Connection]" = None,
+        schema_type: "type[T]",
+        **kwargs: Any,
+    ) -> "Optional[T]": ...
     def select_value_or_none(
         self,
         sql: str,
@@ -314,6 +424,28 @@ class AdbcDriver(SyncArrowBulkOperationsMixin["Connection"], SyncDriverAdapterPr
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             return cursor.rowcount if hasattr(cursor, "rowcount") else -1
 
+    @overload
+    def insert_update_delete_returning(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[Connection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "dict[str, Any]": ...
+    @overload
+    def insert_update_delete_returning(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[Connection]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "ModelDTOT": ...
     def insert_update_delete_returning(
         self,
         sql: str,