sqlspec 0.9.0__tar.gz → 0.10.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlspec
-Version: 0.9.0
+Version: 0.10.0
 Summary: SQL Experiments in Python
 Author-email: Cody Fincher <cody@litestar.dev>
 Maintainer-email: Litestar Developers <hello@litestar.dev>
@@ -41,6 +41,7 @@ Requires-Dist: oracledb; extra == 'oracledb'
 Provides-Extra: orjson
 Requires-Dist: orjson; extra == 'orjson'
 Provides-Extra: performance
+Requires-Dist: msgspec; extra == 'performance'
 Requires-Dist: sqlglot[rs]; extra == 'performance'
 Provides-Extra: psqlpy
 Requires-Dist: psqlpy; extra == 'psqlpy'
@@ -83,6 +84,149 @@ 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(?)",
+        "Can you write a haiku about DuckDB?",
+        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.
@@ -110,7 +254,7 @@ This list is not final. If you have a driver you'd like to see added, please ope
 | [`oracledb`](https://oracle.github.io/python-oracledb/)                                                      | Oracle     | Async   | ✅         |
 | [`oracledb`](https://oracle.github.io/python-oracledb/)                                                      | Oracle     | Sync    | ✅         |
 | [`duckdb`](https://duckdb.org/)                                                                               | DuckDB     | Sync    | ✅         |
-| [`bigquery`](https://googleapis.dev/python/bigquery/latest/index.html)                                        | BigQuery   | Sync    | 🗓️ |
+| [`bigquery`](https://googleapis.dev/python/bigquery/latest/index.html)                                        | BigQuery   | Sync    | ✅ |
 | [`spanner`](https://googleapis.dev/python/spanner/latest/index.html)                                         | Spanner    | Sync    | 🗓️  |
 | [`sqlserver`](https://docs.microsoft.com/en-us/sql/connect/python/pyodbc/python-sql-driver-for-pyodbc?view=sql-server-ver16) | SQL Server | Sync    | 🗓️  |
 | [`mysql`](https://dev.mysql.com/doc/connector-python/en/connector-python-api-mysql-connector-python.html)     | MySQL      | Sync    | 🗓️  |
@@ -121,7 +265,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.10.0}/README.md

@@ -22,6 +22,149 @@ 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(?)",
+        "Can you write a haiku about DuckDB?",
+        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.
@@ -49,7 +192,7 @@ This list is not final. If you have a driver you'd like to see added, please ope
 | [`oracledb`](https://oracle.github.io/python-oracledb/)                                                      | Oracle     | Async   | ✅         |
 | [`oracledb`](https://oracle.github.io/python-oracledb/)                                                      | Oracle     | Sync    | ✅         |
 | [`duckdb`](https://duckdb.org/)                                                                               | DuckDB     | Sync    | ✅         |
-| [`bigquery`](https://googleapis.dev/python/bigquery/latest/index.html)                                        | BigQuery   | Sync    | 🗓️ |
+| [`bigquery`](https://googleapis.dev/python/bigquery/latest/index.html)                                        | BigQuery   | Sync    | ✅ |
 | [`spanner`](https://googleapis.dev/python/spanner/latest/index.html)                                         | Spanner    | Sync    | 🗓️  |
 | [`sqlserver`](https://docs.microsoft.com/en-us/sql/connect/python/pyodbc/python-sql-driver-for-pyodbc?view=sql-server-ver16) | SQL Server | Sync    | 🗓️  |
 | [`mysql`](https://dev.mysql.com/doc/connector-python/en/connector-python-api-mysql-connector-python.html)     | MySQL      | Sync    | 🗓️  |
@@ -60,7 +203,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.10.0}/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.10.0"
 
 [project.optional-dependencies]
 adbc = ["adbc_driver_manager", "pyarrow"]
@@ -24,7 +24,7 @@ msgspec = ["msgspec"]
 nanoid = ["fastnanoid>=0.4.1"]
 oracledb = ["oracledb"]
 orjson = ["orjson"]
-performance = ["sqlglot[rs]"]
+performance = ["sqlglot[rs]", "msgspec"]
 psqlpy = ["psqlpy"]
 psycopg = ["psycopg[binary,pool]"]
 pydantic = ["pydantic", "pydantic-extra-types"]
@@ -109,7 +109,7 @@ packages = ["sqlspec"]
 allow_dirty = true
 commit = false
 commit_args = "--no-verify"
-current_version = "0.9.0"
+current_version = "0.10.0"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"

{sqlspec-0.9.0 → sqlspec-0.10.0}/sqlspec/__init__.py

@@ -1,4 +1,4 @@
-from sqlspec import adapters, base, exceptions, extensions, filters, typing, utils
+from sqlspec import adapters, base, exceptions, extensions, filters, mixins, typing, utils
 from sqlspec.__metadata__ import __version__
 from sqlspec.base import SQLSpec
 
@@ -10,6 +10,7 @@ __all__ = (
     "exceptions",
     "extensions",
     "filters",
+    "mixins",
     "typing",
     "utils",
 )

{sqlspec-0.9.0 → sqlspec-0.10.0}/sqlspec/adapters/adbc/__init__.py

@@ -1,7 +1,8 @@
 from sqlspec.adapters.adbc.config import AdbcConfig
-from sqlspec.adapters.adbc.driver import AdbcDriver
+from sqlspec.adapters.adbc.driver import AdbcConnection, AdbcDriver
 
 __all__ = (
     "AdbcConfig",
+    "AdbcConnection",
     "AdbcDriver",
 )

{sqlspec-0.9.0 → sqlspec-0.10.0}/sqlspec/adapters/adbc/config.py

@@ -2,9 +2,7 @@ from contextlib import contextmanager
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Callable, Optional, Union, cast
 
-from adbc_driver_manager.dbapi import Connection
-
-from sqlspec.adapters.adbc.driver import AdbcDriver
+from sqlspec.adapters.adbc.driver import AdbcConnection, AdbcDriver
 from sqlspec.base import NoPoolSyncConfig
 from sqlspec.exceptions import ImproperConfigurationError
 from sqlspec.typing import Empty, EmptyType
@@ -18,7 +16,7 @@ __all__ = ("AdbcConfig",)
 
 
 @dataclass
-class AdbcConfig(NoPoolSyncConfig["Connection", "AdbcDriver"]):
+class AdbcConfig(NoPoolSyncConfig["AdbcConnection", "AdbcDriver"]):
     """Configuration for ADBC connections.
 
     This class provides configuration options for ADBC database connections using the
@@ -33,20 +31,16 @@ class AdbcConfig(NoPoolSyncConfig["Connection", "AdbcDriver"]):
     """Additional database-specific connection parameters"""
     conn_kwargs: "Optional[dict[str, Any]]" = None
     """Additional database-specific connection parameters"""
-    connection_type: "type[Connection]" = field(init=False, default_factory=lambda: Connection)
+    connection_type: "type[AdbcConnection]" = field(init=False, default_factory=lambda: AdbcConnection)
     """Type of the connection object"""
     driver_type: "type[AdbcDriver]" = field(init=False, default_factory=lambda: AdbcDriver)  # type: ignore[type-abstract,unused-ignore]
     """Type of the driver object"""
-    pool_instance: None = field(init=False, default=None)
+    pool_instance: None = field(init=False, default=None, hash=False)
     """No connection pool is used for ADBC connections"""
-    _is_in_memory: bool = field(init=False, default=False)
-    """Flag indicating if the connection is for an in-memory database"""
 
     def _set_adbc(self) -> str:  # noqa: PLR0912
         """Identify the driver type based on the URI (if provided) or preset driver name.
 
-        Also sets the `_is_in_memory` flag for specific in-memory URIs.
-
         Raises:
             ImproperConfigurationError: If the driver name is not recognized or supported.
 
@@ -143,7 +137,7 @@ class AdbcConfig(NoPoolSyncConfig["Connection", "AdbcDriver"]):
             config["conn_kwargs"] = conn_kwargs
         return config
 
-    def _get_connect_func(self) -> "Callable[..., Connection]":
+    def _get_connect_func(self) -> "Callable[..., AdbcConnection]":
         self._set_adbc()
         driver_path = cast("str", self.driver_name)
         try:
@@ -166,7 +160,7 @@ class AdbcConfig(NoPoolSyncConfig["Connection", "AdbcDriver"]):
             raise ImproperConfigurationError(msg)
         return connect_func  # type: ignore[no-any-return]
 
-    def create_connection(self) -> "Connection":
+    def create_connection(self) -> "AdbcConnection":
         """Create and return a new database connection using the specific driver.
 
         Returns:
@@ -189,7 +183,7 @@ class AdbcConfig(NoPoolSyncConfig["Connection", "AdbcDriver"]):
             raise ImproperConfigurationError(msg) from e
 
     @contextmanager
-    def provide_connection(self, *args: "Any", **kwargs: "Any") -> "Generator[Connection, None, None]":
+    def provide_connection(self, *args: "Any", **kwargs: "Any") -> "Generator[AdbcConnection, None, None]":
         """Create and provide a database connection using the specific driver.
 
         Yields: